Web SDK

Info Contents
Version 2.0.0
Support devsupport@superawesome.tv
License GNU Lesser General Public License Version 3

Note

  • In order to avoid backward compatibility issues some functions are prefix with a version number like this v1.user.get.
  • It is because a new version of this function is (or will be) available.
  • The current version of the function is never prefixed.
  • So in order for you to not have to change your entire source code later you can use the function with the version prefixed with a 100% backward compatibility guaranteed

Including the sources in your html

<head>
    <!-- (...) -->

    <!-- KWS SDK -->
    <script type="text/javascript" src="https://kws-sdk.superawesome.tv?v=2"></script>
</head>

Instantiating the SDK

// KWS will provide all the necessary info for your account
var kwsSdk = new KwsSdk({
    clientId: 'your_client_id',
    kwsApiHost: 'https://examplekwsapihost.com',
    clubUrl: 'https://examplekwsclub.com',
    language: 'en',  // The language of your frontend here

    /*(optional) if set must contain the token of the user. (useful when working with iframe) */
    token: 'BEARER TOKEN HERE',
    /*(optional) if set to true won't init the notification */
    withoutNotifications: false,
    /*(optional) if set to true will use the implicit flow */
    implicit: false,
    /*(optional) if set to true will will consider the backend as a different domain */
    crossDomain: true,
    /*(optional) must contain the backend url if `crossDomain` is set to true */
    callbackHost: 'https://yourbackendurl.com'
});

Login or logout

If the user is not logged in you want to display a login button, if the user is currently logged in you want to display a logout button instead. When you click on the button you call the action from the SDK to log in or log out.

<body>
    <button id="login" class="sa_sign_in" onclick="kwsSdk.signIn()"></button>
    <br/>
    <a href="#" id="logout" onclick="kwsSdk.signOut()">Logout (<span id="displayName"></span>)</a>
</body>
var kwsSdk = new KwsSdk({
    clientId: 'your_client_id',
    kwsApiHost: 'https://examplekwsapihost.com',
    clubUrl: 'https://examplekwsclub.com',
    language: 'en'  // The language of your frontend here
});

kwsSdk.app.user.get()
    .then(function(user){
        console.log('Got user data', user);
        document.getElementById('logout').style.display = 'block';
        document.getElementById('login').style.display = 'none';
        document.getElementById('displayName').innerHTML = user.username;
    })
    .catch(function(){
        console.log('Call failed. User is not authenticated');
        document.getElementById('logout').style.display = 'none';
        document.getElementById('login').style.display = 'block';
    })
    .finally(function(){
        console.log('This is always called at the end when the response is received');
    });

App

Leader

Get Leaderboard

This function allows you to get a leaderboard for the app. It can be filtered by date, including day, week and month leaderboards for example. The user does not have to be authenticated in order to make this call.

Note

  • Function: v1.app.leader.list
  • Parameters:

    • offset (number|optional) offset of the leaderboard results (for the paged results. 0 by default)
    • limit (number|optional) limit of the leaderboard results (for the paged results. 0 by default)
    • start (number|optional) lower threshold timestamp (ms) for the date filter
    • end (number|optional) upper threshold timestamp (ms) for the date filter
  • Usage example

kwsSdk.v1.app.leader.list({
        start: 1454284800000,
        end: 1456790400000
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • offset (number) offset of the results

    • limit (number) limit length applied to the results

    • count (number) number of total users (if limit were not applied)

    • results (array) paged results. Every entry is an object with the following attributes:
      • results.rank (number) rank of the user
  • Response example

{
        "offset": 0,
        "limit": 50,
        "count": 2,
        "results": [{
                "rank": 1,
                "score": 4386,
                "user": "user321"
        }, {
                "rank": 2,
                "score": 1235,
                "user": "user132"
        }]
}

User

AppData

Get App Data

This function allows you to retrieve previous stored data related to the user in that specific app. The data is in the form of pair key-values. It can be filtered by key name.

Note

  • Function: v1.app.user.appData.list
  • Parameters:

    • offset (number|optional) offset of the data results (for the paged results. 0 by default)
    • limit (number|optional) limit of the data results (for the paged results. 0 by default)
    • name (number|optional) search a value by that specific key name
  • Usage example

kwsSdk.v1.app.user.appData.list({
        name: "timeTillEnd"
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • offset (number) offset of the results

    • limit (number) limit length applied to the results

    • count (number) number of total variables (if limit were not applied)

    • results (array) paged results. Every entry is an object with the following attributes:
      • results.name (string) variable name
      • results.value (number) variable value
  • Response example

{
        "offset": 0,
        "limit": 50,
        "count": 1,
        "results": [{
                "name": "timeTillEnd",
                "value": 2864212
        }]
}
Set App Data

This function allows you to create or update data related to the user in that specific app. The data is in the form of pair key-values. Values can only be integers.

Note

  • Function: v1.app.user.appData.set
  • Parameters:

    • name (number|optional) key name
    • value (number|optional) value to be stored
  • Usage example

kwsSdk.v1.app.user.appData.set({
        name: "timeTillEnd",
        value: 2864212
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
Delete App Data

This function allows you to delete data related to the user in that specific app.

Note

  • Function: v1.app.user.appData.deleteByName
  • Parameters:

    • name (string|optional) key name of data you want to delete
  • Usage example

kwsSdk.v1.app.user.appData.deleteByName({
        name: "timeTillEnd"
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });

Has device token

This function checks if the user has a device token registered for this app

Note

  • Function: v1.app.user.getHasDeviceToken
  • Usage example
kwsSdk.v1.app.user.getHasDeviceToken()
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response example
true

Get User Profile

This function allows you to get the user’s profile and its app related data

Note

  • Function: app.user.get
  • Usage example
kwsSdk.app.user.get({})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • id (number) id of the user.
    • username (string) specific display name for the app (it is app specific for every user).
    • dateOfBirth (string YYYY-MM-DD)
    • language (string) ISO 639-1 code.
    • gender (string) “m” for male and “f” for female.
    • permissions (object) list of permissions to access data. Each attribute will be a boolean indicating permission to access every specific piece of data of the child.
    • firstName (string|optional) This field will only be available if the corresponding permission is allowed.
    • lastName (string|optional) This field will only be available if the corresponding permission is allowed.
    • email (string|optional) This field will only be available if the corresponding permission is allowed.
    • streetAddress (string|optional) This field will only be available if the corresponding permission is allowed.
    • postCode (string|optional) This field will only be available if the corresponding permission is allowed.
    • city (string|optional) This field will only be available if the corresponding permission is allowed.
    • country (string|optional) This field will only be available if the corresponding permission is allowed.
  • Response example

{
        id: 1,
        firstName: 'User1',
        lastName: 'Test1',
        email: 'testuser1@test.com',
        dateOfBirth: '2010-01-01',
        streetAddress: 'Street1',
        city: 'City1',
        postalCode: 'N1 000',
        country: 'gb',
        username: 'testuser1DisplayName2',
        gender: true,
        permissions: {
                accessAddress: true,
                accessFirstName: true,
                accessLastName: true,
                accessEmail: true,
                accessStreetAddress: true,
                accessCity: true,
                accessPostalCode: true,
                accessCountry: true,
                sendPushNotification: null,
                sendNewsletter: null,
                enterCompetitions: null
        },
        appData: [{
                name: 'test-appdata',
                value: 5
        }]
}

Get User points in App

This function allows you to retrieve the user points break down per currency in your app

Note

  • Function: app.user.getPoints
  • Alias: app.user.getAppPoints
  • Usage example
kwsSdk.app.user.getPoints({})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • total (number) Total amount of points breakdown per current the user has available in your app at the moment
    • pending (number) Total amount of points breakdown per the user has blocked due to some transaction in progress
    • totalreceived (number) Total amount of points breakdown per the user received by you app
  • Response example

{
        total: [{
                sum: 20,
                currencyId: 2,
                singularName: 'Awesome point',
                pluralName: 'Awesome points'
        }, {
                sum: 13,
                currencyId: 3,
                singularName: 'Other point',
                pluralName: 'Other points'
        }],
        pending: [{
                sum: 15,
                currencyId: 3,
                singularName: 'Other point',
                pluralName: 'Other points'
        }],
        totalReceived: [{
                sum: 20,
                currencyId: 2,
                singularName: 'Other point',
                pluralName: 'Other points'
        }, {
                sum: 25,
                currencyId: 3,
                singularName: 'Other point',
                pluralName: 'Other points'
        }]
}

Get User score

This function allows you to retrieve the user score for an app and a currency. You can also specify a time interval

Note

  • Function: app.user.getScore
  • Parameters:

    • start (timestamp) the start date to use for the interval. If left empty it will take everything from the begining
    • end (timestamp) the end date to use for the interval. If left empty it will take everything until today
    • currencyId (integer) The currency ID to use. If left empty it will use the default currency ID
  • Usage example

kwsSdk.app.user.getScore({})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • score (number) Total amount of points the user has for the specified currency (or default one) and the specified time interval (or overall)
    • rank (number) The current rank of the user for the specified currency (or default one) and the specified time interval (or overall)
  • Response example

{
        "score": 1234,
        "rank": 567
}

Generate random display name

This endpoint returns a randomly generated display name based on the nouns and adjectives set for the app’s display names. This display name at the time of the response will not be in use by any other user across the instance of the API. If there are no words set for the current language option, it will fall back to English and attempt to return an English display name.

Note

  • Function: app.getRandomDisplayName
  • Usage example
kwsSdk.app.getRandomDisplayName({})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • **** (string) A random display name that can be displayed to the user and used for the account creation and/or app activation.
  • Response example

{
        'AwesomeNinja8312'
}

User

Get User Profile and Points

This function allows you to get the user’s profile and their points

Warning

If you plan to use the last version of this endpoint keep in mind users information and users points are two different functions now

Note

  • Function: v1.user.get
  • Usage example
kwsSdk.v1.user.get({})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • id (number) id of the user.

    • username (string) specific display name for the app (it is app specific for every user).

    • applicationPermissions (object) description of permissions to access data. Each attribute will be a boolean indicating permission to access every specific piece of data of the child.

    • applicationProfile (object) profile specific to the app. Includes the following:
      • applicationProfile.username (string) specific display name for the app (it is app specific for every user).
    • dateOfBirth (string YYYY-MM-DD)

    • language (string) ISO 639-1 code.

    • gender (string) “m” for male and “f” for female.

    • points (object) object with a summary of the points of the user. Inlcudes the following fields:
      • points.availableBalance (number) The current number of points available for the user.
      • points.pending (number) The amount of points that are blocked for the user.
      • points.total (number) The total current number of points for the user (including the blocked ones).
      • points.totalPointsReceivedInCurrentApp (number) The total number of points that the user received in this app.
      • points.totalReceived (number) The total number of points that the user received across all apps.
    • firstName (string|optional) This field will only be available if the corresponding permission is allowed.

    • lastName (string|optional) This field will only be available if the corresponding permission is allowed.

    • email (string|optional) This field will only be available if the corresponding permission is allowed.

    • address (object|optional) This field will only be available if the corresponding permission is allowed. It would contain the following fields:
      • address.street (string)
      • address.postCode (string)
      • address.city (string)
      • address.country (string)
  • Response example

{
        "id": 2,
        "applicationPermissions": {
                "accessFirstName": true,
                "accessLastName": true,
                "accessEmail": true,
                "accessStreetAddress": true,
                "accessCity": true,
                "accessPostalCode": true,
                "accessCountry": true
        },
        "applicationProfile": {
                "username": "user2"
        },
        "username": "user2",
        "dateOfBirth": "2005-03-07",
        "language": "en",
        "gender": null,
        "firstName": "",
        "address": {
                "street": "Example Street",
                "postCode": "11111",
                "city": "Example City",
                "country": "United Kingdom"
        },
        "points": {
                "availableBalance": 515,
                "pending": 0,
                "total": 515,
                "totalPointsReceivedInCurrentApp": 119,
                "totalReceived": 515
        }
}

Update User Profile

This function allows apps to update the application profile of the user (excluding the display name, which is inmutable)

Note

  • Function: v1.user.update
  • Parameters:

    • firstName (string|optional) This field will only be available if the corresponding permission is allowed.

    • lastName (string|optional) This field will only be available if the corresponding permission is allowed.

    • language (string) ISO 639-1 code.

    • gender (string) “m” for male and “f” for female and null for unknown.

    • email (string|optional) This field will only be available if the corresponding permission is allowed.

    • address (object|optional) This field will only be available if the corresponding permission is allowed. It would contain the following fields
      • address.street (string)
      • address.postCode (string)
      • address.city (string)
      • address.country (string)
  • Usage example

kwsSdk.v1.user.update({
        "firstName": "John",
        "lastName": "Doe",
        "email": "j.doe@unknown.com",
        "gender": "m",
        "language": "en",
        "address": {
                "street": "Example Street",
                "postCode": "11111",
                "city": "Example City",
                "country": "gb"
        },
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });

Trigger event

This function allows your app to award points to users when a certain event happens (like watching a video or playing a game)

Note

  • Function: v1.user.triggerEvent
  • Parameters:

    • token (string) token string that identifies the event (KWS will provide you with this).
    • points (number|optional) if omitted, the deafult amount of points will be given.
    • description (string|optional) Message the will be sent to the user in a notification. It can contain HTML (This message can contain the word {{POINTS}} that will be replaced by the corresponding amount of points).
  • Usage example

kwsSdk.v1.user.triggerEvent({
        token: "aaabbbcccddd",
        points: 3,
        description: "Thanks for watching! <br> You have been awarded {{POINTS}}!"
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });

Check if event has been triggered

This function is used to check if an event has already reached the limit for the user, and thus will not award points anymore.

Note

  • Function: v1.user.hasTriggeredEvent
  • Parameters:

    • eventId (number) event identifier.
  • Usage example

kwsSdk.v1.user.hasTriggeredEvent({
        eventId: 25
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • hasTriggeredEvent (boolean) It will indicate if the event has reached the limit or not.
  • Response example

{
        "hasTriggeredEvent": false
}

Request Permissions

This function allows your app to send a notification to a user’s parent to request permission for a specific feature, like sending a welcome pack or a birthday email.

Note

  • Function: v1.user.requestPermissions
  • Parameters:

    • permissions (array) array with the requested permissions. It can include the following strings:
      • permissions.accessEmail (string)
      • permissions.accessAddress (string)
      • permissions.accessFirstName (string)
      • permissions.accessLastName (string)
      • permissions.sendPushNotification (string)
      • permissions.sendNewsletter (string)
  • Usage example

kwsSdk.v1.user.requestPermissions({
        permissions: ['accessAddress', 'sendPushNotification']
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });

Invite a Friend

This function allows a user to invite a friend to the app by providing their email. The user making the invite will get rewarded with points when the new user joins the app.

Note

  • Function: v1.user.inviteUser
  • Parameters:

    • email (string) email of the user’s friend.
  • Usage example

kwsSdk.v1.user.inviteUser({
        email: "myfriend@example.com"
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });

Get User global points

This function allows you to get the global amount of points break down per currency of a user across all your apps.

Note

  • Function: user.getPoints
  • Alias: app.user.getGlobalPoints
  • Usage example
kwsSdk.user.getPoints({})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • total (number) Total amount of points breakdown per current the user has available in your app at the moment
    • pending (number) Total amount of points breakdown per the user has blocked due to some transaction in progress
    • totalreceived (number) Total amount of points breakdown per the user received by you app If total and pending are subtracted from it, you’ll get the points the user has already spent.
  • Response example

{
        total: [{
                sum: 20,
                currencyId: 2,
                singularName: 'Awesome point',
                pluralName: 'Awesome points'
        }, {
                sum: 13,
                currencyId: 3,
                singularName: 'Other point',
                pluralName: 'Other points'
        }],
        pending: [{
                sum: 15,
                currencyId: 3,
                singularName: 'Other point',
                pluralName: 'Other points'
        }],
        totalReceived: [{
                sum: 20,
                currencyId: 2,
                singularName: 'Other point',
                pluralName: 'Other points'
        }, {
                sum: 25,
                currencyId: 3,
                singularName: 'Other point',
                pluralName: 'Other points'
        }]
}