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.

Lura Analytics also connects playback quality with monetization. Ad requests, insertion method, break position, quartile progress, skips, completions, and ad errors are measured alongside content playback when those signals are available. This helps teams evaluate ad delivery and investigate interruptions around each break.

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.
Monetization	Measure ad delivery, quartile progress, skips, completions, and errors alongside the viewer's content experience.
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

Configure Lura Analytics through the Lura Player SDK. Although analytics is implemented as a player plugin, it is enabled through the top-level analytics configuration.

Pass the configuration to the React Native player's setConfig method through its ref, as shown in the React Native Quick Start.

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. 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.userSubscription	string	No	Viewer subscription tier or entitlement level, such as premium.
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.

import React, { useEffect, useRef } from "react";
import { View } from "react-native";
import { LuraPlayer, type Configuration, type UnifiedPlaylist } from "@akta-tech/lura-player-react-native";
import { LuraPlayerControls } from "@akta-tech/lura-player-react-native-ui";

const config: Configuration = {
    lura: {
        appKey: "YOUR_LURA_APP_KEY",
        assetId: "YOUR_ASSET_ID",
    },
    analytics: {
        enabled: true,
        apiKey: "YOUR_ANALYTICS_API_KEY",
        app: {
            id: "com.example.streaming",
            name: "Example Streaming",
            version: "2.4.0",
        },
        session: {
            userId: "viewer-8f0c2a",
            userSubscription: "premium",
            data: "experiment-group-b",
        },
    },
};

export default function App() {
    const playerRef = useRef<UnifiedPlaylist>(null);

    useEffect(() => {
        playerRef.current?.setConfig(config);
    }, []);

    return (
        <View>
            <LuraPlayer
                ref={playerRef}
                Controls={LuraPlayerControls}
                style={{ width: "100%", aspectRatio: 16 / 9 }}
            />
        </View>
    );
}

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.

const config = {
    analytics: {
        enabled: true,
        apiKey: "YOUR_ANALYTICS_API_KEY",
        app: {
            id: "com.example.streaming",
            name: "Example Streaming",
            version: "2.4.0",
        },
        session: {
            userId: "viewer-8f0c2a",
            userSubscription: "premium",
        },
    }
};

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, connection type, estimated bandwidth, and latency.
Errors	Recoverable playback errors, repeated failure conditions, fatal playback failures, ad errors, and the reason a session ended.

Available measurements and diagnostics depend on the player SDK and device. Device and connection information is reported when the platform exposes it.

Diagnostics

Diagnostic stream availability depends on the installed player SDK and platform.

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.

const config = {
    analytics: {
        enabled: true,
        apiKey: "YOUR_ANALYTICS_API_KEY",
        diagnostics: {
            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:

const config = {
    analytics: {
        enabled: true,
        apiKey: "YOUR_ANALYTICS_API_KEY",
        diagnostics: {
            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 playback session ends.

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 data does 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; initializing the player alone does not open an analytics session.
3. Look for a POST request to /v2/ingest on the player-analytics.mp.lura.live host.
4. Check device connectivity, DNS, TLS, and network restrictions that could prevent the request.
5. 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.