PushRadar's JavaScript Library

Welcome to PushRadar's documentation for our JavaScript client library. This article covers subscribing to channels, and receiving notifications published to those channels in realtime.

(JavaScript)PushRadar.js

PushRadar's JavaScript client library, pushradar.js should be included above the closing </body> tag of all your webpages:

<script src="//www.pushradar.com/pushradar.js"></script>

After you have linked to the above library, you can get started subscribing to channels.

You will need to use a server library to broadcast notifications. We have produced server libraries for PHP, Node.js, .NET, Ruby and Python. You can also use cURL to broadcast notifications.

(client)"Hello World!" example

The following example demonstrates subscribing to a channel called test-channel and receiving a message broadcast on it (for this example, the message "Hello World!"). Replace your-api-key with your actual PushRadar API key, which may be obtained from the API page of your dashboard.

  • JavaScript
<script src="//www.pushradar.com/pushradar.js"></script>
<script>
    var radar = new PushRadar("your-api-key");
    radar.subscribe.to("test-channel", function (notification) {
        alert(notification.message); // "Hello World!"
    });
</script>
(channels)Subscribing to channels

As you have seen from the code above, subscribing to channels is as easy as calling the subscribe to method on the PushRadar instance, passing in the channel name and a callback which receives a notification when one is broadcast on that channel.

Channel names cannot contain spaces, and by convention are lowercase and alphanumerical (a-z0-9), with dashes separating words, e.g. custom-channel-20. Optionally, you can specify events in channel names using a colon character, for instance messages:new

The example below shows how to subscribe to multiple channels:

  • JavaScript
<script src="//www.pushradar.com/pushradar.js"></script>
<script>
    var radar = new PushRadar("your-api-key");
    radar.subscribe.to("first-channel", function (notification) {
        alert(notification.message);
    });

    radar.subscribe.to("second-channel", function (item) {
        alert(item.height);
    });
</script>
(feature)User targeting & private channels

By convention, a channel named private-user:{userID} should receive notifications targeted to the currently authenticated user in your website or web app, replacing {userID} with the user's actual ID. If a user is logged into your website or web app, register their user ID by calling the setUserID method of the PushRadar object as well.

private-user:{userID} is an example of a private channel as it starts with 'private-'. Private channels require authentication before users can receive messages on them. Set up an authentication endpoint which returns the JSON object {authToken: radar.channelAuth("private-channel-name")} if the user is allowed to join that channel. See the section on channel authentication in the server library documentation for more information.

For this example, we are going to use one of PushRadar's server libraries to broadcast a new message to the user with ID usr100, and then receive that notification client-side using JavaScript.

  • PHP
  • Node.js
  • .NET
  • Ruby
  • Python
  • curl
use PushRadar\PushRadar;

$radar = new PushRadar("your-secret-key");
$radar->targetUser("usr100")->addDataItems(array(
    "message" => "Hey there, from Sam!",
    "sender_name" => "Sam"
))->broadcast("private-user:usr100");
  • JavaScript
<script src="//www.pushradar.com/pushradar.js"></script>
<script>
    // Set user ID on initialization
    var radar = new PushRadar("your-api-key", "usr100");

    // ... or ... radar.setUserID("usr100");

    // Set the authentication endpoint URL ... it should return a JSON object:
    // {authToken: radar.channelAuth("private-user:usr100")}
    radar.setAuthenticationEndpoint("your-auth-endpoint-url");

    radar.subscribe.to("private-user:usr100", function(notification) {
        alert("New message from " + notification.sender_name); // "New message from Sam"
    });
</script>

If your website or web app uses ajax navigation and doesn't refresh the page when users log out, make sure to call radar.setUserID(null); when a user logs out.

(feature)Setting endpoint headers

You may need to set headers for authentication endpoint requests, for instance if your authentication endpoint requires a CSRF token. You can do this using the setHeaders method of the PushRadar object:

  • JavaScript
// ... var radar = new PushRadar(...)
radar.setHeaders({
    'X-CSRF-Token': "your-csrf-token"
});
(feature)Presence channels

Presence channels start with the prefix 'presence-' and like private channels, they require authentication. Presence channels are eligible for presence messages from PushRadar, notifying you about how many subscribers there are currently on the channel, and giving you data that has been passed through as extra presence data for a given user.

You can call radar.setExtraPresenceData({...}) to pass through extra presence data.

The example below shows you how to register an onPresence callback to receive presence messages on a channel. The userData parameter will be an array of objects, each one representing a user. By default, the user objects contain a userID and any extra presence data fields that have been set.

  • JavaScript
var radar = new PushRadar("your-api-key");

// Set the authentication endpoint URL ... it should return a JSON object:
// {authToken: radar.channelAuth("presence-test-channel")}
radar.setAuthenticationEndpoint("your-auth-endpoint-url");

radar.subscribe.to("presence-test-channel", function (notification) {
    alert(notification.message);
}).onPresence(function(userData, count) {
    alert(count + " users are currently subscribed to this channel.");
});
(feature)Action targeting

PushRadar allows you to target notifications to visitors or users who have, or have not, taken a certain action on your website or web app. You can track actions the current visitor/user has taken by calling the action method, passing in an action identifier:

  • JavaScript
// ... var radar = new PushRadar(...)
radar.track.action("purchased-item-#11");

To track multiple actions, you can call the actions method, passing in an array of action identifiers:

  • JavaScript
// ... var radar = new PushRadar(...)
radar.track.actions(["purchased-item-#11", "subscribed-newsletter"]);

To remove an action, simply call the untrack action method, or to remove multiple actions, the untrack actions method:

  • JavaScript
// ... var radar = new PushRadar(...)
radar.untrack.action("subscribed-newsletter");
radar.untrack.actions(["my-action", "another-action"]);

To check whether a user has taken a given action, call the has action method as follows:

  • JavaScript
// ... var radar = new PushRadar(...)
radar.has.action("subscribed-newsletter-#3"); // false
(data)PushRadar and Local Storage

PushRadar's JavaScript client library relies on HTML5 Local Storage for core targeting functionality. Items set in Local Storage are prefixed with "pushradar-ls-".

You should state in your website's privacy policy that you collect the following types of personal information from your visitors or users:

  • (a)their IP address, geographical location, browser type and version, information about actions they have taken and other information.

This is done for the purpose of providing realtime functionality on your service.

If you need any assistance setting up, please do not hesitate to contact us.