JavaScript SDK

Note: this documentation is for the current version of the Javascript SDK. The old 1.x version can be found here.

The JavaScript SDK is different from the other SDKs in that it only provides information about the user's authentication/authorization status. It is not a general purpose SDK to make arbitrary requests against the API. A Node SDK is being developed to fill this role for server-side JavaScript.

Loading and initializing

The following code will load and initialize the JavaScript SDK with the most common options. Replace YOUR_CLIENT_ID, SPID_JSSDK_URI and SPID_SERVER_URI with the appropriate values.

SPID_SERVER_URI is dependent on the SPiD server you will be using.

Production servers

Stage/Pre servers

SPID_JSSDK_URI will normally point to SPiD's CDN or your own hosting. Read more about this under hosting.

SDK variants

The SDK is currently built in three distribution variants: one for users using the AMD module format, one for CommonJS users, and one for vanilla JS users. The third SDK variant will set a global variable named SPiD (note the capitalisation).

Synchronously loading the JS SDK

Place the following code right before the closing </body> tag on your page:

<script type="text/javascript" src="SPID_JSSDK_URI"></script>
<script type="text/javascript">
// Add event subscribers
SPiD.event.subscribe('SPiD.login', function(data) { console.log(data); });
SPiD.event.subscribe('SPiD.logout', function(data) { console.log(data); });
SPiD.event.subscribe('SPiD.sessionChange', function(data) { console.log(data); });

//Initiate SDK
SPiD.init({
    client_id: "YOUR_CLIENT_ID",
    server: "SPID_SERVER_URI"
    // Additional initialization (See below for a full list of available initialization options)
});
// Check session
SPiD.hasSession();

</script>

Asynchronously loading the JS SDK

By loading the SPiD SDK asynchronously it will not block loading other elements on your page. The function assigned to window.asyncSPiD is run as soon as the SDK source has finished loading. Any code you want to run after the SDK is loaded should be placed within this function. Place the following code right before the closing </body> tag.

<script>
window.asyncSPiD = function() {
    // Add event subscribers
    SPiD.event.subscribe('SPiD.login', function(data) { console.log(data); });
    SPiD.event.subscribe('SPiD.logout', function(data) { console.log(data); });
    SPiD.event.subscribe('SPiD.sessionChange', function(data) { console.log(data); });

    //Initiate SDK
    SPiD.init({
        client_id: "YOUR_CLIENT_ID",
        server: "SPID_SERVER_URI"
        // Additional initialization (See below for a full list of available initialization options)
    });
};

// Load the SDK's source Asynchronously
(function(d){
    var js, id = 'spid-jssdk', ref = d.getElementsByTagName('script')[0];
    if (d.getElementById(id)) {return;}
    js = d.createElement('script'); js.id = id; js.async = true;
    js.src = "SPID_JSSDK_URI";
    ref.parentNode.insertBefore(js, ref);
}(document));
</script>

Since version 1.5.0, the SDK is loaded minified by default, for optimal network performance.

Checking and accepting agreements

The response session object contains two boolean fields called defaultAgreementAccepted and clientAgreementAccepted. If one of those fields is false, you can have the SDK issue a call to the relevant endpoint (i.e. ajax/acceptAgreement) when, for example, the user presses a button. If the acceptAgreement request is successful, the auth.sessionChange will fire, and the event response data will include the updated values for the defaultAgreementAccepted and clientAgreementAccepted fields.

<script type="text/javascript" src="SPID_JSSDK_URI"></script>
<script type="text/javascript">
 SPiD.event.subscribe('SPiD.sessionChange', function(data) {
    var sess = data.session || {};
    if (sess.defaultAgreementAccepted && sess.clientAgreementAccepted) {
        return;
    }
    // show SPiD summary and/or client summary depending on booleans
});

$('.acceptButton').click(function() {
    SPiD.acceptAgreement(function (){ alert('Agreement accepted'});
});

//Initiate SDK
SPiD.init({
    client_id: "YOUR_CLIENT_ID",
    server: "SPID_SERVER_URI"
    // Additional initialization (See below for a full list of available initialization options)
});
</script>

Logout

When using the Javascript SDK, a local cache is used to cache the logged in state of the user. When user clicks logout, this local cache needs to be cleared. That is done by calling SPiD.logout() in the Javascript SDK.

Calling SPiD.logout() will try to invalidate the remote logged in state too, but will not succeed in Safari when there has been more than 24 hours since the last active user login. To properly log the user out, you should also redirect the browser to the logout page. The URL can be built by calling SPiD_Uri.logout().

Initialization options

client_id

Your client ID. Required

server

URL to the SPiD server. Required

logging

Set to true to enable logging. Default value is false. When logging is enabled, the SDK will output debug information to the console. NOTE: it uses console.log() so your browser needs to support it, otherwise an error will be thrown.

useSessionCluster

Controls which session endpoint to use. Defaults to true. During development you should consider setting this to false. Remember to set to true or remove this flag before deploying to production. This config option used to be called ”prod”.

varnish_expiration

Varnish cookie expiration, in seconds. Defaults to the same as the session expiration.

setVarnishCookie

Boolean flag to determine if a varnish cookie should be set. Varnish cookie will be set unless this is set to false.

timeout

This is the default connection timeout in milliseconds used when waiting for response by the SPiD servers. Defaults to 5 seconds (5000 milliseconds).

refresh_timeout

This option specifies the cache time of successful hasProduct and hasSubscription calls. This is configurable down to 1 minute (60000 milliseconds). We encourage clients to use the default unless it is necessary to change it.

storage

Set to ’cookie’ to store the session as a cookie. Set to ’localstorage’ to store the session in local storage. The default value is ’localstorage’.

Auto-login usecase

This is a simple overview of Single Sign On using JS SDK, explaining the complete process between the client service (yellow) and SPiD (blue).

Single Sign On using JS SDK

Third-Party Cookies

The SPiD js SDK depends heavily on the possibility to access third party cookies. If a user blocks this feature in the browser or it's blocked by default, this SDK won't be able to retrieve session information from SPiD. Note: this means that methods like .hasSession() will report "session not found" even after a successful login

Comments/feedback

Do you have questions, or just want to contribute some newly gained insight? Want to share an example? Please leave a comment. SPiD reads and responds to every question. Additionally, your experience can help others using SPiD, and it can help us continuously improve our documentation.