ReelFlow Player API Reference

Core Concepts

You will see us refer to Flows in this guide. Flows are the choose-your-own-adventure video experiences that are presented in the ReelFlow Player. The Flow is advanced and explored by the visitor using the configurable Action Buttons. Flows can be built and managed directly, in the ReelFlow Flow Builder.

A Flow can be configured to use one of two Player types:

• Overlay - an interactive video experience that floats in the corner of the screen, over existing page content
  • The Overlay Player is hidden by default, and is launched from a smaller floating video preview on a loop called an Eye-Catcher

• Inline - an interactive video experience that sits inline amongst content
  • The Inline Player is visible by default and unlike the Overlay Player does not have an Eye-catcher component.

An instance of the ReelFlow Player therefore may consist of these key components:

• Eye-catcher - to launch the Flow (Overlay Players only)
• Player - the video player with all controls and user-configurable Action Buttons
• Flow - the video content and Action Buttons

The ReelFlow experience is always injected into the page, which means customers are not required to edit the HTML of the page to enjoy publishing Flows. We therefore do not offer a HTML embed code per-Player. 

Getting Started

As long as the Install Code is already added and verified working on your website (check from the Dashboard at Settings > Install Code), the Player API is available for you to use.

Initialising & accessing the ReelFlow Object

We use the defer attribute, which means the ReelFlow Player is loaded asynchronously.

You therefore should wait for the reelflow:ready event:

window.addEventListener('reelflow:ready', () => {
    // ReelFlow object is now available and initialized
    var targetFlow = ReelFlow.getFlow("F-123456ABCD");
    
    targetFlow.player.show();
});

Interacting with a specific flow

Flow IDs can be found in the Flow Builder, and will look something like this: F-123456ABCD.

// Get Flow instance with ID  'F-123456ABCD'
ReelFlow.getFlow('F-123456ABCD').eyeCatcher.show()
ReelFlow.getFlow('F-123456ABCD').eyeCatcher.on(/* ... */)
ReelFlow.getFlow('F-123456ABCD').player.play()
ReelFlow.getFlow('F-123456ABCD').player.on(/* ... */)

To identify which Flows and their types are available on the page, you can use the ReelFlow.getAvailableFlows() function. This can be useful in cases when you do not wish to hardcode a specific Flow ID, yet target a Flow you know is published on the page.

Swapping two Flows

If you want to swap one flow with another, we recommend this approach:

// Swapping a Flow that is playing   
ReelFlow.getFlow('F-123456ABCD').player.hide()
ReelFlow.getFlow('F-9988776XYZ').player.show()

// Or, if swapping the eye-catcher  
ReelFlow.getFlow('F-123456ABCD').eyeCatcher.hide()
ReelFlow.getFlow('F-9988776XYZ').eyeCatcher.show()

Using any link or page element to launch a Flow

If you wish to start a Flow from a click or other action on a webpage, you don't have to use the API for this, you can achieve this by adding one of our reserved HTML classes or target links, which also makes it easy for non-technical users to enable it via a normal CMS. Learn about using this feature here.

Global Methods

getFlow()

To retrieve and interact with a specific Flow.

// Returns a Flow object 
var targetFlow = ReelFlow.getFlow('F-123456ABCD');

// If an invalid ID is specified, it returns `undefined`

getAvailableFlows()

To retrieve all Flows, their IDs and identifies their types.

var pageFlows = ReelFlow.getAvailableFlows();

/* -- Returns the following structure --
[
    {
        "code": "F-6925bde53d273",
        "type": "overlay"
    },
    {
        "code": "F-6925bdee3e8d3",
        "type": "inline"
    }
]
*/


/* 
Using this you can locate and target a specific Flow 
by it's Flow code e.g. F-123456ABCD or isolate by type
*/

if (pageFlows.length > 0) {
 pageFlows[0].eyeCatcher.show();
 console.log(pageFlows[0].code); // Shows the code of the first Flow 
 console.log(pageFlows[0].type); // Shows the type e.g. inline or overlay
}

removeAll()

Completely removes all Flows on a page, including their eye-catcher and player components.

// Removes all Flows on the page from DOM
ReelFlow.removeAll();

getWorkspaceId()

To retrieve the ID of Workspace the Flows belong to.

// Returns Workspace ID 
var workspaceId = ReelFlow.getWorkspaceId();
// returns 'W-12345678';

Flow object

remove()

Completely removes a single Flow, including the eye-catcher and player component from the page.

// Remove a specific Flow from DOM
ReelFlow.getFlow('F-123456ABCD').remove();

Components

Eye-catcher (ReelFlow.eyeCatcher)

Controls the floating video preview component. The eye-catcher property doesn’t exist for the inline player type.

// Prints "undefined" for inline-type player
console.log(ReelFlow.getFlow("F-123456ABCD").eyeCatcher); 

Methods:

show()

Shows the eye-catcher if hidden.

Note: This only affects visibility; the component remains in the DOM even when hidden.

ReelFlow.getFlow("F-123456ABCD").eyeCatcher.show();

hide()

Hides the eye-catcher if visible.

Note: This only affects visibility; the component remains in the DOM even when hidden.

ReelFlow.getFlow("F-123456ABCD").eyeCatcher.hide();

disable()

Prevents the eye-catcher from appearing. Please note that it’s still will be rendered (available in the DOM), just won’t be shown to the user.

Call before other statements. Call show() to re-enable.

// To disable 
ReelFlow.getFlow("F-123456ABCD").eyeCatcher.disable();

// To re-enable, call show()
// ReelFlow.getFlow("F-123456ABCD").eyeCatcher.show();

Player (ReelFlow.player)

Controls the main video player component.

Methods:

show()

Shows the player if hidden. Optionally starts playing from a specific video in the flow.

// Show player with current video
ReelFlow.getFlow("F-123456ABCD").player.show();

hide()

Hides the player if visible.

ReelFlow.getFlow("F-123456ABCD").player.hide();

Events:

actionButton

Triggered when an action button is clicked. 

var targetFlow = ReelFlow.getFlow("F-123456ABCD");

var removeEventListener = targetFlow.player.on('actionButton:click', (action) => {
    console.log('Action clicked:', action);
    // action = {
    //   id: '9d0d9b93-7cff-4e2e-9acb-bc05181f63e8',
    //   label: 'Chat with us',
    //   index: 0
    // }
});