We’ve built a simple JS library that allows you to quickly add realtime activity streams into your applications. In this short article, we’ll show you how to get started with the libraries, and give an example of what you need to do on your server to make the magic happen.

This tutorial assumes that you have signed up for Pusher Channels already, and have your API keys available for a Channels app.

We will cover the following:

• Adding our activity streams library to your HTML view
• Triggering activity events from your server

Adding the activity stream to the UI

First we’ll look at how to make your web page ready to receive activity stream events.

Download the PusherActivityStreamer.js library

If you have a github account and are happy using git you can fork or clone the project from github (or download a zip instead).

Once you have the code you should make it accessible on your chosen web server. For the purposes of getting up and running we’ll assume that the code is in a directory named activity-streams in the root of your app.

Include the JS files in your HTML page

Now we’ve got libraries handy we’ll need to include a number of JavaScript libraries; jQuery, the Pusher JavaScript library, a stylesheet and the PusherActivityStreamer which hooks up Pusher to the realtime push activity events:

<script src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
<script src="http://js.pusher.com/<%= APP_CONFIG[:current_js_version] %>/pusher.min.js"></script>
<script src="activity-streams/PusherActivityStreamer.js"></script>
<link href="activity-streams/activity-streams.css"rel="stylesheet" type="text/css" />

Define where the activity stream is to appear

Next we need to define where the Activity Stream is going to appear within the UI. The PusherActivityMontior class and associated stylesheet expect an unordered list (<ul>) to be used to display activity. So, let’s create a simple element for this:

<ul id="activity_stream_example" class="activity-stream"></ul>

In the HTML above we give the element a class of activity-streams so that the necessary styles can be applied to it. We also give it an id so it can be easily referenced.

Create a PusherActivityStreamer

Finally, in order to receive Activity Stream events you need to establish a persistent WebSocket connection to Pusher Channels from the web browser so that the instant the Activity Stream event is available it can be pushed to your application. This is achieved by creating a Pusher object using our YOUR_APP_KEY. We also need to subscribe to the site activity channel we used in our PHP called site-activity and create a PusherActivityStreamer.

The PusherActivityStreamer takes two parameters:

1. The site-activity channel so that it can bind to events on it and push in activity events into the Activity Stream as they occur.
2. a jQuery selector that identifies the unordered list where the site activity events should appear. Above, we identifies this by giving it an id attribute of activity_stream_example.

$(function() {
  var pusher = new Pusher('YOUR_APP_KEY');
  var channel = pusher.subscribe('site-activity');
  var streamer = new PusherActivityStreamer(channel, '#activity_stream_example');
});

Triggering server events

Make a new php file in your application, or open an existing one. This will be used to send activity stream events to Pusher.

Include the Pusher PHP library and the activity class

Download the Pusher PHP library and install it somewhere your script has access to, or use the one included in the examples. The code below includes the one in the examples. You should also include the Activity.php file.

<?
require_once('activity-streams/examples/php/lib/squeeks-Pusher-PHP/lib/Pusher.php');
require_once('activity-streams/examples/php/Activity.php');

Triggering events

All you now need to do in order to trigger an activity to be displayed in your activity stream is:

1. Define your application credentials and create a Pusher object
2. Create an Activity object to represent the activity that has occurred
3. Define the activity type and some text about the activity
4. Get the data we want to send in the event from the Activity object
5. Trigger the activity event specifying the channel, event name (we use the $activity_type below) and passing in the event data

<?
$app_key = 'YOUR_APP_KEY';
$app_secret = 'YOUR_APP_SECRET';
$app_id = 'YOUR_APP_ID';
$pusher = new Pusher($app_key, $app_secret, $app_id);

$activity_type = 'activity';
$action_text = 'Yipee! Something happened.';
$activity = new Activity($activity_type, $action_text);
$data = $activity->getMessage();
$pusher->trigger('site-activity', $activity_type, $activity->getMessage());

Test it out

Open your html page in one browser window, and hit your script with another. You should see a the activity stream update to show the newly created activity!

If the desired behaviour doesn’t occur, make sure you have followed the steps correctly. You can also compare your code with the sample application, and check out some of our debugging tools if you are still stuck.

Where next?

Once you’ve signed up for Pusher Channels the sky’s the limit! You can:

• Update the code to use private channels so that you can control who can subscribe to and receive activity stream events
• Add event-driven notifications with Beams
• Have a read through the Pusher docs
• Take a look at the Pusher Tutorials to find out more information about how to build things with Pusher
• Or if you are seeking inspiration you could take a look at the user stories on our blog