Skip to Content
Advanced tools for developersWidget API

Cinema8 Widget API

Build interactive widgets with JavaScript, CSS, and Handlebars templating

Widgets are reusable components that run inside the Cinema8 player. You can use the default widgets or develop your own using the Cinema8 Widget Development Environment.

See also: Widget Playground

Widget Basics

  • Widgets are embedded on the video timeline.
  • They support dynamic properties, actions, and runtime control.
  • You can configure widgets via Creative Studio.

Common Widget Properties

All widgets inherit:

  • name
  • start, end
  • visible
  • onStart, onEnd, onClick
  • position (percentage-based)

You can also define your own custom props (e.g., text, color, video).

Supported Property Types

  • Text (string)
  • Text Area (multiline string)
  • Color (hex string)
  • Image (URL)
  • Video (URL)
  • Boolean
  • Text List (array)
  • Image List (array)
  • Select (dropdown)
  • Action (clickable)

Accessing Parameters

HTML

Use Handlebars templates:

<p>{{text}}</p>

Lists:

<ul>
  {{#each textList}}
    <li>{{this}}</li>
  {{/each}}
</ul>

JavaScript

c8PlayerApi.getWidgetProps()
c8PlayerApi.getWidgetProp('textArea')

Unique IDs:

$('.c-{{uid}} .widget-button').click(() => {
  console.log(c8PlayerApi.getWidgetProp('text'))
})

CSS

.c-{{uid}} {
  background: {{color}};
  padding: 1rem;
}

Using {{uid}}

Ensures unique styling and DOM selection:

  • HTML: <div class="c-{{uid}}">
  • CSS: .c-{{uid}} {}
  • JS: $('.c-{{uid}}')

Accessing Runtime Data

c8PlayerApi.getTrackProps()
c8PlayerApi.getTrackProp('duration')

Authenticated user:

const user = c8PlayerApi.getAuthenticatedUser()

Video Control APIs

c8PlayerApi.play()
c8PlayerApi.pause()
c8PlayerApi.currentTime()
c8PlayerApi.volume(0.5)
c8PlayerApi.subtitle("en")
c8PlayerApi.audioTrack(1)
c8PlayerApi.qualityLevel("auto")

Variable Storage

c8PlayerApi.setVariable('score', 10)
c8PlayerApi.getVariable('score')

Persistent variables:

c8PlayerApi.setVariable('userChoice', 'A', true)

Saving Data

c8PlayerApi.postData({ feedback: 'Great!' }).then(console.log)

Retrieve data:

c8PlayerApi.getData().then(console.log)

Runtime Events

c8PlayerApi.on("play", () => { ... })
c8PlayerApi.on("pause", () => { ... })
c8PlayerApi.on("visibilityChange", visible => { ... })
c8PlayerApi.on("variableChange", (key, prev, next) => { ... })

Executing Actions

c8PlayerApi.executeWidgetPropActions('onImageHover')

Using Clickable Props

Enable “isClickable” in Studio and bind:

<li data-onclick-ref="textList">Item</li>

Handlebars Helpers

<#Handlebars>
  Handlebars.registerHelper("uppercase", val => val.toUpperCase())
</#Handlebars>

Then in HTML:

{{uppercase text}}
⚠️

Need help? Visit the Widget Playground for examples.

Authentication & SSOCinema8 Private Token API