observalyze-ui-sdk

This is the web SDK for displaying observalyze gamification information to users of your application. It can also be used to send events to the platform.

There is also an Event SDK available, check https://www.npmjs.com/package/observalyze-sdk. That SDKs sole purpose is to send events to the server. The event SDK is also bundled with this SDK. The events that are sent are used as triggers to complete tasks, award badges or increase counters.

Observalyze is built with privacy in mind, see #Privacy for some notes on the topic.

Visit Observalyze for more information on how it can be used to increase engagement with your users through gamification AND gain more insight into what your users are doing on your platform.

Installation

First visit observalyze.com to create an account and then visit https://www.observalyze.com/app/projects to obtain the apiKey for your project.

There are two different methods of installation. If you use node or want to use observalyze in combination with a bundler:

npm i --save observalyze-ui-sdk

# You will then be able to do
# import { initialize } from 'observalyze-ui-sdk;

The other method is to include it via a script tag:

<script
  src="https://www.observalyze.com/sdk-ui"
  type="text/javascript"
  data-api-key="[your observalyze api key]"
  data-person="your-users-unique-identifier"
></script>

By using https://www.observalyze.com/sdk-ui you will always load the latest version of the SDK. We advise to pin the SDK to a major version, so that no incompatible changes to the SDK are automatically applied to your project. You can do this by adding a version to the URL: https://www.observalyze.com/sdk-ui@1, this will include SDK version 1.x in your project. You can also pin to a specific version, by using https://www.observalyze.com/[email protected].

Auto log is enabled by default in the browser, see below for more details.

Initialization

This UI SDK is to be used in a web application. It supports both SPA and MPA applications.

Via script tag

If you load the SDK directly from a script tag, a global variable observalyzeUISdk will be available. If you have provided the API Key and a data-person attribute the initialized will be available as observalyzeUI.

Via initialization method

If you use a bundler, or do not set an apiKey or person in the script tag, you need to manually initialize the SDK.

// via script tag
const observalyzeUI = observalyzeUISdk.initialize({ apiKey: 'xxx', person: 'xyz-person-id' });

// Via bundler
import { initialize } from 'observalyze-ui-sdk';

const observalyzeUI = initialize({ apiKey: 'xxx', person: 'xyz-person-id' });

// Using an already initialized event SDK
import { initialize } from 'observalyze-ui-sdk';

const observalyzeUI = initialize({ apiKey: 'xxx', person: 'xyz-person-id' }, observalyzeSdk);

There are more configuration options, those are explained below in the section on Configuration.

Usage

At initialization the SDK will automatically:

1. Connect to the observalyze backend for realtime updates
2. Show notifications to the user directly as they are arrive
3. Depending on the configuration, any configured automatic tagging will be executed

Besides those automatic features the SDK exposes some function you can invoke from code to show information:

// get the Event SDK
getSDK: () => Observalyze;
// Stop any running timers
stop: () => void;
// Change the person identifier originally configured with
setPerson: (person: string) => void;
// Attaches to an existing element and show an unread count badge
showUnreadCount: (element: HTMLElement) => () => void;
// Renders an inbox of messages for the user, including read messages
showMessages: (element: HTMLElement) => () => void;
// Show the currently active quest groups to person must aim to complete. If no element is provided a fixed list will be attached to the right side of the screen.
showQuestGroups: (element?: HTMLElement) => () => void;
// Renders a list of all badges that have been awarded to the person.
showBadges: (element: HTMLElement) => () => void;
// Toggles the dark or light theme
toggleDarkMode: () => void;
// Sets the dark mode setting. `true` is dark mode, `false` is light mode.
setDarkMode: (darkMode: boolean) => void;

Configuration

Obtain your API key by creating an Observalyze account, if you do not have one already. First, acquire the api key for your project from your projects page.

Then initialize the SDK in your application as explained earlier. The theme colors for the SDK are configured in the Project Appearance settings on the platform. For more information, see below.

All observalyze-sdk configuration options are available. If there is no globally available observalyze-sdk available or provided in the initialization, it will be initialized using the provided configuration.

| option | type | required | script attr | description | | ------ | ------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | string | Yes | data-api-key | The api key, retrieved from the projects page, linking the UI to your project. The API key determines whether you connect to your test or live environment. | | person | string | No | data-person | The identifier of the user you want to link all tracked events to | | debug | boolean | No | data-debug="true" | When set to true, logging will be send to the console, for debugging purposes. |

Theme & Colors

The colors for the User Interface are configured in the Project Appearance settings, these will be applied when the SDK initializes.

Dark and Light Mode

If you have configured both dark and light theme colors you can control the selection of the theme in different ways:

1. The system theme will be followed by default
2. Setting the class .oui-dark or .oui-light on the body tag will select the light or dark.
   1. You can use the setDarkMode(darkMode: boolean) or toggleDarkMode() functions of the SDK to control these values from code.

Further customization

If you want to additional customize some elements of the team, each UI element has a class, .observalyze-ui-container which you can reference in your own CSS file.

The configured UI colors are translated to CSS variables:

--oui-primary: #000000;
--oui-primary-lighter: #000000;
--oui-primary-darker: #000000;
--oui-accent: #09CFFD;
--oui-accent-lighter: #3DD9FD;
--oui-accent-darker: #02A9D0;
--oui-background: #efe8e8;
--oui-background-lighter: #FFFFFF;
--oui-background-darker: #C8B0B0;

Requester

The SDK uses fetch to send data by default, if available. Which is in the browser, and Node versions 18 or higher. If you are using the SDK in a non-browser environment and fetch is not available, you should provide your own HTTP implementation.

The requester is expected to adhere to the following interface:

export interface Requester {
  post: <T, D = unknown>(url: string, apiKey: string, data?: D | undefined) => Promise<HttpResponse<T>>;
  patch: <T, D = unknown>(url: string, apiKey: string, data?: D | undefined) => Promise<HttpResponse<T>>;
  put: <T, D = unknown>(url: string, apiKey: string, data?: D | undefined) => Promise<HttpResponse<T>>;
  get: <T>(url: string, apiKey: string) => Promise<HttpResponse<T>>;
  delete: <T>(url: string, apiKey: string) => Promise<HttpResponse<T>>;
}

Axios example

This is a sample implementation of a requester in typescript. It only contains a post implementation, but the implementation for the other functions are pretty similar.

const requester: Requester = {
  post: async function <T, D = any>(url: string, apiKey: string, data: D): Promise<HttpResponse<T>> {
    try {
      const response = await axios.post<T>(url, data, {
        headers: { Authorization: `Bearer ${apiKey}` },
      });
      return {
        statusCode: response.status,
        data: response.data,
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        return {
          statusCode: parseInt(error.status ?? '0', 10),
          data: error.response?.data ?? {},
        };
      }
    }

    return {
      statusCode: 0,
      data: {},
    };
  },
};

Privacy

This SDK will store two different values in the browser localStorage and sessionStorage. observalyze.client and observalyze.session are used to link the event to other events send from the same browser. observalyze.client will not be used if you provide your own client identifier in the configuration. Make sure that you have the users' consent before sending events that include a unique person identifier.

These values can be removed from localStorage and sessionStorage at any moment, the SDK will re-generate new values automatically.

Disclaimer

Note that Observalyze cannot be held liable in any way for any loss or damage as the result of the use of this package or the platform. Please use at your own risk.