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"});

Calling a URL on connection

If you wish for a endpoint to be called when a user first connects to the service, you can use the call.on.connection(...) method, passing in the desired URL. This can be useful if you wish to register client data on connection. Note that if the connection drops and recovers, the connection endpoint will be called again.
JavaScript
radar.call.on.connection('/connected');

Client-client broadcasting

PushRadar supports client to client broadcasting. This direct type of broadcasting is especially suitable for low-latency scenarios such as tracking mouse movements, where low millisecond delivery time is essential.
With client to client broadcasting, messages get delivered directly to all subscribers on a given channel apart from the sender. This type of broadcasting requires that you use 'private client' or 'presence client' channels; channel names must start with the prefix private-client- or presence-client-. Additionally, the channels require authentication, like normal private or presence channels.
Note that client to client broadcasting allows users of your site to send messages directly to other users. This may be open to interference, for example, from a malicious user.
Simply call the broadcast() method of the PushRadar object to broadcast data on a channel. Pass in the name of the channel to broadcast on and the data as an object. Note that you must be subscribed to a channel to broadcast on it. Here is a 'Hello world!' example using client-client broadcasting:
JavaScript
var radar = new PushRadar('your-public-key');
radar.auth('/auth');
radar.subscribe.to('private-client-channel-1', function (data) {
    console.log(data.message);
});

radar.broadcast('private-client-channel-1', {'message': 'Hello world!'});
If any client data has been registered for the sender, it will be passed through in the client broadcast under the key ##clientData. You can use this to identify the sender of the client broadcast.

Fallback mechanisms

PushRadar includes a fallback mechanism to support older browsers. If WebSockets are not supported on a client's browser, XHR polling is used automatically. No extra configuration is required, it works out of the box.