Step 1 - Link the CosmJS file

First step is to link the javascript file which has the library’s code. Fortunately we host the file on a CDN (Content Delivery Network) so you don’t have to worry about hosting it and it’s likely faster.

Note: One thing to keep in mind, CosmJS requires jQuery so it must be linked before CosmJS on the HTML page.

The file has to be linked after jQuery and before your script, like so:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
<script src="http://d23cj0cdvyoxg0.cloudfront.net/cosmjs-1.0.0.min.js"></script>
<script>
  // Your code
</script>

→ We recommend linking all javascript files just before the end of the body tag (</body>).

Step 2 - Set the API key

This has to be done always and before using any of the methods since it’s required for any interaction with the Cosm API.

If you don’t know how to get a key, log in to Cosm and go to Keys (on top right user menu) — then click “+ Key” for adding a new key — give it a name and click Create. You’ll need the long string of random characters.

On the beginning of your script and before any CosmJS method, paste this code and replace where needed:

// Set the Cosm API key
cosm.setKey( "PASTE_YOUR_KEY_HERE" );

Now you can use any CosmJS method!

Step 3 - Get data and subscribe to updates

All the setup is done, it’s time to start using some methods!

Note: Getting data from Cosm is done asynchronously with AJAX requests which means that the rest of your script will continue executing while we wait for Cosm to send the information back to us. This is important because you need to specify what should be done when the data comes back using a function, commonly referred to as a “callback”.

Here’s the code, with comments explaining the process:

// Make sure the document is ready to be handled
$(document).ready(function($) {

  // Set the Cosm API key (https://cosm.com/users/YOUR_USERNAME/keys)
  cosm.setKey( "PASTE_YOUR_KEY_HERE" );

  // Replace with your own values
  var feedID        = 61916,          // Feed ID
      datastreamID  = "sine60";       // Datastream ID
      selector      = "#myelement";   // Your element on the page

  // Get datastream data from Cosm
  cosm.datastream.get (feedID, datastreamID, function ( datastream ) {
    // WARNING: This code is only executed when we get a response back from Cosm, 
    // it will likely execute after the rest your script
    //
    // NOTE: The variable "datastream" will contain all the datastream information 
    // as an object,the structure can be found at: 
    // http://cosm.com/docs/v2/datastream/show.html#examples

    // Display the current value from the datastream
    $(selector).html( datastream["current_value"] );

    // Getting realtime! 
    // The function associated with the subscribe method will be executed 
    // every time there is an update to the datastream
    cosm.datastream.subscribe( feedID, datastreamID, function ( event , datastream_updated ) {
      // Display the current value from the updated datastream
      $(selector).html( datastream_updated["current_value"] );
    });

  });

  // WARNING: Code here will continue executing while we get the datastream data from Cosm, 
  // use the function associated with datastream.get to work with the data 
  // once the request is complete
});