@stillfront-paymenthub/canvas-agent v1.10.0

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

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...'
}