API Documentation

Home  API Docs  .NET
This is documentation for the latest version of PushRadar's API, v3.x (2021)

Prerequisites

Getting started

This guide assumes you are using the NuGet dependency manager. You can find out more at https://www.nuget.org.
Package Manager
Install-Package PushRadar
Within Visual Studio, go to Tools > NuGet Package Manager > Package Manager Console and enter the above command to install version 3 of PushRadar.

How it works

PushRadar is a realtime API service. It allows you to broadcast data form your server, and receive it in realtime on the front-end of your website or web app. It is essentially a publish-subscribe system; you publish (broadcast) messages on 'channels' that are listened to by 'subscribers' on the front-end. Subscribers receive data in realtime and can use it to update the UI, for example.
PushRadar offers millisecond performance at scale, and includes a range of measures to ensure that message content and transport is kept secure at all times.

Broadcasting messages

C#.NET
var radar = new PushRadar.PushRadar("your-secret-key");
radar.BroadcastAsync("channel-1", new Dictionary<string, object>() {
    { "message", "Hello world!" }
});
Once you have included the library from NuGet, create a new instance of the PushRadar object, passing in your secret key, which can be found on the API page of your dashboard.
To broadcast data from your server, call the BroadcastAsync() method on the PushRadar instance, passing in the name of the channel to broadcast on, in this case, 'channel-1', and the data to broadcast as a dictionary, in this case one containing just the message 'Hello world!'.
Note that channel names cannot contain spaces, and must consist of only upper and lowercase letters, numbers, underscores, equals characters, @ characters, commas, periods, semicolons, and hyphens (A-Za-z0-9_=@,.;-).

Receiving messages

To receive messages client-side in realtime, first link to the pushradar.js library. Insert the following code before any other JavaScript code in the <head> section of every page of your website or web app:
HTML
<script src="https://pushradar.com/js/v3/pushradar.min.js"></script>
Then, create a new PushRadar instance, passing in your public key, which can be found on the API page of your dashboard. Subscribe to channels by calling the subscribe.to() method on the PushRadar instance, passing in a callback that will be executed when a new message is received, as shown below.
HTML
<script src="https://pushradar.com/js/v3/pushradar.min.js"></script>
<script>
    var radar = new PushRadar('your-public-key');
    radar.subscribe.to('channel-1', function (data) {
        console.log(data.message);
    });
</script>
Give it a try! Trigger the broadcast code from your server and you should see the message 'Hello world!' written to the console.

Subscribing to multiple channels

You can subscribe to multiple channels as shown below:
JavaScript
var radar = new PushRadar('your-public-key');
radar.subscribe.to('channel-1', function (data) {
    console.log(data.message);
});

radar.subscribe.to('channel-2', function (data) {
    console.log(data.message);
});

Unsubscribing from channels

You can unsubscribe from channels by calling the unsubscribe.from() method on the PushRadar object:
JavaScript
radar.unsubscribe.from('channel-1');

Authenticating users

Private and presence channels require subscribers to be authenticated before they can receive messages broadcast on them. Authenticating users ensures that only the intended recipient(s) receive messages broadcast on certain channels. First of all, register an authentication endpoint client-side by calling the auth() method of the PushRadar object, passing in the url of your authentication endpoint:
JavaScript
radar.auth('/auth');
PushRadar will do a GET request to the authentication endpoint (in this case /auth) when a client subscribes to a private channel. PushRadar will pass in the name of the channel as a query string parameter under the key channelName and the socket ID under the key socketID. Your authentication endpoint should check whether the user who is currently logged in can access the channel being subscribed to. If they can, in your server-side code call the Auth() method of the PushRadar object, passing in the name of the channel and the socket ID, and return the response as a JSON object under the key token.
The code below is a starting point for your authentication endpoint code. For example, this code would be triggered by a GET request to /auth:
C#.NET
var radar = new PushRadar.PushRadar("your-secret-key");
var channelName = HttpContext.Current.Request.QueryString["channelName"];
var socketID = HttpContext.Current.Request.QueryString["socketID"];

if (/* is user allowed to access channel? */ true) {
    var kvp = new KeyValuePair<string, object>("token", radar.Auth(channelName, socketID));
    return Json(kvp);
}
If you need to pass any extra headers to your authentication endpoint, for example in case you need to add a CSRF token, you can use the headers() method of the PushRadar object, client-side:
JavaScript
radar.headers({"X-CSRF-TOKEN": "your-csrf-token"});

Private channels

Private channels require authentication and start with the prefix private-. We recommend that you use private channels by default to prevent unauthorised access to channels. Setting up private channels is as easy as publishing/subscribing to channels with names beginning with private-, and setting up an authentication endpoint as discussed above.
Here is a complete implementation of a private 'hello world' setup, allowing only the user with ID 1 to access messages on private-channel-1:
HTML
<script src="https://pushradar.com/js/v3/pushradar.min.js"></script>
<script>
    var radar = new PushRadar('your-public-key');
    radar.auth('/auth');
    radar.subscribe.to('private-channel-1', function (data) {
        console.log(data.message);
    });
</script>
C#.NET
using System;
using System.Collections.Generic;
using System.Text;
using System.Net;
using System.Web;
using System.Web.Mvc;
using System.Web.Script.Serialization;

namespace Application1.Controllers
{
    public class SiteController : Controller
    {
        public EmptyResult Broadcast()
        {
            var radar = new PushRadar.PushRadar("your-secret-key");
            radar.BroadcastAsync("private-channel-1", new Dictionary<string, object>() {
                { "message", "Hello world!" }
            });

            return new EmptyResult();
        }

        public ActionResult Auth()
        {
            var radar = new PushRadar.PushRadar("your-secret-key");
            var channelName = HttpContext.Current.Request.QueryString["channelName"];
            var socketID = HttpContext.Current.Request.QueryString["socketID"];

            /* is user allowed to access channel? */
            if (HttpContext.Current.User.Identity.GetUserId() == 1 && channelName == "private-channel-1") {
                var kvp = new KeyValuePair<string, object>("token", radar.Auth(channelName, socketID));
                return Json(kvp);
            } else {
                return new HttpStatusCodeResult(HttpStatusCode.Forbidden);
            }
        }
    }
}

Presence channels

Presence channels are channels which are eligible for 'presence messages' containing information about channel subscribers. Presence channels require authentication and start with the prefix presence-. Setting up presence channels is as easy as publishing/subscribing to channels with names beginning with presence-, setting up an authentication endpoint and registering an onPresence(...) callback which periodically receives subscriber count and subscriber data.
Here is a complete implementation of a presence 'hello world' setup, which logs the number of subscribers of presence-channel-1 to the console every 5 seconds:
HTML
<script src="https://pushradar.com/js/v3/pushradar.min.js"></script>
<script>
    var radar = new PushRadar('your-public-key');
    radar.auth('/auth');
    radar.call.on.connection('/connected');

    radar.subscribe.to('presence-channel-1', function (data) {
        console.log(data.message);
    }).onPresence(function (count, clientData) {
        console.log(count);
    });
</script>
C#.NET
using System;
using System.Collections.Generic;
using System.Text;
using System.Net;
using System.Web;
using System.Web.Mvc;
using System.Web.Script.Serialization;

namespace Application1.Controllers
{
    public class SiteController : Controller
    {
        public EmptyResult Broadcast()
        {
            var radar = new PushRadar.PushRadar("your-secret-key");
            radar.BroadcastAsync("presence-channel-1", new Dictionary<string, object>() {
                { "message", "Hello world!" }
            });

            return new EmptyResult();
        }

        public ActionResult Auth()
        {
            var radar = new PushRadar.PushRadar("your-secret-key");
            var channelName = HttpContext.Current.Request.QueryString["channelName"];
            var socketID = HttpContext.Current.Request.QueryString["socketID"];

            /* is user allowed to access channel? */
            if (HttpContext.Current.User.Identity.GetUserId() == 1 && channelName == "presence-channel-1") {
                var kvp = new KeyValuePair<string, object>("token", radar.Auth(channelName, socketID));
                return Json(kvp);
            } else {
                return new HttpStatusCodeResult(HttpStatusCode.Forbidden);
            }
        }

        public EmptyResult Connected()
        {
            var radar = new PushRadar.PushRadar("your-secret-key");
            var socketID = HttpContext.Current.Request.Form["socketID"];
            radar.RegisterClientDataAsync(socketID, new Dictionary<string, object>() {
                { "##uniqueID", 1 },
                { "name", "James Smith" }
            });

            return new EmptyResult();
        }
    }
}
In the example above, client data is registered when a user is first connected (the /connected endpoint passed to call.on.connection(...) is called). The client data is passed through to the onPresence(...) callback as subscriber data. Client data can be anything you like, up to a maximum size of 1KiB per client. For instance, you could register a user's ID. If you have a unique identifier for each user, you can use the special ##uniqueID property to count multiple subscribers with the same unique ID as a single subscriber.

PushRadar .NET on GitHub