HootSuite - App Directory SDK: Quickstart: Create an App Plugin

Add an App Plugin

At hootsuite.com

1. Pre-requisites

In order to complete this section, you will need to add a Twitter or Facebook account to your HootSuite profile.

On your web server

2. File Setup

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

my_plugin.html - This file will be called when HootSuite users interact with your plugin.
my_handler.html - This file represents the external page your plugin will interact with.

Your plugin will also require the following app specific files. If you have already completed the Add an App Stream section, you will have already created these files and they can be re-used as is:

my_receiver.html
app_receiver.js

At hootsuite.com

3. Create an App Plugin

To create a plugin for your app in My Apps:

Click on your app's name.
Click New plugin.
Insert 'My HootSuite Plugin' as a title for your plugin in the 'Title' field.
Insert 'Open popup' as your plugin's menu item in the 'Menu item text' field.
Optionally, provide an icon to serve as the image of the plugin:
- Store this image in the domain's root directory.
- Point to the absolute URL of the image in the 'Icon' field under 'App Plugin Image'.
To specify the URL used to load your app plugin 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 plugin when HootSuite dashboard uses HTTPS, type it in the Secure <iframe>d URLfield, (ex. https://localhost/app.html). You can leave this field empty if your app plugin doesn't support HTTPS. Note: If the app plugin 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 plugin will break.
Click Save.

You have now created a plugin for your app.

4. App Plugin 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.
Inside the 'App Plugins' tab, look for the plugin you created in Step 3 and click Install.

Your plugin has now been successfully installed.

On your web server

5. JS Library Setup

Now you will edit your my_plugin.html file to enable the plugin to communicate with the HootSuite dashboard. Just as in the Add an App Stream section, you will need to add a reference to the HootSuite hosted portion of the App Directory SDK. The file is located here:

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

Add <html> opening and closing tags to the top of my_plugin.html, wrapping opening <head> and <body> opening and closing tags. Inside the <body> tags add a reference to the hsp.js script. This is shown in the following HTML snippet:

<html>
	<head>
	</head>
	<body>
		<script src="http://static.hootsuite.com/jsapi/0-5/hsp.js"></script>
	</body>
</html>

6. 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. If you didn't complete the Add an App Stream section first, 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).

7. JQuery Setup

In order to use the communication layer we have built, we will use JQuery. Right after the hsp.js reference inside the <body> section of my_plugin.html added in Step 3 , add the following line:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.5.2/jquery.min.js"></script>

8. App-Dashboard Event Setup

In my_plugin.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 bottom of the <body> section of the file:

<script>
$(document).ready(function() {
	var hsp_params = {
		apiKey: '<MY API KEY>' ,
		receiverPath: 'http://<YOUR DOMAIN>/my_receiver.html',
	};
		hsp.init(hsp_params);
});
</script>

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

9. Plugin Menu Item Function Implementation

As mentioned in Step 3 , we inserted 'Open popup' as our plugin's Menu Item Text. In this quickstart, we wish our plugin to open a popup that will have information about the specific message selected in the dashboard.

First, we must create a function that will grab the message information that we wish to display in the popup and send it encoded in the URL to my_handler.html. Insert the following code inside my_plugin.html right before the .ready event inserted in Step 8 and taking into account that <YOUR DOMAIN> is your local domain:

function sendToAppHandler(message) {
	var messageId = "messageId=" + encodeURIComponent(message.post.id);
	var datetime  = "&datetime=" + encodeURIComponent(message.post.datetime);
	var message   = "&message=" + encodeURIComponent(message.post.content.body);
	var handler = 'http://<YOUR DOMAIN>/my_handler.html?' + messageId + datetime + message;
	
	hsp.showCustomPopup(handler, 'App Plugin popup');
}

10. App Handler Setup

In my_handler.html, we wish to display the message information received. To achieve this, we write a function to read the parameters being passed in the URL and then we print each. Thus, my_handler.html should look like this:

<html>
	<head>
	</head>
	<body>
	<script type="text/javascript">
	
		function getQuerystring(key)
		{
		  key = key.replace(/[\[]/,"\\\[").replace(/[\]]/,"\\\]");
		  var regex = new RegExp("[\\?&]"+key+"=([^&#]*)");
		  var qs = regex.exec(location.search);
		  return qs[1];
		}
		
		document.write('Message ID: ' + decodeURIComponent(getQuerystring('messageId')) + '<br />');
		document.write('Date & Time: ' + decodeURIComponent(getQuerystring('datetime')) + '<br /><br />');
		document.write('Message: ' + decodeURIComponent(getQuerystring('message')));
		
		</script>
	</body>
</html>

11. Plugin-Handler Connection

To call the sendToAppHandler function created in Step 9 , insert the following code in my_plugin.html inside the JQuery .ready event and right after the hsp.init call inserted in Step 8:

hsp.bind('sendtoapp', function(message){
	sendToAppHandler(message);
});

At hootsuite.com

12. Using the App Plugin

As mentioned in Step 1 , a Twitter or Facebook account will be needed to use the app plugin. If you added a Twitter account then you should see the plugin menu item on a Home Feed stream tweet's menu, for example. If you added a Facebook account, a News Feed stream is one where you could see it. In Step 3 , we inserted 'Open popup' as the plugin's menu item text and this is what is shown in the following image: