Migration from 2.x

This guide covers migrating from the Video Canvas 2.x player (versions 2.5 through 2.8) to the 3.0 player. The 3.0 player is a complete rewrite with a new SDK, new branding API, updated browser requirements, and new events.

Package and SDK changes

NPM package

Update your .npmrc:

# Before (2.x)
@money-alive:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=YOUR_TOKEN

# After (3.0)
@fcxtech:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=YOUR_TOKEN

# Before
npm install @money-alive/data-canvas-player

# After
npm install @fcxtech/player

Player creation

The 2.x SDK used class constructors. The 3.0 SDK uses factory functions:

// Before (2.x)
import { LightboxPlayer } from '@money-alive/data-canvas-player'
const player = new LightboxPlayer(options)

// After (3.0)
import { lightbox } from '@fcxtech/player'
const player = lightbox(options)

// Before (2.x)
import { InlinePlayer } from '@money-alive/data-canvas-player'
const player = new InlinePlayer(options)

// After (3.0)
import { inline } from '@fcxtech/player'
const player = inline(options)

Hosted SDK (script tag)

If using the SDK via a script tag, the global methods remain the same:

// Same in both versions
VC.lightbox(options)
VC.inline(options)

Configuration changes

Next Steps

The 3.0 player introduces a new V2 Next Steps format with header + steps[]. However, the old 2.x format still works — the player automatically converts it internally. No migration is required unless you want to use the new format's additional features (multiple steps, richer content types).

// 2.x format — still works in 3.0, no changes needed
nextSteps: {
  title: 'What happens next?',
  text: 'Choose an option below.',
  buttonText: 'Visit website',
  buttonAction: 'https://example.com',
  secondButtonText: 'Download PDF',
  secondButtonAction: 'https://example.com/doc.pdf',
}

// New 3.0 V2 format (optional upgrade)
nextSteps: {
  header: {
    headingText: 'What happens next?',
    bodyText: 'Choose an option below.',
  },
  steps: [ /* use the Next Steps Editor to generate */ ],
}

Use the Next Steps Editor to build the V2 steps configuration visually.

Branding migration

The 2.x branding used flat properties with hex values. The 3.0 branding uses a structured branding object with the colors, typography, fonts, and logo sub-objects.

Example migration

// Before (2.x)
branding: {
  brandColor: '#ba3000',
  playButtonColor: '#ba3000',
  ctaButtonColor: '#ba3000',
  accessibilityFocusColor: '#FFFFFF',
  menuCurrentItemColor: '#ba3000',
  recapPositiveColor: '#ba3000',
  recapNegativeColor: '#ba3000',
  recapCheckmarkColor: '#ba3000',
  logoWidth: '15em',
  logo: 'https://example.com/logo.jpg',
}

// After (3.0)
branding: {
  colors: {
    brandColor1: 'rgb(186 48 0)',
    brandColor1Text: 'rgb(255 255 255)',
    keyboardFocus: 'rgb(255 255 255)',
  },
  logo: {
    imageUrl: 'https://example.com/logo.jpg',
    imageWidth: '240px',
  },
}

Key changes:

• Color format: 2.x used hex values (#ba3000). 3.0 uses CSS color syntax (rgb(186 48 0)).
• Simplified: In 3.0, setting brandColor1 automatically themes play buttons, CTA buttons, menu active state, recap elements, and other branded UI. You no longer need to set each one individually.
• Text colors: 3.0 adds brandColor1Text for specifying text/icon color on branded elements.
• Logo width: 2.x used em values. 3.0 uses px values.
• Three brand levels: 3.0 supports brandColor1, brandColor2, brandColor3 (each with a matching text color) for multi-tone branding.

Custom CSS migration

Custom CSS has moved inside the branding object and the selector format has changed:

// Before (2.x) — top-level, using :host() selectors
customCss: ':host(video-canvas) { --playButtonColor: green; }'

// After (3.0) — inside branding, device-targeted, no :host() needed
branding: {
  customCss: [{
    name: 'all',
    value: '.sx-button--theme-video-primary { background-color: green; }',
  }],
}

In 3.0, each custom CSS rule automatically has !important appended. Custom CSS only applies to "watch" mode. Device targeting (desktop, mobile-portrait, etc.) replaces media queries.

Recap CSS variables

In 2.x, Recap V2 theming required manually setting CSS variables via customCss with :host(video-canvas) selectors. In 3.0, these are set automatically from brandColor1 and brandColor1Text, or can be overridden via branding.cssVariables.

Browser support changes

Events migration

Changed events

New events in 3.0

Event payload changes

In 2.x, events used payload and vcId. In 3.0, they use data and id:

// Before (2.x)
player.on('ready', (event) => {
  console.log(event.payload)  // event data
  console.log(event.vcId)     // module ID
})

// After (3.0)
player.on('ready', (event) => {
  console.log(event.data)     // event data
  console.log(event.id)       // module ID
})

Player API changes

All 2.x player methods remain the same: show(), hide(), destroy(), setMode(), on(). The player.player property still gives access to the DOM element. 3.0 adds play() and pause() methods on both inline and lightbox players for programmatic playback control.

Content module compatibility

Content modules produced for 2.x are compatible with the 3.0 player. No re-production of content is required. The 3.0 player handles both V2 and V2.1 manifest formats.

Migration checklist

• Update .npmrc to use @fcxtech scope
• Install @fcxtech/player, remove @money-alive/data-canvas-player
• Change new LightboxPlayer() / new InlinePlayer() to lightbox() / inline()
• Rename origin to dataOrigin
• Move customCss into branding.customCss array format
• Migrate branding properties to branding.colors (see table above)
• Convert logo width from em to px
• Update event listeners: payload → data, vcId → id
• Replace recap-statement-answered with recap
• Remove showA11yModeButton from config
• Verify browser support meets 3.0 minimums for your audience
• Test with existing content modules (no re-production needed)