Lura Analytics

The Lura Analytics Plugin turns player activity into streaming intelligence without requiring applications to build and maintain their own event-tracking layer. Once enabled, the plugin observes playback, quality, content, advertising, device, and error signals and sends them to Lura Analytics as a single session.

This session-level view helps streaming businesses understand both audience experience and platform performance. Teams can use the collected data to find startup and buffering friction, compare delivery quality across devices and CDNs, understand how viewers interact with content and tracks, measure ad execution, and investigate playback failures with the context that led up to them.

Because the plugin is maintained as part of Lura Player, event names and measurements remain consistent as the player evolves. Integration requires only an API key, while optional application and session metadata let each playback be analyzed using the business dimensions that matter to your organization.

Value provided by Lura Analytics

Area	Value
Viewer experience	Understand startup, buffering, seeking, playback state, bitrate, frame rate, volume, and track-selection behavior across complete sessions.
Streaming operations	Compare performance by content, CDN, device category, manufacturer, model, operating system, and connection conditions.
Audience segmentation	Add viewer and subscription context to compare experience across customer groups without changing the event integration.
Incident investigation	Use playback errors and optional bounded diagnostics to understand the player and network activity leading up to a failure.
Integration efficiency	Avoid maintaining manual listeners and vendor-specific event mapping; the plugin tracks player events automatically.

Configuration

Lura Analytics is included with Lura Player and does not require a separate library import. Although analytics is implemented as a player plugin, it is enabled through the top-level analytics configuration.

The plugin starts only when enabled is true and apiKey is a non-empty string. Configure it before playback begins because application and session metadata are captured when the analytics session opens.

Attribute	Type	Required	Description
enabled	boolean	Yes	Enables the plugin. Defaults to false when omitted.
apiKey	string	Yes	Provisioned analytics API key used to authenticate delivery. Do not write this value to application logs.
period	number	No	Initial delivery period in seconds. Defaults to 10; values below 1 are treated as 1. The analytics service can adjust this period after the session opens.
app	object	No	Metadata that identifies the application.
app.id	string	No	Application identifier, such as a package name or bundle ID.
app.name	string	No	User-facing application name.
app.version	string	No	Application version.
session	object	No	Viewer and application-specific session metadata.
session.userId	string	No	Viewer identifier supplied by the application. Prefer a stable, non-sensitive identifier.
session.data	string	No	Opaque application-defined session data. Do not include secrets or unnecessary personal data.
diagnostics	object	No	Controls additional player log and network diagnostics. Disabled by default.
diagnostics.enabled	boolean	No	Enables diagnostic delivery. Defaults to false.
diagnostics.logs	boolean	No	Includes Lura Player log entries. Defaults to true when diagnostics are enabled.
diagnostics.network	boolean	No	Includes manifest, media-segment, and DRM request timing. Defaults to true when diagnostics are enabled.

let config = LuraPlayerConfiguration(
    analytics: .init(
        enabled: true,
        apiKey: "YOUR_ANALYTICS_API_KEY",
        app: .init(
            id: "com.example.streaming",
            name: "Example Streaming",
            version: "2.4.0"
        ),
        session: .init(
            data: "experiment-group-b",
            userId: "viewer-8f0c2a"
        ),
        diagnostics: .init(
            enabled: true
        )
    )
)

player?.setConfig(config)

Ask your Lura representative for the analytics API key assigned to your account. For the shared player configuration schema, see the Configuration API reference.

Application and session metadata

The app block identifies the client application. The session block adds the viewer or business context used to segment playback sessions. These values are optional and remain fixed for the life of the analytics session.

session.data accepts a string rather than an object. If structured data is required, encode it in the application before assigning it and keep the resulting value small.

analytics: .init(
    enabled: true,
    apiKey: "YOUR_ANALYTICS_API_KEY",
    app: .init(
        id: "com.example.streaming",
        name: "Example Streaming",
        version: "2.4.0"
    ),
    session: .init(
        data: "experiment-group-b",
        userId: "viewer-8f0c2a"
    )
)

Data collected automatically

The plugin creates one analytics session per playback and reports the following information when it is available:

Category	Measurements and context
Playback lifecycle	Play attempts, playing, pausing, buffering, seeking, completion, application foreground/background changes, and session end reason.
Quality of experience	Playhead, forward buffer, current bitrate, average bitrate, peak bitrate, frame rate, volume, video dimensions, and variant changes.
Content	Asset ID, content type, title, duration, CDN, selected audio language, and subtitle or caption selection.
Advertising	Ad requests, break IDs, client-side or server-side insertion, pre-roll/mid-roll/post-roll position, ad starts, quartiles, skips, completions, and errors.
Environment	Player version, device category, manufacturer, model, operating system, and connection type.
Errors	Recoverable playback errors, repeated failure conditions, fatal playback failures, ad errors, and the reason a session ended.

Environment detection is best effort. Values the platform cannot detect are left empty instead of preventing analytics delivery.

The analytics library creates a random device identifier and stores it locally on the device.

Diagnostics

Diagnostics attach player logs and network request timing to analytics payloads, helping support and operations teams correlate a degraded session with the player and delivery activity around it. Diagnostics are disabled by default.

analytics: .init(
    enabled: true,
    apiKey: "YOUR_ANALYTICS_API_KEY",
    diagnostics: .init(
        enabled: true
    )
)

Both diagnostic streams are included when diagnostics are enabled unless one is explicitly disabled. The following example sends network timing without regular player logs:

analytics: .init(
    enabled: true,
    apiKey: "YOUR_ANALYTICS_API_KEY",
    diagnostics: .init(
        enabled: true,
        logs: false,
        network: true
    )
)

Diagnostic streams are bounded so they cannot grow without limit. Network entries can contain manifest, segment, or license URLs, and logs can contain playback context. Review these values for tokens or personal data before enabling diagnostics in production.

Fatal-error context

When regular diagnostics are disabled, the player retains a small, bounded tail of recent player logs and network requests. This tail is transmitted only with a fatal playback error to provide failure context.

Delivery and resilience

The first playback event opens the analytics session. Events are then batched and sent periodically. Important errors are sent immediately, and the final batch marks the session as ended when playback completes or the viewer leaves the page.

Analytics delivery does not block playback. The client retries temporary network and service failures with backoff, keeps the event buffer bounded, and reopens an expired server session automatically. A rejected API key is not retried indefinitely.

Troubleshooting

If analytics requests do not appear:

1. Confirm that analytics.enabled is true and analytics.apiKey is a non-empty string.
2. Start playback or wait for the player to load a source; creating the LuraPlayer object alone does not open an analytics session.
3. Look for a POST request to /v2/ingest on the player-analytics.mp.lura.live host in your network inspection tool or proxy.
4. Check the response status. A 401 or 403 generally indicates an invalid or unauthorized API key.

Do not print the API key while debugging. If requests reach the service but are rejected, provide the response status and player version to Lura support.