@skolon/widget-sdk v0.2.0

Skolon Widget SDK

An SDK for creating widgets in Skolon, providing an API to interact with Skolon through a widget.

Widgets are small and simple web apps for users to quickly view and interact with, available right in their app collection.

They can be used to show users up to date information from your platform, or give them easy access to common actions.

Table of contents

1. Installation
2. Example Usage
3. Sandboxing
4. API

Installation

yarn add @skolon/widget-sdk

or

npm install @skolon/widget-sdk

Example Usage

Widget

import {
    init,
    loadSettings,
    saveSettings,
    openModal,
    registerSettingsCallback,
} from "@skolon/widget-sdk";

let state = { language: "en-gb", useMetric: true };

init()
    .then(({ preferredLanguage }) => {
        state.language = preferredLanguage;
        return loadSettings();
    })
    .then((settingsString) => {
        if (settingsString) {
            const settings = JSON.parse(settingsString);
            state = { ...settings, language: state.language };
        }

        registerSettingsCallback(() => {
            openModal(
                `https://my-site/widget/settings?useMetric=${state.useMetric}`
            ).then((response) => {
                if (response.closedBy === "Modal" && response.responseData) {
                    const { useMetric } = JSON.parse(response.responseData);

                    state.useMetric = useMetric;
                    saveSettings(JSON.stringify(state));
                }
            });
        });
    });

Modal

import { init, closeModal } from "@skolon/widget-sdk";

let state = { language: "en-gb", useMetric: true };

init().then(({ preferredLanguage }) => {
    state.language = preferredLanguage;

    const queryParams = new URLSearchParams(location.search);
    // Initialize the preselected value to the user's current setting
    state.useMetric = queryParams.get("useMetric");

    // Close the modal and notify the widget of the updated useMetric setting when
    // the user submits the form
    document.querySelector("form").addEventListener("submit", (event) => {
        event.preventDefault();

        closeModal(JSON.stringify({ useMetric: state.useMetric }));
    });

    document.querySelector("#cancel-button").addEventListener("click", () => {
        // Close the modal without sending any updated settings if the user clicks
        // cancel
        closeModal();
    });
});

Guide

A guide for writing an example widget can be found here

Sandboxing

The widgets are loaded in a sandboxed iframe, which results in some restrictions in what can be done. This is done using the iframe sandbox attribute.

The only permissions given are allow-scripts and allow-same-origin. For a full list of permissions not given, see MDN.

Some of the things blocked by the sandbox can instead be done using this SDK, such as opening links using openTab.

Getting data about the user

Getting authorized data about the user can be done through Skolon's APIs, the same way it is done for integrations of regular edtech apps.

API

Table of Contents

• init
• registerSettingsCallback
  • Parameters
• openTab
  • Parameters
• saveSettings
  • Parameters
• loadSettings
• openModal
  • Parameters
• closeModal
  • Parameters
• externalLogin
  • Parameters
• notifyExternalLoginSuccess
  • Parameters
• notifyExternalLoginFailure
  • Parameters
• getAuthCode
  • Parameters
• WidgetSize
  • Properties
• InitData
  • Properties
• ModalResponse
  • Properties
• ExternalLoginResponse
  • Properties
• OpenModalOptions
  • Properties

init

Initiates the library. This should always be the first method called when used in a widget or modal.

Returns Promise<InitData>

registerSettingsCallback

Tells Skolon to render a settings button for the widget. The provided callback will be called when the user clicks the button.

Parameters

• callback Function

Returns Promise

openTab

Opens an url in a new tab in the user's browser. This should only be done on user interaction, as it may otherwise be blocked.

Parameters

• url string The URL of the tab to open

Returns Promise

saveSettings

Saves user specific settings. The saved data will be available for widgets and modals for the user on all devices.

Parameters

• settings string A string representing the settings to save, for example serialized JSON. 16383 characters or shorter.

Returns Promise

loadSettings

Loads previously saved settings.

Returns Promise[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?

openModal

Opens a modal displaying an iframe with the specified URL. Only callable from the main widget.

Parameters

• url string The url to render in the modal.
• options OpenModalOptions? Options for how the modal should be rendered. (optional, default {})

Returns Promise<ModalResponse> A promise that resolves once the modal is closed.

closeModal

Closes the modal and optionally send data to the widget. Only callable from a modal.

Parameters

• data string? A string representing the settings to save, for example serialized JSON. (optional, default null)

Returns Promise

externalLogin

Initiates a login flow to a non-Skolon service in a new tab. The final callback URL should call either notifyExternalLoginSuccess or notifyExternalLoginFailure. Only callable from the main widget.

Parameters

• url string The URL that initiates the login flow

Returns Promise<ExternalLoginResponse> A promise that resolves once either notifyExternalLoginSuccess or notifyExternalLoginFailure is called by a page in the login flow.

notifyExternalLoginSuccess

Notifies the widget that the login was successful

Parameters

• data string? A string representing the settings to save, for example serialized JSON. (optional, default null)

Returns Promise

notifyExternalLoginFailure

Notifies the widget that the login failed

Parameters

• data string? A string representing the settings to save, for example serialized JSON. (optional, default null)

Returns Promise

getAuthCode

Gets an OAuth authorization code that can be exchanged for an access token for Skolon's API.

This is a preview feature, and may be subject to change.

Parameters

• clientId string The client ID of your application
• scopes Array[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)? A list of scopes to request (optional, default [])

Returns Promise[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) A promise resolving to an OAuth authorization code. This promise will reject if the user doesn't approve the requested scopes

WidgetSize

Type: Object

Properties

• width number The number of slots in the grid that the width of the widget covers. Either 1 or 2.
• height number The number of slots in the grid that the height of the widget covers. Either 1 or 2.

InitData

Type: Object

Properties

• widgetSize WidgetSize
• preferredLanguage string The user's preferred language. An ISO 639-1 language code optionally followed by a ISO 3166-1 alpha-2 country code. E.g. 'sv' or 'en-gb'.

ModalResponse

Type: Object

Properties

• closedBy ("Skolon" | "Modal")
• data string? The data provided in the call to closeModal. Will always be null if closed by Skolon

ExternalLoginResponse

Type: Object

Properties

• success boolean True if notifyExternalLoginSuccess was called, false if notifyExternalLoginFailure was called.
• data string? The data passed to notifyExternalLoginSuccess or notifyExternalLoginFailure, if any.

OpenModalOptions

Type: Object

Properties

• size ("small" | "medium" | "large")? Size of the modal.