@low6/play-box

@low6/play-box

@low6/play-box is a library for integrating with one or more of the games provided by Low6.

Installation

npm install @low6/play-box --save

Initialisation and data flow

sequenceDiagram
    participant Host as Host Website
    participant pb as PlayBox
    participant Game as Game

    Host->>pb: new GameClient(options)
    pb->>pb: Create & configure iFrame
    pb->>Host: Inject iFrame under predetermined div
    note right of Host: iFrame is now part of the host page DOM, <br/> but controlled by @low6/play-box lib
    pb->>Host: postMessage({ topic: "IFRAME_INITIALISED" })
    note right of Host: Host receives message indicating iFrame is initialized

    Game->>pb: Register listeners per message topic
    Host->>pb: Register listeners per message topic

    Host->>pb: Send message
    pb->>Game: Send message

    Game-->>pb: Respond
    pb-->>Host: Respond

Usage

Step 1: Allocate a suitable div in the host website with a unique id

<div id="play-box-container" className="h-full w-full flex-1 bg-red-100"></div>

Step 2: Initialise the PlayBox in the host website

import { GameFrame, LogLevel, PlayBoxInitialisationParams } from '@low6/play-box';

const initialisationOptions: PlayBoxInitialisationParams = {
  appId: 'test-app-id',
  clientId: 'test-client-id',
  environment: 'dev',
  language: 'en-GB',
  targetElementSelector: '#play-box-container', //? the id of the div allocated in step 1
  theme: 'light',
  logLevel: LogLevel.DEBUG,
};

new GameFrame(initialisationOptions);

Step 3: Register listeners per message topic in the host website

//? register for the unknown message topic
HostClient.getInstance().registerListener(MessageTopic.UNKNOWN, 'test-listerner-id', (message: PlayBoxMessage) => {
  //..
  //? do something with the message
  //..
});

HostClient.getInstance().registerListener(
  MessageTopic.IFRAME_INITIALISED,
  'test-listerner-id',
  (message: PlayBoxMessage) => {
    //..
    //? do something with the message
    //..
  }
);

Step 4: Send messages to the game

const playBoxMessage: PlayBoxMessage<string> = {
  timestamp: new Date().toISOString(),
  topic: MessageTopic.UNKNOWN,
  data: message,
};

HostClient.getInstance().emitMessageToIframe(playBoxMessage);

API Reference

---

PlayBoxInitialisationParams

Property	Type	Description
appId	string	ID of the app shown in the PlayBox; each game will have a unique ID
clientId	string	ID of the client; each game will have a unique ID
environment	'dev' | 'staging' | 'demo' | 'prod'	Environment name
iFrameUrlCompositionOverride?	IFrameURLComposition	Optional override for the iframe URL composition
language?	string	Language code (e.g., "en-GB"); defaults to "en-GB"
logLevel?	LogLevel	Logging verbosity; defaults to SILENT
targetElementSelector	string	Selector of the element to which the PlayBox is attached
theme?	string	Theme used by the PlayBox; defaults to "default"
userPersonalisation?	UserPersonalisation	Optional user-specific settings for personalization

IFrameURLComposition

Property	Type	Description
baseUrl	string	Base URL for the iframe
path	string	Path that follows the base URL

---

UserPersonalisation

Property	Type	Description
cookieConsent?	boolean	Indicates if the user has consented to cookies (optional)
ssoUserId?	string	Single sign-on user ID (optional)
ssoSessionId?	string	Single sign-on session ID (optional)

---

LogLevel

Member	Value	Priority
SILENT	"silent"	Highest (no output)
DEBUG	"debug"	Lowest (debug messages)
INFO	"info"
WARN	"warn"
ERROR	"error"

Order of priority: DEBUG < INFO < WARN < ERROR < SILENT

Supported message topics

Member	Value	Description
IFRAME_INITIALISED	"IFRAME_INITIALISED"	Sent when the iframe has finished initializing
APP_STATE_UPDATE	"APP_STATE_UPDATE"	Sent when the app state has been updated
REQUEST_USER_AUTH_INFO	"REQUEST_USER_AUTH_INFO"	Request for user authentication information sent from the game to the host
RESPONSE_USER_AUTH_INFO	"RESPONSE_USER_AUTH_INFO"	Response containing user authentication information sent from the host to the game
UNKNOWN	"UNKNOWN"	Used for unrecognized message topics

Local development using pnpm

Clone and build the library

pnpm install
pnpm build

Link the package

pnpm link --global

Use the package in a project

pnpm link --global @low6/play-box
pnpm install