API Documentation

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

Prerequisites

Getting started

This guide assumes you are using the Pip dependency manager. You can find out more at https://packaging.python.org/tutorials/managing-dependencies.
Terminal
pip install pushradar
Run the command above in your project's root directory to install version 3 of PushRadar's Python server library. Alternatively, if you are using Pipenv, you can run the command pipenv install 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

Python
import pushradar

radar = pushradar.PushRadar('your-secret-key')
radar.broadcast('channel-1', {'message': 'Hello world!'})
Once you have included the library via Pip or Pipenv, create a new PushRadar instance passing in your secret key, which can be found on the API page of your dashboard.
To broadcast data from your server, call the broadcast() method on the PushRadar object passing in the name of the channel to broadcast on, in this case, 'channel-1', and the data to broadcast as an object, in this case 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 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. 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:
Python
radar = pushradar.PushRadar('your-secret-key')
if request.method == 'GET':
    channel_name = request.GET.get('channelName')
    socket_id = request.GET.get('socketID')
    # is user allowed to access channel?
    if True:
        return json.dumps({"token": radar.auth(channel_name, socket_id)})
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>
Python
import pushradar
from django.core.exceptions import PermissionDenied
import json

def broadcast():
    radar = pushradar.PushRadar('your-secret-key')
    radar.broadcast('private-channel-1', {'message': 'Hello world!'})

def auth(request):
    radar = pushradar.PushRadar('your-secret-key')
    if request.method == 'GET':
        channel_name = request.GET.get('channelName')
        socket_id = request.GET.get('socketID')
        # is user allowed to access channel?
        if request.user.id == 1 and channel_name == 'private-channel-1':
            return json.dumps({"token": radar.auth(channel_name, socket_id)})
        else:
            raise PermissionDenied()