PokeDemo Player SDK API

Use this page when you are embedding an exported demo and need the stable public player contract.

Packages

How to install

npm i @pokedemo/player

pnpm add @pokedemo/player

bun add @pokedemo/player

Separated framework adapters using imports

• @pokedemo/player/react
• @pokedemo/player/vue

Core usage

import '@pokedemo/player/style.css'
import { PokePlayer } from '@pokedemo/player'

const container = document.getElementById('player')!

const player = new PokePlayer(container, {
  source: {
    baseUrl: 'https://example.com/path-to-bundle-manifest-root',
  },
  network: {
    fetch: window.fetch.bind(window),
  },
})

player.on('ready', () => console.log('ready'))
player.on('error', (error) => console.error('error', error))

The required configuration is source.baseUrl.

Config shape

type PokePlayerConfig = {
  source: { baseUrl: string }
  network?: { fetch?: typeof globalThis.fetch }
  ui?: {
    className?: string
    injectCss?: boolean
    startOverlay?: StartOverlayOptions
    endOverlay?: EndOverlayOptions
    stepOverlay?: StepOverlayOptions
  }
  advanced?: {
    retry?: RetryOptions
    prefetch?: PrefetchOptions
    runtimeHooks?: boolean
  }
}

Overlay options

Overlay behaviour should generally be configured from the PokeDemo web editor.

In most cases, we do not recommend you should change these options, but there are some situations where someone would want to customize it directly in code:
- Dynamic 'title' and/or 'message' based on current user's details
- A/B testing
- Dynamic theme customization

type StartOverlayOptions = {
  enabled?: boolean
  title?: string
  message?: string
  ctaLabel?: string
  opacity?: number
  cardColor?: string
  buttonColor?: string
  textColor?: 'white' | 'black'
}

type EndOverlayOptions = {
  enabled?: boolean
  title?: string
  message?: string
  ctaLabel?: string
  replayLabel?: string
  showReplay?: boolean
  opacity?: number
  cardColor?: string
  buttonColor?: string
  textColor?: 'white' | 'black'
}

type StepOverlayOptions = {
  instruction?: string
  anywhereInstruction?: string
}

Overlay config sample

import type { PokePlayerConfig } from '@pokedemo/player'

const customTitle: string = ...

const config: PokePlayerConfig = {
  source: {
    baseUrl: 'https://example.com/path-to-bundle-manifest-root',
  },
  ui: {
    startOverlay: {
      enabled: true,
      title: customTitle,
        ...
    },
    endOverlay: {
      enabled: true,
        ...
    },
  }
}

Advanced config

import type { PokePlayerConfig } from '@pokedemo/player'

const config: PokePlayerConfig = {
  source: {
    baseUrl: 'https://example.com/path-to-bundle-manifest-root',
  }, 
  // Everything below is optional and should rarely change
  advanced: {
    retry: {
      maxRetries: 2,
      baseDelayMs: 500,
    },
    prefetch: {
      window: 1,
      enabled: true,
    },
    runtimeHooks: false,
  }
}

API

All the available methods that you can call on any given PokePlayer instance

• start()
• pause()
• resume()
• goToStep(index)
• nextStep()
• restart()
• getState()
• getCurrentStep()
• getTotalSteps()
• getSpeed()
• setSpeed(speed)
• destroy()
• PokePlayer.create(container, config)
• ready promise
• event subscription via on(...), once(...), and off(...)

Events

Quick list of emitted events

• ready
• start
• error
• stepChange
• stepStart
• stepEnd
• pause
• finish
• progress
• overlayShown
• overlayClick
• destroy

Sample event payloads:

• error: (error: Error)
• stepChange: (stepIndex: number, step: StepTimeBounds | null)
• stepStart: (stepIndex: number, step: StepTimeBounds)
• stepEnd: (stepIndex: number, step: StepTimeBounds)
• pause: (stepIndex: number, step: StepTimeBounds)
• progress: (currentStep: number, totalSteps: number, timeMs: number)
• overlayShown: (event: OverlayEvent)
• overlayClick: (event: OverlayEvent)

CSS behavior

Import the public stylesheet explicitly in your app:

import '@pokedemo/player/style.css'

React

import '@pokedemo/player/style.css'
import { PokePlayer } from '@pokedemo/player/react'

export function DemoPlayer() {
  return (
    <PokePlayer
      baseUrl="https://example.com/path-to-bundle-manifest-root"
    />
  )
}

Public props:

type PokePlayerProps = {
  baseUrl: string
  fetch?: typeof globalThis.fetch
  autoplay?: boolean
  injectCss?: boolean
  style?: CSSProperties
  className?: string
  onReady?: () => void
  onError?: (error: Error) => void
  onStart?: () => void
  onPause?: (payload: { stepIndex: number; step: StepTimeBounds }) => void
  onFinish?: () => void
  onStepChange?: (payload: { stepIndex: number; step: StepTimeBounds | null }) => void
}

Vue

<script setup lang="ts">
import '@pokedemo/player/style.css'
import { PokePlayer } from '@pokedemo/player/vue'
</script>

<template>
  <PokePlayer
    base-url="https://example.com/path-to-bundle-manifest-root"
  />
</template>

Public props:

{
  baseUrl: string
  fetch?: typeof globalThis.fetch
  autoplay?: boolean
  injectCss?: boolean
}

Public emits:

• ready
• error
• start
• pause
• finish
• step-change

Useful emitted payloads:

• error: Error
• pause: { stepIndex: number; step: StepTimeBounds }
• step-change: { stepIndex: number; step: StepTimeBounds | null }