Overview

An Extension is an API or service which extends platform functionality without affecting the core platform.

Extensions are backend components such as special gamification functionality. They plug into the platform, optionally making available UI for configuration and management via Studio tabs.

Extensions must be created by partners, in-house teams or by the Monterosa Solutions team. Before moving into production, Monterosa must approve of the Extension. Please contact your account manager or raise a support ticket for more information via [email protected]

An Extension needs to implement:

• Extension - instance handshake protocol so that it can be added to a platform's instance

• Extension - Project handshake protocol so that it can be added to a platform's Project.

An Extension can visually integrate into Studio, aid data collection for a Creator and provide data for the App and feeds by providing:

• Studio tabs

• Analytics API

• Field data source

• Assets

• Extension feeds

An Extension can subscribe to Notifications to be notified of data changes made within the platform.

All requests between an Extension and the platform are signed for security reasons. See Signing requests.

Signing requests

All requests to 3rd party Extension are backend-to-backend and signed with Extension access token. Access token is created Extension deployment time, stored in both the Extension and the platform, and not communicated between them (pre-shared).

Signature calculation

signature = SHA1(access_token + signeable_content + salt)

signable_content is a concatenation of the following:

• Resource path (including leading slash, e.g. ”/path/to/script”)

• Query string (including leading question mark, e.g. ”?attr=value”)

• POST data

salt is a random string, it should change from request to request and be sufficiently random.

Salt and generated signature are sent in HTTP headers:

• X-LViS-Salt

• X-LViS-Signature

Receiving end calculates signature from the access_token stored locally and data from the request and checks if it matches the one in the request. Any request failing signature check must return 403 forbidden.

Instance handshake

To add an Extension to a platform's instance, super admin is to provide three parameters:

• Base URL

• Access token

• Name (used to identify the service in Studio UI)

To complete adding an Extension, the platform sends an Instance handshake request to it.

Raise a support ticket to organise new Extension setup tasks

Extension types

• leaderboard

• submissions

• demographics

• timerelease allows to set a lock on assets, like images uploaded for a media element, so that even if the client application knew the url to the asset, the user would not be able to view it until a specific point in time.

Project handshake

An application specifies which Extension(s) it needs. When a Project is created, the platform enables all required Extensions automatically.

The platform sends a Project handshake request to the Extension in the following cases:

• A new Extension has been added to the Project

• Extension config in the app is changed

• Project name is changed

Studio Tabs

Tabs are entries in Studio main menu.

Tabs are fetched by sending a request to the Extension when a Project or an Event is selected in Studio:

• Project-specific tabs

• Event-specific tabs

Tab icon

An icon that is shown for the Extension tab on Studio main menu. Can be any Font Awesome 5.14 icon that support fal prefix including pro icons. To specify an icon the tabs response must contain icon field with name of the desired icon. By default Studio use th icon.

Example

[
  {
    "name": "Event Segments",
    "level": "e",
    "url": "https://example-extension.mic.io/tabs/projects/b10be847-2d51-49b3-a9f9-2429434763d7/event_segments",
    "icon": "address-book"
  }
]

Extension setup

An extension may provide a setup object. This setup object is used in handshake requests for a project created from experience where the extension is used. And can be used to specify data required to set up the extension in a new project.

Auth endpoint

An Extension can check users access rights making Project access or Super admin access request.

Project access

Project access

GET https://environment.lvis.io/p/:project_id/sessions/:user_session_token?service_id=demographics

Path Parameters

Name	Type	Description
project_id	string	ID of the project.
user_session_token	string	User session token.

Query Parameters

Name	Type	Description
service_id	string	Service identifier.

200

{
  "id": 3, // authenticated user id
  "role": "creator" // user's role in context of requested project
}

401

{}

Super admin access

Super admin access

GET https://environment.lvis.io/sa_sessions/:user_session_token?service_id=demographics

Path Parameters

Name	Type	Description
user_session_token	string	User session token.

Query Parameters

Name	Type	Description
service_id	string	Service identifier.

200

{
  "id": 3, // authenticated user id
  "role": "super_admin" // user's role in context of requested project
}

401

{}

Notifications

The notifications mechanism is deprecated and will be removed soon. Use webhook events instead when possible.

The purpose is to allow an Extension to use Studio as Event/Element management system, where some processing is done by the Extension. To enable this Studio notifies the Extension whenever data changes are made in Studio. When notified the Extension then fetches up-to-date data from the platform using feeds or Control API.

Please note that notification does not guarantee that any of the data was actually changed after the previous notification, or that the current state of the object is final and complete. So the Extension should track changes by itself.

There can be a lag of a couple of seconds between a change and notification.

On success the Extension needs to respond with 200 and empty body.

On error the Extension needs to respond with corresponding status and empty body.

These are supported notification types:

• Listings notification

• Elements notification

Analytics API

This API allows adding a tab with Extension analytics data to the Event's analytics page. The platform enables this feature according to corresponding flag in instance handshake response. The platform makes Analytics request to the Extension to get its data.

Field data source

An Extension can act as a data source for a custom field, providing dynamic content.

Assets

An Extension can provide assets which the platform passes to the App. The platform fetches assets from the Extension by calling Assets.

Extension feeds

Each Extension can provide Extension-specific data feeds. These feeds will be requested from the Extension and uploaded to the public CDN by the platform. Feeds list is configured during instance handshake in the handshake response.

Event feeds are uploaded periodically while event is running. The platform fetches Extension specific Event data feed by calling Event-level feed.

Uploaded public feed will be listed on the Event feeds page, and available at the following URL:

//<static_host>/events/<first two chars of event uuid>/<event uuid>/<extension_type>/<feed_id>.json

Webhook events

Subscribing to webhook events is a way to integrate with the platform and perform actions in response to changes, without the need for periodic API pooling.

See webhooks description for more details.