Setup Guide

This guide will show you how to setup the Client SDK for it to function within your web application.

Direct

Insert the following script in the site head tag

<script src="https://cdn.gamification.marshalldoes.dev/sdk.js"/>

Next is to setup the Client SDK with its configuration. This is best completed early in the startup flow of your site. The setup flow identifies this client as belonging to your site, and provides authentication to them.

Direct

window
    .gamificationSaaS
    .setup({
        siteId: '',
        auth: {
            token: ''
        }
    })

Secure Authentication

A secure JSON Web Token is used to authenticate a user with our service. This gives your trusted backend a way to digitally sign a piece of data that confirms a user is who they say they are. We can then verify that your trusted environment has verified this users identity by checking for your signature on every request.

Caution

User tokens must be generated on the backend and transmitted to the client via an API call so that your secret key is not exposed to users.

To create a JWT the following payload should be used

{
    "sub": "<user id>",
    "exp": 1475878357
}

• UserId can be valid UTF-8 string.
• We recommend setting an expiry of 1 day

Examples:

Javascript

const jwt = require('jsonwebtoken');

function createToken(userId, secretKey) {
    const payload = {
        sub: userId
    };

    const options = {
        expiresIn: '1d'
    };

    return jwt.sign(payload, secretKey, options);
}

ASP.NET

public string CreateToken(string userId, string secretKey)
{
    var tokenHandler = new JwtSecurityTokenHandler();
    var key = Encoding.UTF8.GetBytes(secretKey);

    var tokenDescriptor = new SecurityTokenDescriptor
    {
        Subject = new ClaimsIdentity(new[] {
            new Claim(JwtRegisteredClaimNames.Sub, userId)
        }),
        Expires = DateTime.UtcNow.AddDays(1),
        SigningCredentials = new SigningCredentials(
            new SymmetricSecurityKey(key),
            SecurityAlgorithms.HmacSha256Signature
        )
    };

    var token = tokenHandler.CreateToken(tokenDescriptor);
    return tokenHandler.WriteToken(token);
}

Insecure authentication

Caution

Insecure Authentication allows users to impersonate other users. It should not be used in instances where this is not appropriate

Insecure Authentication is an alternate form of user authentication for purposes where a simple integration is desired. This removes the requirement for a backend to securely generate authentication tokens by allowing users to directly specify their user id.

Direct

window
    .gamificationSaaS
    .setup({
        siteId: '',
        auth: {
            userId: ''
        }
    })