App Directory SDK

Frequently Asked Questions

SSO Flow

Retain User Settings

Multiple Account Support

hsp.js Errors

SSO Flow

As a requirement, we expect developers to use Single Sign On authentication on the Hootsuite side of the app, but OAuth for the external service provider.

Here is the workflow the app should follow when using SSO on the Hootsuite side:

  • You can set the app to use SSO in the dev admin tool, then provide a shared secret

  • This will cause Hootsuite to pass the user Hootsuite User ID through with a token check for every interaction with Hootsuite

  • This will keep a record of the Hootsuite user

  • The App will then take that ID and will have a layer that maps the Hootsuite ID to the App User ID

  • If there is no record, the App should prompt for authentication (OAuth within your app)

Retain User Settings

After the stream authenticates with Hootsuite, the following parameters are passed back to the stream iframe:

  1. lang=en

  2. timezone=7200

  3. pid=2823         // placement ID, unique for each stream per user

  4. uid=1234567      // Hootsuite user ID

  5. i=1234567        // user identifier (optionally entered by user upon App installation)

  6. ts=1318362023    // timestamp

  7. token=123abc...  // security token (sha1 hash)

App developers diverge here in terms of how they store these details for a user. The preferred method is to use the provided hsp.saveData and hsp.getData methods, however, storing this within a table within your app is also acceptable.  Please avoid using cookies to store session information.

Multiple Account Support

In order to support multiple accounts across streams (the ability for a user to authenticate each stream under a unique account), you can tie the access token to the stream/app ID. Each new stream adds results in a call to authenticate with your service - even if the user has already added the app and authenticated it in a different stream, the app will request the user to authenticate again.

hsp.js Errors

hsp.init should not be in every page, but only on the initial page of the app and only called once. Once you have initialized, you should then be passing the PID and UID along to each successive page the user visits in the app. The UID and PID should be passed along as part of the recieverPath URL: /index.php?theme=magnum&lang=en&timezone=-25200&pid=515068&uid=209524

After loading my app stream, I am getting this js error: 'Unsafe JavaScript attempt to access frame with URL https://abc.abc.abc from frame with URL https://xyz.xyz.xyz Domains, protocols and ports must match'.

  1. Make sure there are no errors on your app stream/plugin page
  2. Ensure your app stream/plugin is using the correct hsp.js: https://d2l6uygi1pgnys.cloudfront.net/jsapi/2-0/hsp.js
  3. Make sure apiKey in hsp.init() is correct
  4. If the Hootsuite dashboard is in SSL mode, make sure you have provided the correct secure iframe url in the app stream setting page. Make sure your app receiver URL is also using SSL. It is important that hsp.js is loaded in https.

I am getting 'API Key: xxxxxxxxxxxxxxxxxxx is not correct, please check your app settings' error on the dashboard.

Make sure apiKey in hsp.init() is correct.

I am getting 'API Key: is not correct, please check your app settings' error on the dashboard.

Make sure apiKey in hsp.init() is not empty. If you use hsp.js in your popup or other iframe pages, make sure hsp.init() is not called again. The only hsp function that is legitimate to use outside app stream/plugin page is hsp.cloaseCustomPopup(apiKey, pid), and it doesn't require init.

After loading my app stream, I am getting this js error: 'Uncaught TypeError: Cannot call method 'appendChild' of null'.

Check your hsp.init function. Make sure it is called after the page is completely loaded. e.g. put the function inside $(document).ready().

How do I use hsp function on my custom popup page?

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 page and run the hsp function from there: window.parent.frames[apiKey_pid].hsp.some_function().