API Documentation

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

Prerequisites

Getting started

This documentation is for our JavaScript client library, pushradar.js, and covers subscribing to channels and receiving messages in realtime. It should be paired with one of our server libraries (see above) or cURL.

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>
In the example above, whenever a message is broadcast on the channel 'channel-1', the message content is 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');

Registering an authentication endpoint

Private channels require subscribers to be authenticated before they can receive messages broadcast on them. Authenticating users is recommended for security to ensure that only the intended recipient(s) receive messages broadcast on certain channels. You can 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');
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"});

Fallback mechanisms

At this time, PushRadar supports 97.72% of all browsers currently in use across all devices; any browser that supports WebSockets can connect to PushRadar's servers. We do not implement fallback mechanisms for the few browsers that do not support WebSockets. We recommend performing a browser check for support of WebSockets, reverting to your own custom fallback system if it fails.
You can check if WebSockets are supported on a user's browser by calling the is.supported() method of the PushRadar object:
JavaScript
if (!radar.is.supported()) {
    // Prompt the user to upgrade their browser to one which supports WebSockets
    // or implement your own fallback system here
}