Datazoom captures session-level event stream data from client applications and creates a rich dataset where rows represent events and columns represent the available metadata dimensions. These dimensions include both prescripted fields from predefined data dictionaries and unlimited custom events and metadata.

To fully understand a user’s journey, data collection strategies need to reflect the complexity of modern digital experiences. Users navigate between pages, interact with distinct UI components, and may consume multiple pieces of media simultaneously through complex components like media players.

Context hierarchy

Datazoom organizes collection around a context hierarchy. The Global Context represents the overall application experience and carries the app_session_id. Within that global session, you can create Custom Contexts for non-player experiences and Player Contexts for individual media players; each Player Context generates its own content_session_id. Ad Break and Ad Contexts then nest beneath the relevant Player Context using ad_break_id and ad_session_id. This structure keeps events, metadata, state, timers, and counters scoped to the correct context while preserving their relationship to the parent app session, giving data teams an accurate view of the complete user journey.

Each user session is assigned a unique identifier that persists until the session is determined to have ended, such as when the app is closed, or has been abandoned after a period of inactivity. Additional session identifiers are assigned within the App Session to mark media playback through the Content Session and advertising playback through the Ad Session. Figure 1 depicts the hierarchical nature of these session identifiers.

By assigning a specific flow or media player to a Datazoom context, the SDK automatically scopes the events, metadata, and state to that context. Here is how the identifiers are used to build a complete picture:

app_session_id (Global Context): When the user opens your app or webpage, Datazoom generates a unique app_session_id upon the datazoom_loaded event. This ID persists throughout the application experience until the session ends based on configured inactivity timeouts, a user-initiated exit, or abandonment.
[context_name] (Custom Context): You can create a non-player context for specific multi-step processes, such as a checkout flow, or specific UI components, such as a scrolling carousel or interactive dashboard.
content_session_id (Player Context): Every time a media player initiates playback, it generates a unique content_session_id nested within the app session.
ad_break_id (Ad Break Context): If a media player launches an ad break, an ad_break_id is created and nested within that specific player’s content_session_id.
ad_session_id (Ad Context): An ad_session_id is created for each ad and nested within that ad’s ad_break_id.

App Session lifecycle

Start of an App Session

The first available event that marks the beginning of an application session and receives the unique app_session_id identifier occurs when the client SDK is loaded into the application. Datazoom has a prescripted event called datazoom_loaded, which provides the timestamp and related metadata for that event. This app_session_id persists throughout the event stream until the end of an App Session is reached.

End of an App Session

Several conditions can signal the end of an App Session and provide a deterministic signal to capture the final event of the App Session. There are also situations where an event cannot be generated to signal the end of a session, such as an app crash or tab closure.

User-initiated session end

It is programmatically possible to capture the graceful exit of an application or webpage. This can be used as a custom event to signal the end of a user’s engagement with the application.

Session end due to inactivity

Datazoom provides a configurable timer to indicate that a user has abandoned the application. The default setting is 20 minutes, after which the app_session_id will no longer be used. If the user returns to the application, a new app_session_id will be assigned. Note that if the user is playing content, is inactive for more than 20 minutes, and then resumes playback, the content_session_id will persist across two unique app_session_id values, with the first event of the new app_session_id being a resume event for the media player.

Session end due to unforeseen circumstances

In certain cases, an application will lose the ability to emit an event due to the nature of software execution, such as an app crash, garbage collection, or tab closure. For these cases, a sequential event counter can be used to identify the very last event in the app_session_id, such as heartbeat, pause, or stop, along with the related counters, averages, and timers for aggregation tables.

Metadata resolution: global vs. local

When managing multiple nested contexts, you will often have metadata that applies to the entire app, such as user_id, browser_name, or device_type, alongside metadata specific to a localized context, such as a title in a player context or custom_cart_value in a checkout context.

Global Metadata: Defined at the application level. It is automatically inheritable by all events triggered across all localized contexts.
Local Metadata (Context-Specific): Defined directly within a localized context, such as a specific media player or checkout flow. This data is strictly scoped to the events generated within that environment.

Note on precedence: If the same metadata key exists at both the global and local levels, Datazoom uses the value from the most specific active context. For example, an app might set a global custom_title value of “Sports,” while a video player context sets custom_title to “Quarterfinal Highlights.”

Solving for multiple concurrent players

A primary benefit of these nested sessions is their ability to seamlessly handle multiple media players on a single screen.

Whether it is a news article with multiple auto-playing video embeds, a sports broadcasting app offering Picture-in-Picture (PiP), or a social media feed with scrolling video carousels, tracking these interactions accurately presents a unique challenge. With nested contexts, if you have three concurrent video players on the screen, Datazoom will generate three distinct content_session_id values nested under one app_session_id.

You can easily distinguish which video caused an error, triggered an ad, or completed playback. User interactions specific to a particular player are also accurately tracked and isolated to that player’s context.

Data validation

Datazoom validates event data payloads through several mechanisms, including deduplication to prevent duplicate messages, decimal point and range enforcement for numerical fields, assurance that all required fields exist, configurations to drop or modify empty fields or unexpected values, and flexibility to add more checks and mitigations.

Customers can request to have mismatched data handled on egress by either filtering the entire message or, more surgically, removing only the specific incorrect values while preserving the rest of the event data.

Best practices

Minimize Global Clutter: Keep your global metadata restricted to truly overarching application state, such as centralized User IDs, cohort IDs, and page titles. Leave flow-specific or video-specific data to localized Custom and Player Contexts.
Destroy Contexts on Unmount: If your application is a Single Page Application (SPA) like React or Angular, or if users continuously scroll past videos, such as in a social feed, be sure to destroy the context when the element is removed from the DOM to prevent memory leaks: primaryPlayerContext.destroy();
Use Fluxdata: Datazoom maintains session timers and counters, such as playback_duration_content_ms and stall_duration_content_ms. Because these are securely scoped to their specific context hierarchy, the final fluxdata calculated at the end of a content_session_id will accurately reflect the performance of that specific player engagement, rather than an aggregate of all elements on the screen.

For specific instructions for your given application platform, media player, ad framework, or custom use cases, please see the respective articles in the Datazoom Collectors documentation.