Start typing to search...

@withkoji/user-defaults (deprecated)

Warning

This package is deprecated and is included only for backwards compatibility. For new templates, use withkoji-koji-core.html.

The @withkoji/user-defaults package provides a secure interface for accessing permissioned user data across all Koji templates.

A template can request data with a reserved key, for the user’s Koji profile data, or with a user key from any template on Koji, for additional preferences. This data can then be used to autofill values and personalize experiences. For example, automatically enter the user’s name in a leaderboard, or display the user’s avatar in a game.

Keys requested from any template are available in a global, unscoped namespace and do not need to be registered. When a request does not use a reserved key, Koji checks whether the user has entered a value for the requested key, either on the current template or on a different template. If not, the user is prompted to submit a value and allow it to be saved for later reuse. This method enables users to own and manage their data in a transparent, portable way, rather than relying on cookies or other measures.

Install

Install the package in your Koji project.

npm install --save @withkoji/user-defaults

KojiUserDefaults

new KojiUserDefaults()

Instantiates KojiUserDefaults.

Example

import KojiUserDefaults from '@withkoji/user-defaults';
const kojiUserDefaults = new KojiUserDefaults();

KojiUserDefaults methods

.onConnect(handler)

Listens to the user’s login state to enable access to permissioned user data.

Parameters

  • handlerFunction, handles requests for user data. Receives the following property as input:

    • isConnectedBoolean, indicates whether the user is logged in to Koji.

Example

kojiUserDefaults.onConnect((isConnected) => {
  // If logged in, get user name
  if (isConnected) {
    kojiUserDefaults.get('profile.username', (success, key, value) => {
      console.log(success, key, value);
    });
  }
});

.get(key, handler)

Gets a specified piece of user data and invokes a callback function to handle the results of the request.

Parameters

  • keyString, key of the user data to retrieve. See Keys.

  • handlerFunction, handles the results of the data request. Receives the following properties as input:

    • successBoolean, indicates whether the request was successful.

    • keyString, key of the user data.

    • valueString, value of the user data, if the request was successful. For an unsuccessful request, the value is undefined.

Example

kojiUserDefaults.get('profile.username', (success, key, value) => {
  console.log(success, key, value);
});

.promptLogin()

Prompts the user to log in to Koji.

Example

kojiUserDefaults.promptLogin();

Keys

The following reserved keys can be used to access data from the user’s Koji profile.

  • profile.username

  • profile.profilePicture

  • profile.reputation

Additionally, any template can request user data, and the specified key will be used to represent string values in an unscoped, portable, global storage. For example, you could request a key in your template called user.favoriteColor, and then reuse that value in any other Koji template.