ReelFlow Player API Reference

Core Concepts

The ReelFlow Player can be configured to display on a page as one of two "types":

• Overlay - hovering in the corner of the screen over existing content
• Inline - inline, embedded in the flow of the page content

The ReelFlow embedded Player consists of two components:

• Eye-catcher: A compact floating video preview on a loop (Overlay only)
• Player: The main video player with full controls and action buttons

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

The Flow ID can be find in the Flow Builder in the Dashboard, and looks 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 necessarily 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
    // }
});