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

RandomName

Get Random names data

This endpoint gets the list of nouns and adjectives for random name generation

Note

  • Function: v1.app.randomName.list
  • Response:

    • [language].words (object) object with nouns and adjectives for a given language
      • [language].words.nouns (array) array of object with the list of nouns for a given language
        • [language].words.nouns[i].value (array) noun
        • [language].words.nouns[i].gender (string) “m” for masculine, “f” for feminine and “n” for neutral
      • [language].words.adjectives (object) object with feminine, masculine and neutral adjectives
        • [language].words.adjectives.f (array) array of objects defining feminine adjectives
        • [language].words.adjectives.m (array) array of objects defining masculine adjectives
        • [language].words.adjectives.n (array) array of objects defining neutral adjectives
          • [language].words.adjectives.[gender][i].value (array) adjective
          • [language].words.adjectives.[gender][i].beforeNoun (boolean) boolean indicating whether the adjective should be added before the noun in a random name
  • Response example

{
        "en": {
                "nouns": [{
                        "value": "Dragon",
                        "gender": "n"
                }, {
                        "value": "Monster",
                        "gender": "n"
                }],
                "adjectives": {
                        "n": [{
                                "value": "Unbeatable",
                                "beforeNoun": true
                        }, {
                                "value": "Evil",
                                "beforeNoun": true
                        }]
                }
        },
        "es": {
                "nouns": [{
                        "value": "Dragón",
                        "gender": "m"
                }, {
                        "value": "Bestia",
                        "gender": "f"
                }],
                "adjectives": {
                        "f": {
                                "value": "Malvada",
                                "beforeNoun": false
                        },
                        "m": {
                                "value": "Malvado",
                                "beforeNoun": false
                        }
                }
        }
}

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
        }]
}

Get App Config

This endpoint returns the configuration of an app based on the clientId passed as a query parameter.

Note

  • Function: v1.app.getConfig
  • Parameters:

    • oauthClientId (string) client ID of the application.
  • Response:

    • id (number) ID of the app.
    • name (string) Display name.
    • oauthClientId (string) Client ID; should be the same as the client ID passed as a query param.
    • oauthCallbackUrls (array) Array of approved values to accept as redirectUri. Only values in this array will be accepted when authenticating the user, and only these URLs should be redirected to after the user authenticates.
    • parentEmailRequired (boolean) Whether or not it’s required to collect the parent’s email address of the user regardless of their age. If false, parent email is only reuired for underage users.
    • areAnonAccountsEnabled (boolean) Whether or not anonymous accounts are enabled. If so, users can sign up without providing a date of birth.
    • languages (array) List of supported languages.
  • Response example

{
        "app": {
                "id": 1,
                "name": "Test App",
                "oauthClientId": "test-app",
                "oauthCallbackUrls": ["https://www.superawesome.com/redirect-uri"],
                "parentEmailRequired": true,
                "areAnonAccountsEnabled": false,
        },
        "languages": ["de", "en", "es", "fr", "it", "ja", "ko", "pt-br", "zh-tw"]
}

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

App

Activate Application

Used for activating a user in the context of an application. A user cannot log in to or interact with an application until they’ve been activated within this application.

Note

  • Function: v1.user.app.create
  • Parameters:

    • appName (string) client ID of the application.
    • username (string) Display name of the user within the application; this is unique across users and across applications.
    • permissions (array) Array of permissions to request; notification of these requests will be sent along with the activation notification email.
    • dateOfBirth (string) Date of birth of the child, if not already set. May be required, depending on the app’s settings.
    • parentEmail (string) Parent’s email address. May be required, depending on the app’s settings, or the newly added date of birth if set.

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

Forgot Password

This endpoint allows you to initiate the forgot password flow for a user, triggering an email to be sent to either the child’s email address (if set) or their parent’s email address. The email contains a link which will take the user to a page where they can reset their password. If necessary, the link can be altered in the control panel.

Note

  • Function: v1.user.forgotPassword
  • Parameters:

    • username (string)
    • appName (string|optional) the client ID of the app this request was made from, if applicable (used for branding the email)

Reset Password

This endpoint allows you to use a token to reset a child’s password. The reset password token is generated by KWS and sent to the child (or their parent) via email when the forgot password flow is triggered. After the password is reset, a confirmation email will be sent to the child (or their parent). Please note that this endpoint is only necessary if you are implementing your own ‘forgot password’ flow.

Note

  • Function: v1.user.resetPassword
  • Parameters:

    • token (string)
    • newPassword (string)
    • appName (string|optional) the client ID of the app this request was made from, if applicable (used for branding the email)

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

Delete account

Delete a users account.

Note

  • Function: v1.user.deleteAccount
  • Parameters:

    • password (string)

Create user

This endpoint creates a new child user.

Note

  • Function: user.create
  • Parameters:

    • username (string|optional) login username. Required if child below threshold parental consent age. Must be at least 3 characters long, must start by a letter and can contain only alphanumeric, “-” or “_”
    • password (string) login password. Must be at least 5 characters long.
    • dateOfBirth (string|optional) Date of birth of the user in the format YYYY-MM-DD. It is normally required, but it might depend on the cluster setup.
    • parentEmail (string|optional) : Email address of the parent. Required only for children under threshold parental consent age.
    • email (string|optional) : Email address of the user. Required only if child above threshold parental consent age. Forbidden otherwise.
    • country (string|optional) : country of the user. It can be ommited if unknown.
  • Response:

    • id (number) id of the created user
  • Response example

"{id: 374382}"