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.
- 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)
- Installation
- Verifying a release (security)
- Prerequisites
- Modules
- Usage
- Best Practices
- Configuration Options
- API Reference
- Data Model
- Support
- Contributing
- License
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:
NRTHEOplayerTrackerdoesn't bundle THEOplayerSDK-core itself (likeNRIMATrackerand 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.
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.xcframeworkis included inXCFrameworks.zip(and published on its own asNRTHEOplayerTracker.xcframework.zip), but doesn't bundle THEOplayerSDK-core itself — see the SPM note above for how to add it.
- Clone this repo.
- In Xcode, go to File > Add Files to "YourProject".
- Select the module directory and click Add.
- Repeat for each module you need.
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 installNote: Replace with the desired release version if pinning.
For more details on all installation methods, see INSTALLATION.md.
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.
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.
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 succeededand the command exits with code0. Any failure exits with a non-zero code, so you can use the check in a script. --signer-workflowis 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.
gh attestation verify NRIMATracker.xcframework.zip \
--repo newrelic/video-agent-iOS \
--signer-workflow newrelic/video-agent-iOS/.github/workflows/ios-release.yml \
--format jsonThe result lists the repository, the release automation that made the file, the commit that automation ran from, and the public log entry.
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.swiftSwift 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 matchOn 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- 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.
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)
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 |
Before initializing the Video Agent, obtain your application token:
- Log in to one.newrelic.com
- Navigate to the Streaming Video & Ads onboarding flow
- Copy your
applicationToken
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)
}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 setupSwift
// 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 setupadEnabled 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.
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 orNRTHEOplayerTracker.xcframework— see Option 1 for what that does and doesn't bundle) and a valid THEOplayer license from Dolby. See theSimpleTheoplayerTestsample app for a complete working integration.
For comprehensive setup instructions and additional examples, see the Developer Onboarding Guide.
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"]
)Set a user identifier to track video analytics per user:
// Set userId globally across all trackers
NRVAVideo.setUserId("user-12345")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 agoWhen 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 |
| 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:. |
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()| 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. |
Limits for custom attributes added to default mobile events:
- Attributes: 128 maximum
- String attributes: 4 KB maximum length (empty string values are not accepted)
| 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.
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().
Register a player with the Video Agent. Returns a trackerId for future reference.
let trackerId = NRVAVideo.addPlayer(playerConfig)Release a tracker when the player is destroyed.
NRVAVideo.releaseTracker(trackerId)Set a unique identifier for the current user across all trackers.
NRVAVideo.setUserId("user-12345")Set a custom attribute on a specific content tracker.
NRVAVideo.setAttribute("contentSeries", value: "Season 1", trackerId: trackerId)Set a custom attribute across all active trackers.
NRVAVideo.setGlobalAttribute("appVersion", value: "2.1.0")Record a custom event across all trackers.
NRVAVideo.recordCustomEvent([
"actionName": "VideoBookmarked",
"bookmarkPosition": player.currentTime().seconds
])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 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.
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()- 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
applicationTokenand HTTP auth headers are never touched — obfuscation only runs on event attribute values.
| 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. |
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/**/*.hThen open docs/html/index.html in your preferred browser. The source code annotations are also compatible with Doxygen.
The Examples folder contains all usage examples. The Test folder contains the test apps.
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.
- New Relic Documentation: Comprehensive guidance for using our platform
- New Relic Community: The best place to engage in troubleshooting questions
- New Relic University: A range of online training for New Relic users of every level
- New Relic Technical Support: 24/7/365 ticketed support. Read more about our Technical Support Offerings
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.
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.
The New Relic Video Agent for iOS & tvOS is licensed under the Apache 2.0 License.
