Skip to content

Latest commit

 

History

History
133 lines (89 loc) · 5.69 KB

presence.md

File metadata and controls

133 lines (89 loc) · 5.69 KB
Raw

Presence HTTP API Usage

To enable presence during the beta, please send an email to support@pubnub.com with the subscribe key(s) on which you would like to track presence. When the feature is out of beta, customers will be able to manage presence configuration from the account portal on a per-key basis.

Presence data is not stored for long-term history by default, but we can enable this on request.

Addition of UUID on subscribe

For unique clients to be tracked, a UUID should be included with each /subscribe request. The UUID may, in fact, be any string value such as a user name or user ID, but the default string generated by PubNub's client libraries follow the uuid4 spec resembling c05cca54-45ab-49d3-861b-d50fe2be9304. It is recommended the client cache the UUID so that it is consistently used on reconnection. Clients that do not include a UUID will not be counted in presence stats. Do not share this UUID between clients or presence will have inconsistent behavior.

example:

http://pubsub.pubnub.com/subscribe/<sub-key>/<channel>/<callback>/<timetoken>?uuid=<uuid>
http://pubsub.pubnub.com/subscribe/demo/my_channel/0/123456789?uuid=c05cca54-45ab-49d3-861b-d50fe2be9304

Announcing Enter/Leave/Timeout Events

Every API key that enables the presence feature will also be able to subscribe to presence side-channels using the -pnpres suffix (i.e. my_channel-pnpres will have join/leave/timeout events for the channel my_channel). If the number of users subscribed to the channel is high and presence events are frequent it may get too chatty. This feature is recommended for channels with a low number of subscribers, but we put in place no limitations.

An example event message might look like:

{
    action: ‘join',
    uuid: ‘2891723ad908f30d90e’,
    timestamp: 1232342342,
    occupancy: 12
}

Time Interval Occupancy Announcements

This feature is meant to be an alternative to the enter/leave announcements and is better suited for channels with a higher subscriber count. At regular, user-configurable intervals pubnub sends a message containing the current subscriber count. It does not include a uuid list or timestamps.

An example interval announcement message might look like:

{
    occupancy: 1223
}

Current Subscriber List

We provide a REST API for users to query the current occupancy status of the channel on-demand. The response will include the current subscriber count and optionally a list of uuid’s.

Example

http://pubsub.pubnub.com/v2/presence/sub-key/demo/channel/my_channel

Response

{
    occupancy: 4,
    uuids: [
        ‘123123234t234f34fq3dq’,
        ‘143r34f34t34fq34q34q3’,
        ‘23f34d3f4rq34r34rq23q’,
        ‘w34tcw45t45tcw435tww3’,
        ‘w345w34tw34fsers5tsz3’,
    ]
}

Channel Active / Inactive Notifications

A channel becomes active when occupency goes from 0 to >= 1 and becomes inactive with occupancy goes from >=1 to 0. If configured, a notification of this change of state is published to a channel of your choosing and/or PubNub will make a callback to your application server at the URL you configure.

A PubNub messaging notifying you of a channel becoming active would resemble:

{
    "channel":"my_channel", 
    "status":"active", 
    "timestamp":12323425345
}

You application server can have different callbacks for active and inactive. Your web server must accept a POST request with the following parameters.

  • sub_key: string,
  • channel: string,
  • status: string,
  • timestamp: long int

Configurable Options

The following options will eventually be configured in the account portal, but while in BETA will be configured manually by the PubNub team

  • presence_announce_max: The maximum number of occupants in a channel before it switches to interval announcements
  • presence_cb_active: The HTTP callback URL that is triggered when a channel becomes active
  • presence_cb_inactive: The HTTP callback URL that is triggered when a channel becomes inactive
  • presence_interval: When in interval announce mode, the number of seconds between each announcement
  • presence_active_notice_channel: The pubnub channel where active/inactive channel notifications are published

Libraries

Currenly Javascript and Python libraries have extra fuctions added for presence. More libraries are being added. Please feel free to contribute pull requests at http://github.com/pubnub

Javascript

Initializing

You have the option of manually defining the uuid for a client when initializing PUBNUB for the first time. Once a UUID is set, it will be saved in local storage if supported by the browser or in a cookie if not. The uuid parameter is not required and if it is not specified, a uuid will be generated automaticalled and stored in either local storage or a cookie as the brower allows.

<div pub-key="<pub-key>" sub-key="<sub-key>" uuid="<uuid>" id="pubnub"></div>

or alternatively:

var pubnub = PUBNUB.init({
    publish_key   : '<pub-key>',
    subscribe_key : '<sub-key>',
    uuid:         : '<uuid>'
});

Addition of Presence Callback

PUBNUB.subscribe({
    channel    : "hello_world",
    presence   : function(message) {
        console.log("Got a message");
    },
    callback   : function(message) {
        console.log("New channel occupancy: "+message['occupancy'])
    }
});

PUBNUB.here_now() function

PUBNUB.here_now({
    channel:'hello_world', 
    callback:function(message) {
        console.log("Current people here: ", message['uuids']);
    }
}