Add an App Stream

App Directory SDK

Add an App Stream

1. File Setup

Your sample app needs the following file hosted within your domain's root directory:

  • my_app.html - The landing page for your app's first app stream within the Hootsuite dashboard.

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!

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:

Note: Do not download the above javascript file to include in your app. Always use the above CDN to ensure your app is using the current SDK version.

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-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 you retrieved and stored previously 

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


5. 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>

6. 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 (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 5. It should look similar to this:


7. Send Messages to Hootsuite

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

  • 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 5. It should look something like this (line break tags are optional):

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

8. 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 the function created in Step 4.

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 7.

Once your stream is set up, it's time to add an App Plugin that'll allow you to extend the set of actions that can be taken on messages received in the Hootsuite dashboard.