Web SDK

Info Contents
Version 2.0.0
Support kws-support@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

User

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.
    • 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.
    • parentEmail (string|optional) This field will only be available calling from the session of a user
  • 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",
        "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
        }]
}

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"

Country

Get age gate info

This function allows you to get the age threshold for a user or for a given country, returning a flag indicating if the user is under age. It does not require authentication.

Note

  • Function: v1.country.getChildAge
  • Parameters:

    • dob (string|optional) date of bith of the user in the following FORMAT: YYYY-MM-DD.
    • country (string|optional) country of the user. If not provided, it will be detected from requesting IP (to use in Frontend only)
  • Usage example

kwsSdk.v1.country.getChildAge({
        country: 'US',
        dob: '2008-05-04',
})
.then(function() { /* Your success handler here */ })
.catch(function() { /* Your error handler here */ });
  • Response:

    • country (string) detected country by IP or sent country in API request
    • consentAgeForCountry (number) threshold age
    • age (number|optional) age of the user. Only sent if dob was provided in the request
    • isMinor (boolean|optional) flag indicating if user is under age. Only sent if dob was provided in the request
  • Response example

{
        country: 'US',
        consentAgeForCountry: 13,
        age: 11,
        isMinor: true
}

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.
    • 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)
    • parentEmail (string|optional) This field will only be available calling from the session of a user
    • isMinor (boolean) Whether or not the user is a child, based on the age requirements in the country the user was created in.
  • Response example

{
        "id": 2,
        "applicationPermissions": {
                "sendPushNotification": true,
                "sendNewsletter": true,
                "featureA": true,
                "featureB": false,
        },
        "applicationProfile": {
                "username": "user2"
        },
        "username": "user2",
        "dateOfBirth": "2005-03-07",
        "language": "en",
        "firstName": "",
        "address": {
                "street": "Example Street",
                "postCode": "11111",
                "city": "Example City",
                "country": "United Kingdom",
                /* DEPRECATED *\/ "countryName": "United Kingdom", "countryCode": "gb" }, "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.
    • 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.countryCode (string) if the address.countryCode is set address.country is not allowed
      • address.country (string) DEPRECATED! if the address.country is set address.countryCode is not allowed
  • Usage example

kwsSdk.v1.user.update({
        "firstName": "John",
        "lastName": "Doe",
        "email": "j.doe@unknown.com",
        "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 */ });

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 */ });