Add an App Plugin

App Directory SDK

Add an App Plugin

1. Pre-Requisites

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

2. File Setup

Your sample app plugin will require the following new files 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

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, type it in the <iframe> URL field (ex. https://localhost/app.html)
  • 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 (next to your app 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.

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:

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.

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:

    <script src=""></script>

6. 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=""></script>

7. App-Dashboard Event Setup

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

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

  $(document).ready(function() {
    var hsp_params = {


8. 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 want 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 for 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(;
  var datetime  = "&datetime=" + encodeURIComponent(;
  var message   = "&message=" + encodeURIComponent(;
  var handler = 'https://<YOUR DOMAIN>/my_handler.html?' + messageId + datetime + message;

  hsp.showCustomPopup(handler, 'App Plugin popup');

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

      function getQuerystring (key) {
        key = key.replace(/[\[]/,"\\\[").replace(/[\]]/,"\\\]");
        var regex = new RegExp("[\\?&]"+key+"=([^]*)");
        var qs = regex.exec(;
        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')));

10. Plugin-Handler Connection

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

hsp.bind('sendtoapp', function(message){

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


Click Open popup and a popup like the following will appear:


12. Final Touches

To make a more efficient and better looking app, check out the Best Practices section. If you run into any issues, read through the FAQ or email us at