The SDK is a javascript library built to facilitate front-end interactions with the Rubiq API. It uses the standard javascript [authentication] 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. ajax.js and auth.js are 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.auth.init. The call accepts the AppKey as a parameter, and an optional callback function used to perform subsequent SDK operations once authentication is complete.
<script src="https://api.dialogportal.com/v1/sdk/v1/auth.js"></script>
<script src="https://api.dialogportal.com/v1/sdk/v1/ajax.js"></script>
<script src="https://api.dialogportal.com/v1/sdk/v1/entity.js"></script>
<script type="text/javascript">
var APP_KEY = 12345;
rs.sdk.auth.init(APP_KEY, function() {
console.debug('API authenticated');
});
</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 calls to rs.sdk.auth.init 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 entity.js rs.sdk.entity.login function.
rs.sdk.auth.init(APP_KEY, function() {
// Check whether an entity is already logged in
if (rs.sdk.entity.getEntityID() !== -1) {
console.debug('entityID from localStorage: ', rs.sdk.entity.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.entity.login(loginID, password, loginSuccess, loginError);
});
function loginSuccess(data) {
console.debug('Entity authenticated: ', rs.sdk.entity.getEntityID());
console.debug('Name: ', data.firstName, data.lastName);
}
function loginError(err) {
console.error('Login failed: ' + err.responseText);
}
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.entity.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 error is logged to the error console - in a real scenario this error message would be displayed to the user somehow.
Behind the scenes
rs.sdk.entity.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 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);
}
SDK functions
rs.sdk.auth.init(appKey, cb, force)
appKey: required.
cb: An optional callback function, called after successful API authentication
force: An optional boolean parameter, instructing the function to perform the authentication even if already authenticated.
Authenticate the Rubiq API, saving the API token in sessionStorage
Authentication will usually only be performed if an authentication token doesn't already exist. This can be overridden by passing the force parameter.
rs.sdk.entity.getEntityID()
Return the entityID from localStorage
rs.sdk.entity.create(userData, cbSuccess, cbError)
rs.sdk.entity.get(cbSuccess, cbError)
rs.sdk.entity.login(loginID, password, cbSuccess, cbError)
Authenticate an entity, saving the entityID and ApiSessionKey in localStorage
rs.sdk.entity.logout()
Remove the entityID and ApiSessionKey from localStorage
rs.sdk.entity.update(userData, cbSuccess, cbError)
rs.sdk.terms.accepted(termsID, cbSuccess, cbError)
Return true or false depending on whether the authenticated entity has accepted the terms
rs.sdk.terms.acceptedLatest(termsID, cbSuccess, cbError)
Return true or false depending on whether the authenticated entity has accepted the latest version of the terms