Add an App Stream

App Directory SDK

Add an App Stream

On your web server

1. File Setup

Your sample app will require the following files hosted within your domain's root directory:

  • my_app.html - The landing page for your app's first app stream within the Hootsuite dashboard.
  • my_receiver.html - Enables your app to receive events from Hootsuite.
  • app_receiver.js - Download and locally store the Hootsuite App Directory SDK javascript event receiver, also in your domain's root directory.


2. Create an App Stream

To create a stream for your app in My Apps:

  • Click on your app's name.
  • Click New stream.
  • Insert a title for your stream in the 'Title' field.
  • Optionally, provide an icon to serve as the image of the stream:
    • Store this image in the domain's root directory.
    • Point to the absolute URL of the image in the 'Icon' field under 'App Stream Image'.
  • To specify the URL used to load your app stream, type it in the <iframe> URL field (ex. https://localhost/app.html).
  • Click Save.

You have now created a stream for your app.

On your web server

3. JS Library Setup

In order to enable your app's ability to send and receive messages to and from the Hootsuite dashboard, you will need to add a reference to the Hootsuite hosted portion of the App Directory SDK. This file is located here:

To reference this script, add the following HTML snippet to the top of the <body> section of your my_app.html file:

<script src=""></script>

4. App Receiver Setup

In order to receive events from the Hootsuite dashboard, your my_receiver.html will need to reference your locally downloaded copy of app_receiver.js. To accomplish this, add the following HTML snippet to the top of the <body> section of your my_receiver.html file:

<script src="https://<YOUR DOMAIN>/app_receiver.js"></script>

Where <YOUR DOMAIN> is your local domain (ex. localhost).

You have now set up the communication channels for your app to send and receive messages to and from the Hootsuite dashboard. Next, you will add the code to actually use this communication layer.

5. App-Dashboard Event Setup

In my_app.html, initialize the JS API using the hsp.init function and set the hsp parameters:

  • As the apiKey string use the API Key retrieved in the Create an App section, Step 4.
  • As the receiverPath string use the absolute URL of my_receiver.html (ex. https://localhost/my_receiver.html).

Insert this code in between HTML script tags, in the <body> section of the file:

    apiKey: '<MY API KEY>',
    receiverPath: 'https://<YOUR DOMAIN>/my_receiver.html'

Where <MY API KEY> is the retrieved API Key and <YOUR DOMAIN> is your local domain.

6. Add Content

Add some content to your app. In the my_app.html file, at the top of the <body> section of the document, insert the following HTML:

<h2>My First App</h2>


7. App Stream Installation

Inside your Hootsuite dashboard:

  • On the Launch Bar, go to Tools > App Directory.
  • Click My Apps. Your app should appear in the menu.
  • Click Install. It is located next to your app's name.
  • Add the stream you created for your app by following the on-screen instructions.

At this point you should see your app appear in a Hootsuite stream with the heading that you added in Step 6. It should look similar to this:


On your web server

8. Send Messages to Hootsuite

Let's add functionality that will make your app communicate with the Hootsuite dashboard. We'll do this by using two basic functions available in hsp.js:

  • hsp.showTrends(): Shows latest trending topics.
  • hsp.showUser(twitterHandle): Opens a user info popup for the specified twitter username. Let's use Hootsuite (@hootsuite) as an example.

The code should be placed in the <body> section of my_app.html, right after the heading added in Step 6. It should look something like this (line break tags are optional):

<br />
<a href="#" onclick="hsp.showTrends(); return false;">Show trending topics</a>
<br />
<a href="#" onclick="hsp.showUser('hootsuite'); return false;">Show @hootsuite info</a>

9. Receive Messages from Hootsuite

Let's check if your app is enabled to receive events from the Hootsuite dashboard by using the hsp.bind() function for two different types of events:

  • refresh: Fired when the app stream is refreshed.
  • dropUser: Fired when a user drags and drops a Twitter account from the Hootsuite dashboard into your app stream.

We will place this functions in my_app.html, in between the script tags used for hsp.init(), right after such function created in Step 5.

hsp.bind('refresh', function() {

hsp.bind('dropuser', function(username, tweetID) {

Where window.location.reload() reloads the app streams' window and dropping a Twitter account into the app stream will use the hsp.showUser(twitterHandle) function described in Step 8.