canvas-agent

An agent to initialize and manage Canvas storefront instances.

Usage

Using import

npm i @stillfront-paymenthub/canvas-agent

import CanvasAgent from '@stillfront-paymenthub/canvas-agent'

... or HTML <script> before JS

<script src="https://cdn.jsdelivr.net/npm/@stillfront-paymenthub/canvas-agent" type="text/javascript"></script>

Initiate a Canvas instance

This example will initiate a Canvas instance in fullscreen mode and open it once a session could be successfully created.

let canvasInstance

const handleCanvasEvent = (event) => {
    const actions = {
        ready: () => canvasInstance.show()
        error: () => //... handle failure, e.g. 'could not load shop'
        expired: () => //... handle expired token, e.g. get new token and recreate instance
    }

    actions[event.eventType]?.()
} 

canvasInstance = await CanvasAgent.create({
    canvasAppId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    token: 'ey0ab76c9d823e645ff0....',
    eventListener: handleCanvasEvent,
    locale: 'de-DE',
    customContext: {
        playerSegment: 1 // e.g. A/B test
    }
})

Parameters

| Parameter | Type | Required | Description | | --------------- | ----------- | -------- | ----------- | | canvasAppId | string | Yes | Application Id from the Canvas client customization store, e.g. 1a70cd16-7ff2-48ad-bbcf-bf509072132e | | token | string | Yes | Your authentication token that will be validated against your identity backend by Hydra, e.g. a JWT. | | forceAuth | boolean | No | Force Canvas authentication flow, ignoring a client-cached session. Default: false | | eventListener | function | No | Provide a function reference that will be called on each Canvas event. | | frameParent | HTMLElement | No | The DOM node used to attach the Canvas client iframe, default: document.body | | fullScreen | boolean | No | Embed type; whether the storefront should open in full screen or become part of the host page. Default: true | | locale | string | No | Pass the locale as the country with the region designator, e.g. en-US, default: navigator.language() | | sessionId | string | No | Pass a specific session id, e.g. for cross channel tracking purposes. Default: nanoid() | | customContext | object | No | Pass an object of custom context parameters that be will merged by override with your custom context from the Canvas client customization.

Instance methods

create(parameters)

Create a new Canvas client instance. Hidden after initation.

show()

Show the canvas instance. Needs to be called after initiation to display the storefront.

hide()

Hide the canvas instance

destroy()

Destroy a canvas instance

getAppState()

Inspect current app instance state: initializing | ready | error

getState()

Inspect current agent state including passed parameters and app state.

reward(offerId)

Fire reward dialog for a specific offer.

navigate(collectionId, offerId?)

Navigate to a specific collection, and optionally to a specific offer detail page.

checkout(offerId)

Force checkout of a specific offer.

Events reference

The provided eventListener will be called with the event object as single argument eventListener(event).

Error

A blocking error occured, halting the application. ⚠ Needs to be handled.

{
    eventType: 'error',
    message: 'Authentication failed to retrieve token'
}

Expired

The token has expired, keeping the application from getting fresh data or creating checkout sessions. ⚠ Needs to be handled.

{
    eventType: 'expired'
}

Ready

The application has successfully initialized and is ready to be opened.

{
    eventType: 'ready'
}

Close

The player has closed the application.

{
    eventType: 'close'
}

Navigate

The player has navigated.

{
    eventType: 'navigate',
    fromPath: '/collection/6f440ba6-9028-49b2-9e94-aac3603b7f3a',
    toPath: '/collection/eacd5674-e9cc-4c50-aec2-59bfcb693744'
}

Checkout

The player has started a checkout.

{
    eventType: 'checkout',
    offerId: 'f4a6...'
}