Application Events

Applications may receive notifications from the Core Service. Notifications are broadcast over a long-poll HTTP request using the Basic HTTP Push Relay Protocol which provides for live and deferred message handling.

Getting your Channel

Channels are long, extremely difficult to guess URLs which contain an identifier unique to your application. In order to retrieve your application’s channel you will need to make a signed API call to the following endpoint:

http://auth.bravecollective.net/api/live/channel

You will receive a response containing a channel key which is the URL you will need to poll for events.

Messages within your channel can only physically be sent by the core service; this alleviates the need for per-message cryptographic operations.

Messaging

Users may wish to receive push notifications; your application may implement a message delivery endpoint and listen for the following message structure:

{
    kind: "message",
    sender: "<id>",
    recipients: ["<id>", …],
    priority: int,  // -2 to 2
    event: "<str>",
    title: "<str>",
    message: "<str>",
    action: "<url>"
}

The keys represent:

• kind — identifies this push notification as a broadcast message
• sender — the ID of the application which sent the message
• recipients — a list of API authorization tokens that the message is being directed at
• priority — an optional number between -2 and 2 representing the priority, roughly: idle, info, normal, warning, critical.
• event — a textual, dot-notation notification identifier for the message
• title — optional title for the notification, useful for window titles or e-mail subjects
• message — the body of the message, plain text (and may contain newlines)
• action — an optional URL which the user can use to react to the message

These keys are optional and may not be present in the message: priority, event, title, action. If missing, priority defaults to zero.