Step 1 - Link the XivelyJS 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, XivelyJS requires jQuery so it must be linked before XivelyJS 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/xivelyjs-1.0.4.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 Xively API.

If you don’t know how to get a key, log in to Xively 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 XivelyJS method, paste this code and replace where needed:

// Set the Xively API key
xively.setKey( "PASTE_YOUR_KEY_HERE" );

Now you can use any XivelyJS 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 Xively is done asynchronously with AJAX requests which means that the rest of your script will continue executing while we wait for Xively 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 Xively API key (https://xively.com/users/YOUR_USERNAME/keys)
  xively.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 Xively
  xively.datastream.get (feedID, datastreamID, function ( datastream ) {
    // WARNING: This code is only executed when we get a response back from Xively, 
    // it will likely execute after the rest your script
    //
    // NOTE: The variable "datastream" will contain all the Datastream information 
    // as an object. The structure of Datastream objects can be found at: 
    // https://xively.com/dev/docs/api/quick_reference/api_resource_attributes/#datastream

    // 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
    xively.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 Xively, 
  // use the function associated with datastream.get to work with the data 
  // once the request is complete
});