App Directory SDK

Quickstart

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.

At hootsuite.com

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 when HootSuite dashboard uses HTTP, type it in the <iframe>d URL field, (ex. http://localhost/app.html).
  • To specify the URL used to load your app stream when HootSuite dashboard uses HTTPS, type it in the Secure <iframe>d URL field, (ex. https://localhost/app.html). You can leave this field empty if your app stream doesn't support HTTPS. Note: If the app stream is loaded using HTTPS, my_receiver.html (see below) must also be loaded using HTTPS, otherwise the incoming communication from HootSuite dashboard to you app stream will break.
  • 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:

http://static.hootsuite.com/jsapi/0-5/hsp.js

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

<script src="http://static.hootsuite.com/jsapi/0-5/hsp.js"></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="http://<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. http://localhost/my_receiver.html).

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

<script>
hsp.init({
	apiKey: '<MY API KEY>',
	receiverPath: 'http://<YOUR DOMAIN>/my_receiver.html'
});
</script>

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>

At hootsuite.com

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:

MyFirstApp

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() { 
	window.location.reload();
});    
hsp.bind('dropuser', function(username, tweetID) {
	hsp.showUser(username);
});

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.

App Directory SDK

From the HootSuite Blog

Thumbnail for Google Plus Best Practices for Brands

Google Plus Best Practices for Brands

In part 1 “Google+ for Brands: 4 Reasons your Brand Should Be on it”, we...
Read More

Thumbnail for Top 10 Twitter Trends of the Week by Ad Age and HootSuite (USA), Volume 57

Top 10 Twitter Trends of the Week by Ad Age and HootSuite (USA), Volume 57

This week, inspiring women were all over the US Twitter trends. From Angelina Jolie motivating...
Read More

Thumbnail for Top 10 Global Twitter Trends of the Week, Volume 57

Top 10 Global Twitter Trends of the Week, Volume 57

This week’s global Twitter trends combine the heavy with the light-hearted. Mixed in with Mother’s...
Read More

Thumbnail for Friday Cute Picture Overload ~ A HootUp Photo Essay

Friday Cute Picture Overload ~ A HootUp Photo Essay

What’s more beautiful than twenty pictures of children smiling and being creative?  Enjoy this Friday...
Read More