Datazoom SDKs organize collection around contexts. A context defines the scope for data collection, such as the whole app, a player, or a custom workflow. This lets the SDK associate metadata and events precisely.

• Global or app context: Applies to the overall application session.

• Player context: Applies to one media player instance.

• Custom context: Applies to a non-player flow, component, or interaction stream.

Global metadata is inherited by lower-level contexts, and more local metadata overrides broader metadata when the same key is used.

Initialize the SDK

Every SDK has an initialization step. This is the method that activates Datazoom collection for the application.

• What it does: Starts the SDK, applies configuration, and establishes the global session context.

• When to use it: Once, during app or page startup.

• Why it matters: Without initialization, the SDK cannot collect automatic data or accept custom events and metadata reliably.

Use the global context

SDKs expose a default application-level context. This is where you attach metadata or events that apply broadly across the user session.

• Use cases: user identifiers, experiment buckets, subscription tier, page or screen information, device tags

• Behavior: data set at this level is usually included with later events unless a more specific context overrides it

Create a player or custom context

When you need to track a specific player instance or a non-player workflow, most SDKs provide a way to create a local context.

• Player context: ties data to a single media player

• Custom context: ties data to a checkout flow, widget, carousel, or similar scoped experience

Set custom metadata

Set persistent contextual data that should travel with future events by attaching business-specific fields that are not part of the standard dictionaries.

• What it does: stores custom key-value data in the current scope

• Scope options: app-level or context-level

• Persistence: remains in effect for later events until changed or cleared

Examples of metadata include content category, user segment, paywall status, search term, transaction ID, feature flag, or channel.

Get current metadata

SDKs allow your application to read back the metadata currently stored on the global or local context.

• What it does: returns the metadata currently held in that scope

• Why it helps: useful when updating, debugging, or rebuilding state after a session boundary

This is especially useful where metadata updates overwrite the full state rather than merging automatically.

Clear metadata

SDKs provide a way to remove previously stored metadata from the app or player scope.

• What it does: deletes persisted custom metadata from a scope

• When to use it: on logout, player teardown, content changes, or when a value is no longer valid

Generate a custom event

Sends an event that is not automatically captured by Datazoom’s standard dictionaries.

• What it does: emits a custom event name into the stream

• Optional behavior: can include one-time metadata that applies only to that event

• Typical examples: sign_up, purchase, search_submitted, button_click, paywall_dismissed, form_error

Generate a context-specific event

In SDKs that support multiple players or custom contexts, you can usually emit an event from a specific context rather than from the app globally.

• What it does: sends the event with the local context’s identifiers and metadata

• Why it matters: prevents the event from being associated with the wrong player or workflow

This is particularly important in multi-player pages, concurrent experiences, or apps where several flows are active at once.

Destroy or end a context

Custom contexts often have a cleanup method to remove local state when the workflow or component is finished.

• What it does: tears down a local context and releases its associated metadata/state

• When to use it: when a widget is removed, a flow completes, or a temporary context is no longer needed

Listen for SDK callbacks or lifecycle notifications

SDKs expose callbacks that help the host application react to session changes.

• Common purpose: detect session termination, restart, content session boundaries, or other lifecycle changes

• Why it matters: some custom metadata must be re-applied after a session restart or content boundary

Lifecycle notifications help your application keep custom state accurate.