Page Comparison

The SDK is a JavaScript/ECMAScript library built to facilitate front-end interactions with the Rubiq API. It uses the standard JavaScript Authenticating from JavaScript which means that the requesting domain must be registered in dialogportal™. Contact a Fluid Account Manager for assistance with this.

The SDK is comprised of a number of scripts. core.js is always required but the others are optional - include the ones you need.

SDK authentication

Every page using the Rubiq SDK must begin with a call to rs.sdk.core.init(). The call accepts the AppKey as a parameter, and an optional callback function used to perform subsequent SDK operations once initialization and authentication is complete.

<script src="https://api.dialogportal.com/v1/sdk/v1/core.js"></script>
<script type="text/javascript">
   var APP_KEY = 12345;
   rs.sdk.core.init(APP_KEY, function() {
      console.debug('SDK initialized');
   });
</script>

Behind the scenes

The SDK is initialized, and authenticated with the Rubiq API. An API "token" is generated and saved in the browser sessionStorage. Subsequent page loads must still call rs.sdk.core.init() to prepare the SDK, but the function will not need to re-authenticate - the stored token will be re-used. 

The API token is only valid for 1 hour from the last use. However, any SDK request that fails with an expired token will automatically re-authenticate, store the new token, and resend the failed request with the new token.

Entity Authentication

All entity-level operations through the SDK require entity authentication. This is done via the rs.sdk.core.login() function.

<script src="https://api.dialogportal.com/v1/sdk/v1/core.js"></script>
<script src="https://api.dialogportal.com/v1/sdk/v1/entity.js"></script>
<script type="text/javascript">
   var APP_KEY = 12345;
   rs.sdk.core.init(APP_KEY, function() {
      // Check whether an entity is already logged in
      if (rs.sdk.core.getEntityID() !== -1) {
         console.debug('entityID from localStorage: ', rs.sdk.core.getEntityID());
         rs.sdk.entity.get(function(e) {
            console.debug('Entity fetched. Name:', e.firstName, e.lastName);
         });
      }
      else
         // Assumes a loginID and password have already been saved to variables
         rs.sdk.core.login(loginID, password, loginSuccess, loginError);
   });
   function loginSuccess(data) {
      console.debug('Entity authenticated: ', rs.sdk.core.getEntityID());
      console.debug('Name: ', data.firstName, data.lastName);
   }
   function loginError(err) {
      console.error('Login failed: ' + err.responseText);
   }
</script>

There's a lot going on in this example. First, the SDK is authenticated as usual. In the callback, a check is made to see whether an entity is already logged in. If they are, the entity details are fetched with rs.sdk.entity.get(), using the existing authentication details.

If the entity is not already logged in, then rs.sdk.core.login() is called, using variables loginID and password, which have presumably been populated from a login form. In the login callback function (loginSuccess()), the entity details are logged to the debug console.

If a login error occurred (e.g. wrong loginID or password), the login error callback function (loginError()) is called, which loggs the error to the error console - in a real scenario this error message would be displayed to the user somehow.

Behind the scenes

rs.sdk.core.login() calls API endpoint 2001: Authenticate to authenticate the entity. The SDK must be used with Data Isolation enabled, and on successful completion, the login function stores the ApiSessionKey and EntityID in the browser localStorage. This means that the entity will not need to be authenticated for each session - next time the user visits the site, the ApiSessionKey and EntityID will be fetched from localStorage and used in subsequent SDK requests.

Errors

All error callback functions listed below should expect an XMLHttpRequest object parameter. If jQuery is used, this will be the jQuery jqXHR wrapper.

rs.sdk.entity.create(data, cbSuccess, cbError);
function cbError(xhr) {
   var httpStatus = xhr.status;
   var apiStatusSubCode = xhr.getResponseHeader('ApiStatusSubCode') || '-1';
   if (httpStatus === 400)
      // There was a problem with the data, e.g. the email address was not unique
      alert(xhr.responseText);
   else
      console.error('Something went wrong.', httpStatus, apiStatusSubCode);
}

Optional parameters

Optional parameters (displayed in the function list below with a question mark: optional_parameter?) can be excluded from SDK function calls. Any callback function parameters can be sent instead, as they are always last.

For example, to request the active, default terms version text for terms with API ID abcde these 2 calls are equivalent:

rs.sdk.terms.getVersionText('abcde', 'active', 'default', onSuccess);
rs.sdk.terms.getVersionText('abcde', onSuccess);

SDK functions

rs.sdk.core.init(appKey, cb?)

rs.sdk.core.getEntityID()

Return the entityID from localStorage. Returns -1 when no entity has been authenticated.

rs.sdk.core.login(loginID, password, cbSuccess?, cbError?)

Authenticate an entity, saving the entityID and ApiSessionKey in localStorage

rs.sdk.core.logout()

Remove the entityID and ApiSessionKey from localStorage

rs.sdk.entity.create(userData, cbSuccess?, cbError?)

userData: The details of the new entity, see 1001: Create account

cbSuccess: Sends a single parameter containing the details of the new entity.

Create a new entity. The successfully created new entity is automatically authenticated, as if rs.sdk.core.login() had been used.

rs.sdk.entity.get(cbSuccess?, cbError?)

cbSuccess: Sends a single parameter containing the details of the entity, see 1002: Get account data

rs.sdk.entity.update(userData, cbSuccess?, cbError?)

userData: The entity details that are to be updated, see 1003: Update account data

cbSuccess: A callback function for a successful update. Passes a single parameter containing the details of the updated entity.

rs.sdk.terms.acceptConsent(consentID, sourceID, cbSuccess?, cbError?)

See 2105: Accept permission

rs.sdk.terms.acceptTerms(termsID, sourceID, version?, consents?, cbSuccess?, cbError?)

version: A version string, formatted as major.minor, i.e. '1.0'. Defaults to the active version.

consents: An array of consentIDs. Defaults to all consents for this version of the terms.

See 2102: Accept terms

rs.sdk.terms.hasAccepted(termsID, latest?, cbSuccess?, cbError?)

latest: Defaults to false. When true, only pass true to cbSuccess when the entity has accepted the latest version of the terms.

cbSuccess: Sends true or false depending on whether the authenticated entity has accepted these terms

rs.sdk.terms.hasConsented(consentID, cbSuccess?, cbError?)

cbSuccess: Sends true or false depending on whether the authenticated entity has accepted this consent

rs.sdk.terms.get(termsID?, cbSuccess?, cbError?)

cbSuccess: Sends a terms details object when termsID is given, otherwise an array of all active terms, see 2100: Get terms

rs.sdk.terms.getVersion(termsID, version?, cbSuccess?, cbError?)

version: A version string, formatted as major.minor, i.e. '1.0'. Defaults to the active version.

cbSuccess: Sends a terms version details object, see 2101: Get terms version

rs.sdk.terms.getVersionText(termsID, version?, textKey?, cbSuccess?, cbError?)

version: A version string, formatted as major.minor, i.e. '1.0'. Defaults to the active version.

textKey: The key of the text to fetch. Defaults to the default text for this version.

cbSuccess: Sends terms version text, with merged authenticated entity details

rs.sdk.terms.withdrawConsent(consentID, sourceID, reason, cbSuccess?, cbError?)

See 2107: Withdraw permission

rs.sdk.terms.withdrawTerms(termsID, sourceID, reason, cbSuccess?, cbError?)

See 2104: Withdraw terms acceptance

rs.sdk.terms.renderVersionText(htmlContainerID, sourceID, termsID, version?, textKey?, cbSuccess?, cbError?, cbAcceptSuccess?, cbAcceptError?)

htmlContainerID: An id of an HTML element, e.g. 'terms-acceptance' for <div id="terms-acceptance"></div>

version: A version string, formatted as major.minor, i.e. '1.0'. Defaults to the active version.

textKey: The key of the text to fetch. Defaults to the default text for this version.

cbSuccess: Parameterless callback, called after the terms version and version text have been fetched and rendered

cbError: Called on error fetching terms version or version text

cbAcceptSuccess: Called on successful terms acceptance, after rendered "Accept" button is clicked

cbAcceptError: Called on error during terms acceptance, after rendered "Accept" button is clicked

Fetch terms version text with merged authenticated entity details, and render it as HTML.

If placeholders are found in the text, consents will be displayed as an unordered list (ul) of checkboxes, and an "Accept" button will be generated:

<!--rs.sdk:consents-->
<ul style="list-style: none">
  <li>
    <input id="C-{consent.id}" type="checkbox">
    <label for="C-{consent.id}">{consent.name}</label>
  </li>
  <li>
    <input id="C-{consent.id}" type="checkbox">
    <label for="C-{consent.id}">{consent.name}</label>
  </li>
</ul>

<!--rs.sdk:accept:Do you accept these terms?-->
<button onclick="this.disabled = true;...(process consents and perform acceptance)...">
  Do you accept these terms?
</button>