Custom Analytics

The Blings SDK enables easy integration of your analytics solution, such as Google Analytics, Mixpanel, or Amplitude, with MP5 video playback.

By adding a small piece of code, you can track various video analytics, including events like "video is ready", button clicks, scene changes, play and pause, and more. All these analytics will be sent directly to your system.

By integrating the Blings SDK, you can easily analyze the behavior of users while they watch the video as part of the entire user journey, all within your existing tool set. This unified approach allows you to gain valuable insights and understand how users interact with the video content, and compare that to the results of this communication.

SDK custom analytics functions

Blings SDK requires three functions to set up analytics:

init - This function is used to set up the tool and pass the analytics token. It is called immediately.

config - This function is used to set parameters such as page and user ID. It is called once the player has received user data.

send - This is the main function that gets called for every playback event.

// custom analytics configuration object
{
	    init: ()=>{},   
	    config: (player)=>{}, 
	    send: (event, properties)=>{}
	}

You can use these functions in accordance with your analytics tool, as shown in this example that uses Mixpanel:

First, add the library script to your page, and then, set the analytics this in this way:

const customAnalytics = {
  init() {
    mixpanel.init("YOUR_MIXPANEL_TOKEN");
  },
  config(player) {
    mixpanel.register({
      userID: "xyz-123",
      userType: "customer",
    });
  },
  send(event, properties) {
    mixpanel.track(event, properties);
  },
};

Passing the analytics configuration to the SDK

To integrate your analytics platform, you have two options:

1. Per Instance Configuration (Recommended): Set the customAnalytics configuration in the analyticsConfig property, inside settings property, when you call BlingsPlayer.create. (This configuration takes precedence over the global configuration)

   BlingsPlayer.create({
     settings: {
       analyticsConfig: {
         customAnalytics: {
           init() {},
           config(player) {},
           send(event, properties) {},
         },
       },
     },
     // ...
     // standard configuration: project, data, scenes, ...
   });

2. Global Configuration: Set BlingsPlayer.config.analytics function, that returns the configuration object, before running the BlingsPlayer.create function. This will set the custom analytics for each player created.

   BlingsPlayer.config.analytics = () => {
   	return {
   	    init: ()=>{},
   	    config: (player)=>{}, 
   	    send: (event, properties)=>{}   
   	}
   })
   
   BlingsPlayer.create({...})

Integration Demo

Feel free to explore the provided demo and check the console for relevant logs to see how the events are being tracked.

Code pen integration demo

Documentation and Types:

configuration object

export interface IBlingsAnalytics {
  initiated?: boolean;
  send(event: AnalyticsEvents, properties?: any): void;
  init(): Promise<void>;
  config(player: Player, identifier?: IIdentifier): void;
}

Events:

// event name
type AnalyticsEvents =
  | "init"
  | "loaded"
  | "scene-change"
  | "ended"
  | "play"
  | "first-play"
  | "pause"
  | "replay"
  | "cta-hover"
  | "cta-click"
  | "sdk-loaded"
  | "loading-video-def"
  | "video-def-loaded"
  | "loading-assets"
  | "ready"
  | "fingerprint"
  | "loaded-from"
  | "spinner-state"
  | InteractiveAnalyticsEvents
  | "wtr"
  | "error"
  | "html-id"
  | "uid";

// category for each event
EVENT_CATEGORIES = {
  PAGE: "PAGE",
  PLAYBACK: "playback",
  PLAY_PAUSE: "play-pause",
  INTERACTION: "interaction",
  LOADING: "loading",
  WATCH_TIME_RANGE: "wtr",
  ERROR: "error",
};

// for playback events, the 'value' sent
PLAYBACK_FLOW = {
  LOADED: 1,
  FIRST_PLAY: 2,
  SCENES: 20, // + scene num, e.g 24. 
  MAIN_CTA: 80,
  ENDED: 99,
  REPLAY: 100,
};

Event Definitions

🔹 init

📌 Triggered When: The analytics system initializes.

🎯 Purpose: Marks the start of analytics tracking.

📊 Example Data:

{

"category": "PAGE"

}

🔹 loaded

📌 Triggered When: The player is fully loaded and ready to play.

🎯 Purpose: Confirms successful loading of all required assets.

📊 Example Data:

{

"category": "PLAYBACK",

"value": "LOADED"

}

🔹 scene-change

📌 Triggered When: The user navigates to a new scene.

🎯 Purpose: Tracks scene transitions.

📊 Example Data:

{

"category": "PLAYBACK",

"value": "SCENE_2",

"label": "IntroScene"

}

🔹 ended

📌 Triggered When: The video reaches its end.

🎯 Purpose: Identifies when a user watches the entire video.

📊 Example Data:

{

"category": "PLAYBACK",

"value": "ENDED"

}

🔹 play

📌 Triggered When: The user presses play.

🎯 Purpose: Tracks playback initiation.

📊 Example Data:

{

"category": "PLAY_PAUSE",

"value": 120

}

🔹 first-play

📌 Triggered When: The video plays for the first time.

🎯 Purpose: Differentiates initial play from other play events.

📊 Example Data:

{

"category": "PLAYBACK",

"label": "USER_INTERACTION_NO_AUTO_PLAY",

"value": "FIRST_PLAY",

"payload": {

"initialScenes": ["IntroScene"],

"firstScene": "IntroScene"

}

}

🔹 pause

📌 Triggered When: The video playback is paused.

🎯 Purpose: Tracks when a user stops playback.

📊 Example Data:

{

"category": "PLAY_PAUSE",

"value": 150

}

🔹 replay

📌 Triggered When: The user replays the video.

🎯 Purpose: Tracks when users restart the video.

📊 Example Data:

{

"category": "PLAYBACK",

"value": "REPLAY"

}

🔹 cta-click

📌 Triggered When: The user clicks a CTA button.

🎯 Purpose: Tracks conversion and user engagement.

📊 Example Data:

{

"category": "PLAYBACK",

"value": "MAIN_CTA"

}

🔹 sdk-loaded

📌 Triggered When: The SDK is fully initialized.

🎯 Purpose: Confirms the SDK is ready.

🔹 loading-assets

📌 Triggered When: Additional assets (images, animations, etc.) are loading.

🎯 Purpose: Tracks the loading process for supporting assets.

🔹 ready

📌 Triggered When: The player is fully ready for interaction.

🎯 Purpose: Indicates all required resources are loaded and functional.

🔹 fingerprint

📌 Triggered When: A unique user identifier is generated.

🎯 Purpose: Ensures consistent user tracking across sessions.

🔹 loaded-from

📌 Triggered When: Identifies the source from which the player was loaded.

🎯 Purpose: Tracks traffic sources (e.g., direct URL, referral).

🔹 spinner-state

📌 Triggered When: The loading spinner appears or disappears.

🎯 Purpose: Tracks buffering states.

🔹 InteractiveAnalyticsEvents

📌 Triggered When: Various interactive analytics events occur.

🎯 Purpose: A generic category for user interactions (clicks, hovers, swipes).

🔹 wtr (Watch Time Range)

📌 Triggered When: The user watches a specific segment of the video.

🎯 Purpose: Tracks how much of the video was watched.

📊 Example Data:

{

"category": "WATCH_TIME_RANGE",

"value": [30, 90],

"label": "IntroScene"

}

🔹 error

📌 Triggered When: An error occurs in the player.

🎯 Purpose: Captures issues related to playback, assets, or analytics failures.

📊 Example Data:

{

"type": "ANALYTICS",

"message": "Init of one or more analytics instances failed"

}

🔹 html-id

📌 Triggered When: The player’s unique HTML element ID is referenced.

🎯 Purpose: Assists in debugging and tracking player instances.

🔹 uid

📌 Triggered When: A unique user identifier is assigned.

🎯 Purpose: Ensures continuity of tracking for a user across sessions.