Skip to content

About

Video Agent for iOS and tvOS

Topics

Resources

Code of conduct

Security policy

Stars

3 stars

Watchers

10 watching

Forks

Latest commit

 

History

880 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Community Project header

New Relic Video Agent for iOS & tvOS

License

The New Relic Video Agent for iOS & tvOS provides comprehensive video analytics for Apple platform applications using AVPlayer or THEOplayer (Dolby OptiView Player). Track video events, monitor playback quality, identify errors, and gain deep insights into user engagement and performance — for both iPhone/iPad and Apple TV.

Features

  • Automatic Event Detection — Captures AVPlayer lifecycle events automatically without manual instrumentation
  • THEOplayer Support — Native tracker for THEOplayer (Dolby OptiView Player) covering lifecycle events, QoE/rendition tracking, and error mapping (iOS only, iOS 13.0+)
  • QoE Metrics — Per-session aggregate covering startup time, rebuffering, bitrate (peak / average / per-sample download rate min / max / mean), adaptive-bitrate behavior (rendition switch counts, distinct renditions seen), pause time, and playback errors. See DATAMODEL.md for the full attribute reference.
  • Event Segregation — Organized event types: VideoAction, VideoAdAction, VideoErrorAction, VideoCustomAction
  • IMA Ads Support — Built-in Google IMA SDK ad tracking via dedicated ad tracker
  • tvOS Support — Auto-detection of Apple TV with optimized harvest cycles
  • Multi-Player Support — Track multiple simultaneous video players in the same application
  • Easy Integration — Swift Package Manager, XCFrameworks, manual source import, or CocoaPods (deprecated)

Table of Contents

Installation

Option 1: Install via Swift Package Manager (Recommended)

In Xcode: File > Add Package Dependencies..., enter the repo URL, and pick the products you need:

https://github.com/newrelic/video-agent-iOS.git

Select NewRelicVideoCore and NRAVPlayerTracker (required for AVPlayer), plus NRIMATracker, NRMediaTailorTracker, or NRTHEOplayerTracker as optional ad/player support.

Or declare it in your own Package.swift:

dependencies: [
    .package(url: "https://github.com/newrelic/video-agent-iOS.git", from: "5.1.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "NewRelicVideoCore", package: "video-agent-iOS"),
            .product(name: "NRAVPlayerTracker", package: "video-agent-iOS"),
            // .product(name: "NRIMATracker", package: "video-agent-iOS"),        // Optional — Google IMA ads
            // .product(name: "NRMediaTailorTracker", package: "video-agent-iOS"), // Optional — AWS MediaTailor SSAI
            // .product(name: "NRTHEOplayerTracker", package: "video-agent-iOS"),  // Optional — THEOplayer (iOS 15.0+)
        ]
    )
]

Note: NRTHEOplayerTracker doesn't bundle THEOplayerSDK-core itself (like NRIMATracker and Google IMA, which also stay separate). You'll still need to add THEOplayerSDK-core to your project separately — e.g. via its own xcframework zip — plus a valid THEOplayer license from Dolby.

Option 2: Install via XCFrameworks

Download the latest pre-built XCFrameworks from the Releases page. Look for XCFrameworks.zip, extract it, and drag the .xcframework files into your Xcode project under Frameworks, Libraries, and Embedded Content, set to "Embed & Sign".

Security: to check that the files you downloaded are the ones we built, see Verifying a release.

Note: NRTHEOplayerTracker.xcframework is included in XCFrameworks.zip (and published on its own as NRTHEOplayerTracker.xcframework.zip), but doesn't bundle THEOplayerSDK-core itself — see the SPM note above for how to add it.

Option 3: Install Manually Using Source Code

  1. Clone this repo.
  2. In Xcode, go to File > Add Files to "YourProject".
  3. Select the module directory and click Add.
  4. Repeat for each module you need.

Option 4: Install via CocoaPods (Legacy)

CocoaPods Trunk is being discontinued by its maintainers — new pod versions can no longer be published after December 2, 2026. Already-pinned versions keep working indefinitely, but new installs and upgrades should use Swift Package Manager above instead.

Add the dependencies to your Podfile:

pod 'NewRelicVideoAgent'
pod 'NRAVPlayerTracker'
pod 'NRIMATracker'         # Optional — only if using Google IMA ads
pod 'NRTHEOplayerTracker'  # Optional — only if using THEOplayer (iOS 13.0+, requires a THEOplayer license)

Then run:

pod install

Note: Replace with the desired release version if pinning.

For more details on all installation methods, see INSTALLATION.md.

Verifying a release (security)

Every release published by our release automation is signed, and ships with a list of file fingerprints. You can check that the files you downloaded are exactly the ones we built, and that they were built by this repository's release automation and not by someone else.

Releases published before this was added have no signatures. The Build section at the bottom of a release's notes tells you whether a release has them.

What we publish and sign

Each release has eight files. All eight are signed.

File What it is
xcframeworks.zip All frameworks in one download
NewRelicVideoCore.xcframework.zip, NRAVPlayerTracker.xcframework.zip, NRIMATracker.xcframework.zip, NRMediaTailorTracker.xcframework.zip, NRTHEOplayerTracker.xcframework.zip One zip per framework (these are what Swift Package Manager downloads)
SHA256SUMS The fingerprint (SHA-256 checksum) of each zip
integrity-manifest.json The version, the commit the files were built from, and the fingerprints in a machine-readable form

Fingerprint. A short code worked out from a file. If even one byte of the file changes, the code changes.

Signature (GitHub calls it an attestation). A tamper-proof stamp, made by GitHub when our release automation (.github/workflows/ios-release.yml) built the files. It says which repository and which automation produced a file with that exact fingerprint. It is recorded in a public log, and nobody can create a valid one for a file we did not build.

How to verify (3 steps)

You need the GitHub CLI version 2.53 or newer (older versions miss some of the options below), logged in once with gh auth login.

# 1. Download the release (replace v5.1.2 with the version you use)
gh release download v5.1.2 -R newrelic/video-agent-iOS -D release-files
cd release-files

# 2. Check the fingerprints: every line must say OK
shasum -a 256 -c SHA256SUMS          # on Linux: sha256sum -c SHA256SUMS

# 3. Check the signatures: every file must pass
for f in *; do
  gh attestation verify "$f" \
    --repo newrelic/video-agent-iOS \
    --signer-workflow newrelic/video-agent-iOS/.github/workflows/ios-release.yml \
    || echo "FAILED: $f"
done
  • A passing file prints Verification succeeded and the command exits with code 0. Any failure exits with a non-zero code, so you can use the check in a script.
  • --signer-workflow is important: it only accepts signatures made by our release automation, not by any other workflow in the repository.
  • To check only the files you use, run step 3 for those files (and for SHA256SUMS).

If any check fails, do not use the files. Report it as described in A note about vulnerabilities.

See what the signature says

gh attestation verify NRIMATracker.xcframework.zip \
  --repo newrelic/video-agent-iOS \
  --signer-workflow newrelic/video-agent-iOS/.github/workflows/ios-release.yml \
  --format json

The result lists the repository, the release automation that made the file, the commit that automation ran from, and the public log entry.

The manifest and the three commits

integrity-manifest.json is signed too, so you can trust what it says:

{
  "version": "5.1.2",
  "commit": "<commit the files were built from>",
  "files": {
    "NRIMATracker.xcframework.zip": {
      "sha256": "<hex fingerprint>",
      "sha384": "sha384-<base64 fingerprint>"
    }
  }
}

A release mentions three commits, and they are not the same on purpose:

Commit Where you see it What it is
Built from commit in integrity-manifest.json, and the release notes The code the files were built from
Release automation In the signature (--format json) The commit of the automation itself, on master, when it ran
Version label (tag) The release's tag, for example v5.1.2 The merged commit. It holds the same code as "built from", plus the updated Package.swift (the new tag and fingerprints)

To check the last claim yourself, you can see that only Package.swift differs between the built commit and the tag:

BUILT=$(jq -r .commit integrity-manifest.json)
git clone https://github.com/newrelic/video-agent-iOS.git && cd video-agent-iOS
git fetch origin "$BUILT"
git diff --name-only "$BUILT" v5.1.2        # should print only: Package.swift

Swift Package Manager users

Swift Package Manager downloads each framework zip and compares its fingerprint with the checksum: in our Package.swift, and refuses a file that does not match. To check by hand that the Package.swift on the tag matches the signed files:

swift package compute-checksum NRIMATracker.xcframework.zip
curl -s https://raw.githubusercontent.com/newrelic/video-agent-iOS/v5.1.2/Package.swift \
  | grep -A2 'name: "NRIMATracker"'      # the checksum: line must match

Verifying without internet access

On a connected machine, download the signature and the trusted keys. Then check on the offline machine:

# connected machine
gh attestation download NRIMATracker.xcframework.zip -R newrelic/video-agent-iOS
gh attestation trusted-root > trusted_root.jsonl

# offline machine (the .jsonl file name starts with sha256:)
gh attestation verify NRIMATracker.xcframework.zip \
  --bundle sha256:<digest>.jsonl \
  --custom-trusted-root trusted_root.jsonl \
  --repo newrelic/video-agent-iOS \
  --signer-workflow newrelic/video-agent-iOS/.github/workflows/ios-release.yml

What a signature does and does not tell you

  • It does: the files are byte-for-byte what our release automation built, in this repository, and they were not swapped or changed afterwards.
  • It does not: say the code is free of bugs or vulnerabilities. It proves where the files came from, not that the code is safe.

Prerequisites

Before using the Video Agent, ensure you have:

  • New Relic Account — Active account with a valid application token
  • AVFoundation — Available by default on iOS 12+ / tvOS 12+
  • Google IMA SDK (optional) — Required only if tracking IMA ads
  • THEOplayer SDK (optional) — Required only if tracking THEOplayer; requires a valid THEOplayer license from Dolby
  • Minimum Deployment Target — iOS 12.0 / tvOS 12.0 or higher (iOS 13.0+ if using NRTHEOplayerTracker, per THEOplayer's own minimum)

Modules

The Video Agent is composed of five modules:

Module Description Required
NewRelicVideoCore Base classes for tracker management, event generation, and data harvesting. Standalone — no New Relic iOS Agent dependency required. Yes
NRAVPlayerTracker Video tracker for AVPlayer. Automatically hooks into player lifecycle events via KVO and notifications. Yes (for AVPlayer)
NRIMATracker Ad tracker for the Google IMA SDK. Captures ad lifecycle events including quartiles, breaks, and errors. Optional
NRTHEOplayerTracker Video tracker for THEOplayer (Dolby OptiView Player). Wires real lifecycle, QoE/rendition, and error events via THEOplayer's own listener API. iOS only, iOS 13.0+. Optional (for THEOplayer)
NRMediaTailorTracker Ad tracker for AWS MediaTailor server-side ad insertion (SSAI). Detects ads inside an AVPlayer HLS stream and emits the standard ad event vocabulary plus AD_ERROR. HLS-only in v1; DASH support is via a customer-supplied adapter. iOS 12 + tvOS 12. See NRMediaTailorTracker/README.md. Optional

Usage

Getting Your Application Token

Before initializing the Video Agent, obtain your application token:

  1. Log in to one.newrelic.com
  2. Navigate to the Streaming Video & Ads onboarding flow
  3. Copy your applicationToken

Basic Setup — AVPlayer Only

Objective-C

// Step 1: Initialize NRVAVideo in AppDelegate
NRVAVideoConfiguration *config = [[[NRVAVideoConfiguration builder]
    withApplicationToken:@"YOUR_NEW_RELIC_TOKEN"]
    withDebugLogging:YES]
    build];
[[[NRVAVideo newBuilder] withConfiguration:config] build];

// Step 2: Register your player in your ViewController
NRVAVideoPlayerConfiguration *playerConfig = [[NRVAVideoPlayerConfiguration alloc]
    initWithPlayerName:@"MainVideoPlayer"
    player:yourAVPlayer
    adEnabled:NO
    customAttributes:@{@"contentTitle": @"My Video Title"}];
NSInteger trackerId = [NRVAVideo addPlayer:playerConfig];

// Step 3 (Optional): Release the tracker when done
- (void)dealloc {
    [NRVAVideo releaseTracker:trackerId];
}

Swift

// Step 1: Initialize NRVAVideo in AppDelegate
let config = NRVAVideoConfiguration.builder()
    .withApplicationToken("YOUR_NEW_RELIC_TOKEN")
    .withDebugLogging(true)
    .build()
NRVAVideo.newBuilder().with(configuration: config).build()

// Step 2: Register your player in your ViewController
let playerConfig = NRVAVideoPlayerConfiguration(
    playerName: "MainVideoPlayer",
    player: yourAVPlayer,
    adEnabled: false,
    customAttributes: ["contentTitle": "My Video Title"]
)
let trackerId = NRVAVideo.addPlayer(playerConfig)

// Step 3 (Optional): Release the tracker when done
deinit {
    NRVAVideo.releaseTracker(trackerId)
}

Setup with AVPlayer and IMA Ads

Objective-C

// Step 1: Initialize NRVAVideo (same as above)

// Step 2: Register the player with ads enabled
NRVAVideoPlayerConfiguration *playerConfig = [[NRVAVideoPlayerConfiguration alloc]
    initWithPlayerName:@"MainVideoPlayer"
    player:yourAVPlayer
    adEnabled:YES
    customAttributes:nil];
NSInteger trackerId = [NRVAVideo addPlayer:playerConfig];

// Step 3: Wire up the IMA ad tracker
NRIMATracker *adTracker = (NRIMATracker *)[NRVAVideo adTrackerForId:trackerId];
// Pass adTracker to your IMA ads loader setup

Swift

// Step 1: Initialize NRVAVideo (same as above)

// Step 2: Register the player with ads enabled
let playerConfig = NRVAVideoPlayerConfiguration(
    playerName: "MainVideoPlayer",
    player: yourAVPlayer,
    adEnabled: true,
    customAttributes: nil
)
let trackerId = NRVAVideo.addPlayer(playerConfig)

// Step 3: Wire up the IMA ad tracker
let adTracker = NRVAVideo.adTracker(forId: trackerId) as? NRIMATracker
// Pass adTracker to your IMA ads loader setup

Setup with NRAdConfig (Recommended)

adEnabled above is a legacy boolean shortcut. The current API is NRAdConfig — the single place to select and configure the ad tracker for a player session: client-side ads (Google IMA/CSAI) or AWS MediaTailor server-side ad insertion.

Objective-C

// Client-side ads (Google IMA) — equivalent to the legacy adEnabled:YES
NRVAVideoPlayerConfiguration *playerConfig = [[NRVAVideoPlayerConfiguration alloc]
    initWithPlayerName:@"MainVideoPlayer"
    player:yourAVPlayer
    adConfig:[NRAdConfig csai]
    customAttributes:nil];

// AWS MediaTailor server-side ad insertion (requires NRMediaTailorTracker)
NRVAVideoPlayerConfiguration *playerConfig = [[NRVAVideoPlayerConfiguration alloc]
    initWithPlayerName:@"MainVideoPlayer"
    player:yourAVPlayer
    adConfig:[NRAdConfig mediaTailor]
    customAttributes:nil];

// No ads / disable ad tracking — equivalent to the legacy adEnabled:NO
NRVAVideoPlayerConfiguration *playerConfig = [[NRVAVideoPlayerConfiguration alloc]
    initWithPlayerName:@"MainVideoPlayer"
    player:yourAVPlayer
    adConfig:nil
    customAttributes:nil];

Swift

// Client-side ads (Google IMA) — equivalent to the legacy adEnabled: true
let playerConfig = NRVAVideoPlayerConfiguration(
    playerName: "MainVideoPlayer",
    player: yourAVPlayer,
    adConfig: NRAdConfig.csai(),
    customAttributes: nil
)

// AWS MediaTailor server-side ad insertion (requires NRMediaTailorTracker)
let playerConfig = NRVAVideoPlayerConfiguration(
    playerName: "MainVideoPlayer",
    player: yourAVPlayer,
    adConfig: NRAdConfig.mediaTailor(),
    customAttributes: nil
)

// No ads / disable ad tracking — equivalent to the legacy adEnabled: false
let playerConfig = NRVAVideoPlayerConfiguration(
    playerName: "MainVideoPlayer",
    player: yourAVPlayer,
    adConfig: nil,
    customAttributes: nil
)

For MediaTailor-specific options (custom-CDN ad-segment prefixes, tracking-URL overrides), see NRMediaTailorTracker/README.md.

Basic Setup — THEOplayer

Swift

// Step 1: Initialize NRVAVideo (same as the AVPlayer example above)

// Step 2: Register your THEOplayer instance. No `playerType` is needed for a real
// THEOplayer instance — addPlayer identifies it by class automatically. (For a
// custom/wrapped player object that class detection can't see through, set
// playerConfig.playerType explicitly — otherwise addPlayer creates no tracker at all.)
let playerConfig = NRVAVideoPlayerConfiguration(playerName: "MainVideoPlayer", player: theoplayer)
let trackerId = NRVAVideo.addPlayer(playerConfig)

// Step 3: Release the tracker when done
deinit {
    NRVAVideo.releaseTracker(trackerId)
}

Note: THEOplayer support requires NRTHEOplayerTracker (iOS 13.0+, via Swift Package Manager or NRTHEOplayerTracker.xcframework — see Option 1 for what that does and doesn't bundle) and a valid THEOplayer license from Dolby. See the SimpleTheoplayerTest sample app for a complete working integration.

For comprehensive setup instructions and additional examples, see the Developer Onboarding Guide.

Best Practices

1. Setting contentTitle

For best results, explicitly set the content title during player configuration:

let playerConfig = NRVAVideoPlayerConfiguration(
    playerName: "MainVideoPlayer",
    player: yourAVPlayer,
    adEnabled: false,
    customAttributes: ["contentTitle": "My Video Title"]
)

2. Setting userId

Set a user identifier to track video analytics per user:

// Set userId globally across all trackers
NRVAVideo.setUserId("user-12345")

3. Adding Custom Attributes

Add custom attributes to improve data aggregation and analysis:

let customAttrs: [String: Any] = [
    "contentTitle": videoMetadata.title,
    "subscriptionTier": "premium",
    "contentProvider": "studio-abc",
    "region": "us-west-2",
    "cdnProvider": "cloudflare"
]

let playerConfig = NRVAVideoPlayerConfiguration(
    playerName: "MainVideoPlayer",
    player: yourAVPlayer,
    adEnabled: false,
    customAttributes: customAttrs
)

You can also set attributes after initialization:

// String
NRVAVideo.setAttribute("contentSeries", value: "Season 1", trackerId: trackerId)

// Number / Bool
NRVAVideo.setAttribute("contentResolution", value: 1080, trackerId: trackerId)
NRVAVideo.setAttribute("isDVR", value: true, trackerId: trackerId)

// Date — automatically converted to epoch seconds
NRVAVideo.setAttribute("sessionStart", value: Date(), trackerId: trackerId)

// Set global attribute across all trackers
NRVAVideo.setGlobalAttribute("appVersion", value: "2.1.0")

Use these attributes in New Relic queries:

-- Analyze by subscription tier
SELECT count(*) FROM VideoAction WHERE actionName = 'CONTENT_START'
FACET subscriptionTier SINCE 1 day ago

-- Monitor by region
SELECT average(contentPlayhead) FROM VideoAction
FACET region SINCE 1 hour ago

4. Gradual Rollout with Feature Flags

When deploying to production, use feature flags to enable the tracker gradually:

let rolloutPercentage = 5 // Start with 5% of users

let shouldEnable = (userId.hashValue % 100) < rolloutPercentage

if shouldEnable {
    let config = NRVAVideoConfiguration.builder()
        .withApplicationToken("YOUR_NEW_RELIC_TOKEN")
        .withHarvestCycle(300) // 5 minutes
        .build()
    NRVAVideo.newBuilder().with(configuration: config).build()
}

Recommended Rollout Schedule:

Phase Percentage Duration Validation
Initial 5% 2–3 days Verify data flowing to New Relic
Early 15% 3–5 days Check data quality and performance
Expansion 25% 5–7 days Validate across device types
Majority 50% 1–2 weeks Monitor at scale
Full 100% Ongoing Complete deployment

Configuration Options

NRVAVideoConfiguration

Builder Method Type Default Description
withApplicationToken(_:) String — Required. Your New Relic application token.
withHarvestCycle(_:) Int 300 (Mobile) / 180 (TV) Interval in seconds between data harvests.
withDebugLogging(_:) Bool false Enable debug logging for development. Also turns on the event buffer logs described in Buffer logging.
withDebugLogging(_:level:) Bool, NRVALoggingLevel false, .info Same as above, with a minimum level for the buffer logs: .info, .warning or .error. withDebugLogging(true) is equivalent to .info.
withQoeAggregateEnabled(_:) Bool true QoE aggregation is enabled out of the box. Disable with withQoeAggregateEnabled(NO).
withQoeAggregateIntervalMultiplier(_:) Int 2 Multiplier applied to the harvest interval for QoE aggregation. Configure with withQoeAggregateIntervalMultiplier:.

Buffer logging

The agent keeps events in an in-memory buffer until they are harvested. With debug logging enabled it reports on that buffer, and on the smaller dead letter (retry) buffer, through os_log (subsystem com.newrelic.videoagent), including in release builds:

Level When Example
INFO Buffer reaches 85% (once per crossing) ondemand event buffer 85% full (298 of 350 events)
WARNING Buffer reaches 90% and an emergency harvest is requested (once per crossing) ondemand event buffer 90% full (315 of 350 events), requesting an emergency harvest
ERROR The buffer is full and the oldest event is dropped (every drop) ondemand event buffer full (capacity 350), oldest event dropped. Total dropped this session: 1

The dead letter buffer logs the same way, with messages labelled Dead letter (retry) buffer and its own dropped count. Dropped counts are cumulative for the session. Logging does not change buffer sizes, harvest timing or which events are dropped.

let config = NRVAVideoConfiguration.builder()
    .withApplicationToken("YOUR_TOKEN")
    .withDebugLogging(true, level: .warning)   // WARNING and ERROR only
    .build()

NRVAVideoPlayerConfiguration

Parameter Type Description
playerName String Unique identifier for the video player.
player AVPlayer or THEOplayer The player instance to track. A real AVPlayer/THEOplayer instance is identified by class automatically.
adConfig NRAdConfig? Recommended. Selects and configures the ad tracker: NRAdConfig.csai() for Google IMA, NRAdConfig.mediaTailor() for AWS MediaTailor, or nil to disable ad tracking.
adEnabled Bool Legacy shortcut for adConfig. true → NRAdConfig.csai(); false → nil.
customAttributes [String: Any]? Custom attributes to attach to all events from this player.
playerType NRPlayerType Optional override (.avPlayer / .theOplayer / .unspecified) — only needed for a custom/wrapped player object that automatic class detection can't see through. Left unset for such an object, addPlayer creates no tracker at all rather than guessing.

Custom Attribute Limits

Limits for custom attributes added to default mobile events:

  • Attributes: 128 maximum
  • String attributes: 4 KB maximum length (empty string values are not accepted)

Accepted Attribute Value Types

Type Behaviour Example
NSString / String Stored as-is "premium"
NSNumber / Int, Double, Bool Stored as-is @(1080), true
NSDate / Date Converted to epoch seconds (NSNumber) NSDate.now
NSArray / Array Stored recursively; invalid elements are dropped @[@"hls", @(4)]
NSDictionary / [String: Any] Stored recursively; entries with non-string keys or invalid values are dropped @{@"cdn": @"cloudflare"}
NSNull Stored as JSON null [NSNull null]
Anything else (NSURL, NSData, custom objects…) Dropped with an error log; key is not stored —

Note: There are special keywords reserved for default attributes documented in DATAMODEL.md. Do not use these as custom attribute names, as they will be dropped by the agent.

Live Stream Configuration

The agent uses a separate harvest interval for VOD and LIVE content:

Content Type Default Interval Range Builder Method
VOD 300s (Mobile) / 180s (TV) 5–300s .withHarvestCycle(seconds)
LIVE 30s (Mobile) / 10s (TV) 1–60s .withLiveHarvestCycle(seconds)
// Live stream — flush every 10 seconds on TV, 30s on Mobile (or override)
let tracker = NewRelicVideoAgent.build(
    withHarvestCycle: 300,
    withLiveHarvestCycle: 10
)

Note: Harvest intervals are immutable after .build().

API Reference

NRVAVideo (Primary API)

NRVAVideo.addPlayer(_:)

Register a player with the Video Agent. Returns a trackerId for future reference.

let trackerId = NRVAVideo.addPlayer(playerConfig)

NRVAVideo.releaseTracker(_:)

Release a tracker when the player is destroyed.

NRVAVideo.releaseTracker(trackerId)

NRVAVideo.setUserId(_:)

Set a unique identifier for the current user across all trackers.

NRVAVideo.setUserId("user-12345")

NRVAVideo.setAttribute(_:value:trackerId:)

Set a custom attribute on a specific content tracker.

NRVAVideo.setAttribute("contentSeries", value: "Season 1", trackerId: trackerId)

NRVAVideo.setGlobalAttribute(_:value:)

Set a custom attribute across all active trackers.

NRVAVideo.setGlobalAttribute("appVersion", value: "2.1.0")

NRVAVideo.recordCustomEvent(_:)

Record a custom event across all trackers.

NRVAVideo.recordCustomEvent([
    "actionName": "VideoBookmarked",
    "bookmarkPosition": player.currentTime().seconds
])

Data Model

The Video Agent captures comprehensive video analytics across four event types:

  • VideoAction — Playback lifecycle events (request, start, pause, resume, buffer, seek, rendition changes, heartbeats)
  • VideoAdAction — Ad lifecycle events (request, start, end, quartiles, breaks, clicks)
  • VideoErrorAction — Error events (playback failures, ad errors, crashes)
  • VideoCustomAction — Custom events defined by your application

Full Documentation: See DATAMODEL.md for the complete event and attribute reference, and Advanced Topics for creating custom trackers.

Obfuscation Rules

Obfuscation rules let you mask sensitive data before it is transmitted to New Relic.

Each rule is a regex pattern paired with a replacement string. Rules are applied in order to every string attribute value in every outgoing event — including QoE events and crash-recovered events.

Configuration

Objective-C

NRVAVideoConfiguration *config = [[[[NRVAVideoConfiguration builder]
    withApplicationToken:@"YOUR_NEW_RELIC_TOKEN"]
    withObfuscationRules:@[
        @{ @"regex": @"account-\\d+",  @"replacement": @"ACCOUNT_ID" },
        @{ @"regex": @"token=[^&\"]+", @"replacement": @"token=REDACTED" },
    ]]
    build];
[[[NRVAVideo newBuilder] withConfiguration:config] build];

Swift

let config = NRVAVideoConfiguration.builder()
    .withApplicationToken("YOUR_NEW_RELIC_TOKEN")
    .withObfuscationRules([
        ["regex": "account-\\d+",  "replacement": "ACCOUNT_ID"],
        ["regex": "token=[^&\"]+", "replacement": "token=REDACTED"],
    ])
    .build()
NRVAVideo.newBuilder().with(configuration: config).build()

How it works

  • Rules are applied per string attribute value, not on the raw JSON payload — numeric and boolean attributes are unaffected.
  • All rules run against every outgoing event (regular, live, QoE, and crash-recovered).
  • Rules are evaluated in the order they are declared. If two rules can match the same value, order matters.
  • The applicationToken and HTTP auth headers are never touched — obfuscation only runs on event attribute values.

Edge cases

Scenario Behavior
No rules configured No-op; zero performance overhead
Empty replacement string Matched content is deleted (this is intentional and allowed)
Invalid regex pattern withObfuscationRules: throws NSInvalidArgumentException at configuration time — fail fast before any events are sent
Non-string attribute value (number, bool) Skipped; only string values are processed
Malformed rules array entry (not a dictionary) Entry is skipped with a warning log
applicationToken / auth headers Never included in event attributes; not affected
Rule ordering Rules apply in array order — document this to your team if order matters
Catastrophic backtracking NSRegularExpression has no built-in timeout on iOS. Avoid patterns with unbounded quantifier nesting (e.g. (a+)+). Test rules against worst-case inputs before deploying.

Documentation

To generate source code documentation using appledoc:

appledoc --project-name NewRelicVideoAgent --project-company "New Relic Inc." --company-id com.newrelic --create-html --no-create-docset --output ./docs NewRelicVideoCore/NewRelicVideoCore/**/*.h

Then open docs/html/index.html in your preferred browser. The source code annotations are also compatible with Doxygen.

Examples

The Examples folder contains all usage examples. The Test folder contains the test apps.

Support

Should you need assistance with New Relic products, you are in good hands with several support channels.

If the issue has been confirmed as a bug or is a feature request, please file a GitHub issue.

Support Channels

Contributing

We encourage your contributions to improve the New Relic Video Agent for iOS & tvOS! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.

If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at [email protected].

For more details on how best to contribute, see CONTRIBUTING.md.

A note about vulnerabilities

As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through our bug bounty program.

To all contributors, we thank you! Without your contribution, this project would not be what it is today.

License

The New Relic Video Agent for iOS & tvOS is licensed under the Apache 2.0 License.

About

Video Agent for iOS and tvOS

Topics

Resources

Code of conduct

Security policy

Stars

3 stars

Watchers

10 watching

Forks

Releases

Packages

Used by

Contributors

Languages