Getting started with Cometify

» This documentation
» Your environment
» How the Cometify service works, HTML 5 WebSockets and Comet
» Embed the Cometify JavaScript and set up a listener
» Generate secureKey for the listener
» POST data to create the push
» JavaScript and POST examples (code snippets)

This documentation

Go to the table of contents

This documentation is provided as is and will be changed during the development process of Cometify. The Cometify web push service is currently in the very early stages and may contain several bugs or features that will need to be tweaked. If you have any suggestions to how the API or how the service can be improved, feel free to come and say "Hey, dude! Let's do it like this to improve yada yada...".

With that said I believe that we can start this little guide to help you getting started, create your first push message and fetch it with a listener.

Your environment

Go to the table of contents

Let's start with something that's most likely no problem, but make sure that your visitors, if you are developing for a relatively closed down application, can connect to *.cometify.org on port 80, 443, 8081 and port 2323 (That's where our WebSocket-server is) and that your server(s) that want to push the data has it's firewall opened up for cometify.org, port 80 or 443 (if you want to push via HTTPS / SSL).

How the Cometify service works, HTML 5 WebSockets and Comet

Go to the table of contents

We use identifiers so we can push different messages to different users, pages or websites. Each push contains the identifier-name together with the message and each client listener will listen for pushed messages on one or more specific identifiers.

If you wish, identifiers can be secured with a generated password so that secure pushes to that identifier can only be read when the listener has this password. Of course, this is all up to you and what data you may want to push out to your visitors.

An identifier (or channel if you prefer) is what the browsers will listen on or that the server pushes to. An identifier is 1-60 characters long and consists of the characters a-z, A-Z, 0-9 and underscore but may not start with a digit or underscore. (regexp /^[a-zA-Z][a-zA-Z0-9_]{0,59}/). An identifier is NOT case sensitive.

Embed the Cometify JavaScript and set up a listener

Go to the table of contents

As soon as a browser with JavaScript support gets the above JavaScript code, a listener will be created to listen on the chosen identifiers. Our JavaScript and server will take care of everything regarding the communication between the browser and our server using HTML 5 WebSockets or Comet techniques if the webbrowser doesn't support WebSockets. Don't worry, you don't need to make a choice here; everything is automated, for your pleasure. As a note, there can be a maximum of 30 listeners from the same IP connected at the same time. If you have needs for more listeners/browsers at the same network, sharing the same IP it's totally possible to increase the limits for your account.

Let's take a look at the code above and explain the different parameters.
The identifiers (required) value can be a string (i.e. 'chat'); or identifiers value can be a JSON array of strings (i.e. ['metrics', 'tweets']).
Format: regexp /^[a-zA-Z][a-zA-Z0-9_]{0,59}/ identifiers with internal_id (optional) can look like this {metrics: 59, tweets: 100}. When set the listener will listen to all pushes with a higher push_id than your internal_id for this identifier, also all earlier pushes from the latest 3 minutes on the same identifier with a higher push_id will be returned connect. Please note that you can not use internal id:s if you want to use regular identifiers (described above). If internal id == 0 is set, the listener will return all pushes from the latest ten minutes on this identifier. This value is related to the push_id parameter when pushing data. internal id is the eventual push_id, identifier is the identifier for which the push comes from. Sometimes new data can be inserted into your database right between the moment that your script executed and the moment when the clients browser started listening for pushed messages - Use this option if it's important for your application that the client receives all information. Please note that 3 minutes after the push, the data will be invalidated and cannot be received by the listener. As you might notice, this is a bit tricky and we'll go through some examples at the bottom of the documentation (examples coming soon). ADVANCED USE callback (required) is the name of the JavaScript function to handle the pushed data. It can either be defined inline or as a string with the function name. the function takes three arguments; (data, id, identifier) where data is the pushed text. secureKey (optional) is a md5 hex generated from the formula md5hex([API key] + [API secret] + md5hex([identifiers, comma separated])) secureKey example; API key = 1, API secret = 'c1h89chHaka9s1', identifiers = ['metrics', 'tweets'] will create the secureKey value md5hex('1' + 'c1h89chHaka9s1' + md5hex('metrics,tweets')) = 'd6d02dbf813a87619a1ab325878942b0'. secureKey value is optional and only needed to listen to pushed messages that are flagged as "secret". That's pretty much there is to it. If you've set up everything correct you should have a listener up and running. If you're having trouble generating the secretKey for the identifiers, we'll give you a hand. Right here, below.
Your identifiers, comma separated (no spaces!): Your API key: Your API secret: GENERATED SECURE KEY: FILL IN THE FIELDS TO GENERATE

POST data to create the push
Go to the table of contents

Having set up a listener now it's time to actually create the push message. This is being done by a POST request to http://cometify.org/[API key]/push/[identifier] (also works with HTTPS if you want a SSL protected push) - together with some parameters.

POST parameters to send are the following
identifier (required) value as a string (i.e. 'chat'), it's not possible to send a single push to multiple identifiers.
Format: regexp /^[a-zA-Z][a-zA-Z0-9_]{0,59}/ push_id (optional), an integer value, is optional and could be used as your internal id for this push. As you have already read about the identifiers with internal id parameter on the identifier, you might get a clue about the usage. This is great to use if it's important that the client receives all data (otherwise data can be lost during the few seconds your site has loaded and the browser has connected to Cometify). ADVANCED USE secret (required) is either 0 or 1. If set to 0 then the listener won't need to provide secretKey to receive this push. If set to 1 then the listener need to provide a correct secretKey. Please note that if secret = 0, anyone that knows your API key and identifier can listen to your push anytime, anywhere. text (required) is the message you want to push to the listeners. It can maximum be 64 kilobytes. secure (required) is a md5 hex generated from the formula md5hex([API key] + md5hex([API secret]) + [identifier] + [text]). secure example; API key = 1, API secret = 'c1h89chHaka9s1', identifier = 'visitors', text = '284 people' will create the secure value = md5hex('1' + md5hex('c1h89chHaka9s1') + 'visitors' + '284 people') = '149f26540f697a97e886e2527466c6e8' Remember to follow URI-standards and urlencode your parameters and values.

JavaScript and POST examples
Go to the table of contents


<script src="https://cometify.org/latest/cometify.min.js"></script>
<script>
    // Using the API secret: 'dj28DNam!!nx72*'

    Cometify.init({
        apiKey: 37282591,
        identifiers: ['guestbook', 'comments', 'oneliner'],
        secureKey: '5b70b14ea396f689a1b9550ba66025bc',
        callback: 'cometifyCallback'
    }).start();

    function cometifyCallback(data, id, identifier) {
        alert('Data: ' + data + '; Identifier: ' + identifier);
    }
</script>

<?php /* PHP POST example */ ?>
<?php
    $hostname = 'cometify.org';
    $apiKey = 37282591;
    $apiSecret = 'dj28DNam!!nx72*';
    $text = 'Hello world!';
    $identifier = 'oneliner';

    $secure = md5($apiKey . md5($apiSecret) . $identifier . $text);

    $data = array(
        'identifier' => $identifier,
        'secret' => 1,
        'text' => $text,
        'secure' => $secure,
    );

    $request = "";
    foreach ($data as $key => $value) {
        if ($request) $request .= "&";
        $request .= urlencode($key) . '=' . urlencode($value);
    }

    $packet = "POST http://{$hostname}/{$api_key}/push/{$identifier} HTTP/1.1\r\n"
     . "Host: {$hostname}\r\n"
     . "Content-type: application/x-www-form-urlencoded\r\n"
     . "Content-length: " . strlen("{$request}") . "\r\n"
     . "Connection: Close\r\n\r\n"
     . "{$request}";

    $fp = fsockopen($hostname, 80);
    fwrite($fp, $packet);
    fclose($fp);
?>

And that's it, you're live, in real time!
Go to the table of contents

Got questions, ideas, suggestions, "nothing is working", "what the hell is this?", etc. Feel free to contact me at carloscar@agigen.se.

Good luck!

Getting started with Cometify

Table of contents

This documentation

Your environment

How the Cometify service works, HTML 5 WebSockets and Comet

Embed the Cometify JavaScript and set up a listener

POST data to create the push

JavaScript and POST examples

And that's it, you're live, in real time!