The SDK is a javascript 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.
The SDK uses AJAX to interact with the API. It uses native javascript functionality (XMLHttpRequest), but when jQuery is present on the page then jQuery will be used instead.
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">
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.
API authentication is per-session and must be performed on each visit - the token is stored in sessionStorage. Entity authentication persists outside the session - the entityID and ApiSessionKey are stored in localStorage.
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?)
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.
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?)
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;..."> Do you accept these terms? </button>