The SDK is a javascript JavaScript/ECMAScript library built to facilitate front-end interactions with the Rubiq API. It uses the standard javascript JavaScript Authenticating from JavaScript which means that the requesting domain must be registered in dialogportal™. Contact a Fluid Account Manager for assistance with this.
...
| Note |
|---|
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. |
| Note |
|---|
The SDK is ECMAScript5 compatible, which means it supports most browsers. If you need to support legacy browsers, you may need to include a compatibility shim such as es5-shim, which supports all SDK requirements. |
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.
| Code Block | ||
|---|---|---|
| ||
<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.
...
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.
| Note |
|---|
API authentication is per-session and must be performed on each visit - the |
Errors
All error callback functions listed below should expect an XMLHttpRequest object parameter. If jQuery is used, this will be the jQuery jqXHR wrapper.
| Code Block | ||
|---|---|---|
| ||
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.
...
| Code Block | ||
|---|---|---|
| ||
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
...
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.
...
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>
...