App Directory SDK

Documentation

JSApi

Current version: 0-5

How It Works

JSApi is the App Directory SDK's communication gateway between your app and the HootSuite dashboard. The API allows app developers to call functions that send events to the HootSuite dashboard and to receive event notifications specific HootSuite dashboard events of within an app.

Interactions between HootSuite and your app are enabled by two files:

  • JS Api - The SDK Javascript library, hsp.js, provides functions that drive specific functionality in the HootSuite dashboard. hsp.js also enables initialization and registration of your app to receive events from the HootSuite dashboard through an app receiver hosted by your app.
  • App Receiver - The app receiver enables your application to receive events from the HootSuite dashboard. More specifically, the receiver is required for the hsp.bind() function described below to work.

Setup

The following files are needed to use the JS API:

  • JS Library - The hsp.js library enables two-way communication between your app and the HootSuite dashboard. Include this file in your App's primary page.

    https://hootsuite.s3.amazonaws.com/jsapi/0-5/hsp.js

    For example, the reference to this file in your primary page would appear as follows:

  • App Receiver - The app receiver enables your application to receive events from the HootSuite dashboard. More specifically, the receiver is required for the hsp.bind() and hsp.updatePlacementSubtitle() to work. This file needs to be downloaded, placed in the root hosted App's root directory, and then referenced by hsp.init() in the receiverPath parameter ( HTTPS URL).

    https://hootsuite.s3.amazonaws.com/jsapi/0-5/my_receiver.html

API Functions & Events

Communication from your app to the HootSuite dashboard occurs using the functions available in hsp.js.

Communication from the HootSuite dashboard to your app is enabled through events. The events that your app is interested being notified about are registered with calls to the hsp.bind() function indicating the event of interest and the callback function that your app will execute when the event it triggered.

Functions

Events

  • closepopup - Fires when a custom popup opened by your app stream is closed
  • dropuser - Fires when a user drags & drops a Twitter user avatar from the HootSuite dashboard into your app stream
  • refresh - Fires when the app column is refreshed, either by the user within the stream, or as part of a dashboard refresh
  • sendtoapp - Registering for this event will cause users to see a menu item reading Send to <app stream>...in Twitter, Facebook and LinkedIn stream message menus. This event is fired when users click on the menu item
  • sendcomposedmsgtoapp - Adds app plugin to the native HootSuite social network profile selector. User can send messages to the plugin directly from HootSuite compose message box
  • sendprofiletoapp - Registering for this event will cause users to see a menu item in Twitter, Facebook, LinkedIn and Google+ Page profile menus. The event is fired when users click on the menu item
  • sendassignmentupdates - Registering this event will let an app get notified of its assignment updates

hsp.init(params)

Initializes the JS API and loads the theme CSS files.

params: object:

  • apiKey (string)
  • receiverPath (string, optional) Absolute URL of your app_receiver.html file. This must start with https://
  • useTheme (int, optional) Set to 1 to use current dashboard theme.
  • subtitle (string, optional) The subtitle of your app, to be displayed in the stream's title.
  • callBack (function, optional) Init will send an error message to the callBack function after initialization. The message is: No Error, if initialization is successful.
Example:

hsp.bind(eventName, callback)

Registers an event handler for a specified event.

Note: This requires the App Receiver to be set up.

eventName: (string)

Name of the event to handle, can be one of the following:

  • closepopup - Fires when a custom popup opened by your app stream is closed
  • dropuser - Fires when a user drags & drops a Twitter user avatar from the HootSuite dashboard into your app stream
  • refresh - Fires when the app column is refreshed, either by the user within the stream, or as part of a dashboard refresh
  • sendtoapp - Registering for this event will cause users to see a menu item reading Send to <app stream>...in Twitter and Facebook stream message menus. This event is fired when users click on the menu item

callback: (function)

Function to handle the callback, the function's parameters are determined by the event. See the events section for details on expected callback formats.

Example:

As stated in the Best Practices section, it makes sense to suppress reloading of the stream while the user interacts with it (e.g. posting messages, expanded details, possibly scroll position not near the top). A possible approach could look something like this:

The use of window.location.reload() is obviously not the best approach and was used mostly for simplicity of the examples. One of the most elegant solutions would be to poll for any new messages via AJAX and to inject only new messages into the DOM while leaving existing messages untouched.

hsp.clearStatusMessage()

Removes all currently visible status messages.

hsp.composeMessage(message, params)

Opens the Share to Social Networks dialog in the HootSuite dashboard.

message: (string)

Twitter message rules apply, eg. to compose a DM to @HootSuite would be: d hootsuite <your message here>

params: (object, optional):

  • shortenLinks: bool, optional
    Shorten all links found in message with user's default URL shortener (ow.ly / ht.ly / or vanity url). Defaults to false.
  • timestamp: bool OR int, optional
    Open the Scheduler and populate it with the timestamp (in GMT). If true is passed in, then the Scheduler will open with no default time. Defaults to false.
  • replyToId: string, optional
    Compose a new tweet in reply to an existing tweet. If a valid string ID is passed in for an existing tweet, then the Composer will treat the new message as part of the conversation.
Example:

hsp.retweet(id, screenName)

Opens the retweet dialog process in the HootSuite dashboard for tweet with id to be retweeted by screenName.

id: (string)

Twitter's id_str tweetId for the tweet to retweet

screen_name: (string, optional)

The Twitter screen_name you want to retweet with

Example:

hsp.customUserInfo(data)

Opens a user info popup window.

data (JSON object)

Example:

hsp.showCustomPopup(src, title, width, height)

Shows a modal popup window containing an iFrame showing content from the specified URL. On close the dialog fires the closePopUp() event.

src (string)

URL of the content to show in the popup

title (string)

The title displayed on the popup window

width (int)

The width in pixels of the popup. The width has the following constraints:

  • If not specified, the width defaults to 640 pixels
  • The minimum width is 300 pixels.
  • The maximum width is 900 pixels.

height (int)

The height in pixels of the popup. The width has the following constraints:

  • If not specified, the height defaults to 445 pixels
  • The minimum height is 225 pixels.
  • The maximum height is 500 pixels.
Example: Important:

Please do not initialize hsp again inside the custom popup. Your popup is not supposed to use any hsp functions other than closeCustomPopup(apiKey, pid).

If your popup and app stream/plugin are in the same domain, it is recommended that your popup uses the following javascript function to communicate back to your stream/plugin and run the hsp function: window.parent.frames[apiKey_pid].hsp.some_function().

Note: hsp event binding functions are not available in the custom popup.

hsp.closeCustomPopup(apiKey, pid)

Closes the modal popup window. Note: Please make sure the iFrame page in the custom popup window and the app stream page are sharing the same domain. You don't need to (and shouldn't) call hsp.init() again in the iFrame page, just include hsp.js and call hsp.closeCustomPopup(apiKey, pid). You can use JavaScript to communicate between the popup and the stream like this:

apiKey (string)

Your app's API Key

pid (string)

The pid is associated with each unique installation of an app stream (or plugin). You can get the pid of each app stream from the url request your server gets. For example:

https://demo.ca/stream.html?lang=en&theme=blue_steel&timezone=-25200&pid=60956&uid=136

hsp.showImagePreview(src, externalUrl)

Shows an image in a popup window, optionally linking to an external URL.

src (string)

Image URL

externalURL (string)

URL to open if user clicks on the image

hsp.showStatusMessage(message, type)

Shows a notification in the top center of the HootSuite dashboard.

message (string)

Should be brief, max. 70 characters.

type (string):

Can be one of the following:

  • info: Blue background
  • error: Red background
  • warning: Yellow background
  • success: Green background

hsp.updatePlacementSubtitle(name)

Updates the subtitle of the App's stream.

Note: This requires the App Receiver to be set up (see above).

name (str)

Max 35 characters

hsp.showUser(twitterHandle)

Opens a user info popup for the specified Twitter username.

twitterHandle (string)

Twitter username

Example:
showUser

hsp.showFollowDialog(twitterHandle, isFollow)

Opens a dialog window for following or un-following a Twitter user.

twitterHandle (string)

Twitter username

isFollow (bool)

true to follow, false to unfollow.

Example:
showFollowDialog

hsp.getTwitterAccounts(callback)

Gets a list (array) of all Twitter profiles (user names) the logged-in user has added to their HootSuite account.

callback (function)

Function that accepts an array strings

Example:

hsp.assignItem(data)

Assign a message, or any text content, to a HootSuite user (self, or team member)

data (JSON object)

Example:

API Events

This section describes the set of available events and expected event handler function signatures available by using hsp.bind().

refresh()

Fires when the app column is refreshed, either by the user within the stream, or as part of a dashboard refresh.

callback format- a function with no parameters

Example:

dropuser()

Fires when a user drags & drops a Twitter user avatar from the HootSuite dashboard into your app stream

callback format- a function with two parameters, the Twitter handle of the user and the unique ID of the Tweet from which the user was dragged

Example:

sendcomposedmsgtoapp()

Adds app plugin to the native HootSuite social network selector. User can send messages to the plugin directly from HootSuite compose message box

NOTE: You need to contact our app directory administration team to enable this event binding for your app plugin

callback format- a javascript object containing the message data

Message object data structure: Example:

closepopup()

Fires when a custom popup opened by your app stream is closed

callback format- a function with no parameters

Example:

sendtoapp()

Registering for this event will cause users to see a menu item reading Send to <app stream>...in Twitter and Facebook stream message menus. This event is fired when users click on the menu item.

callback format- a javascript object containing the message data

Message object data structure: Example message object: Example:

sendprofiletoapp()

Registering for this event will cause users to see a menu item in Twitter or Facebook profile menus. The event is fired when users click on the menu item.

callback format- a javascript object containing the profile data

Profile object data structure:

(click on the link to expand)

 Twitter
 Facebook

sendassignmentupdates()

Registering this event will let an app get notified of its assignment updates

callback format- a javascript object containing the update information data

Sample Assign To Callback: Sample Resolve Callback:

OAuth-specific API Functions

These functions are part of the OAuth authentication procedure, as described on the "Authentication process" page.

hsp.startAppTokenAuth()

Initiates the Session Token creation process.

When this is called, HootSuite sends the stored OAuth Access Token to the App's Authentication Endpoint which validates the token, and creates and returns a Session Token. HootSuite then reloads the App stream, passing the new Session Token token as a URL parameter.

hsp.editAppAuth()

Displays the authentication popup for the app.

EditAppAuth