# 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.

```jsx
// 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](https://developer.mixpanel.com/docs/javascript#eu-data-residency) to your page, and then, set the analytics this in this way:

```jsx
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)

   ```jsx
   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.

   ```tsx
   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](https://codepen.io/yonsch/embed/preview/xxrRVpL?default-tab=js,result\&editable=true)

### Documentation and Types:

configuration object

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

Events:

```tsx
// 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.blings.io/developers/getting-started/advanced-topics/custom-analytics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.