feat(NRMediaTailorTracker): new iOS / tvOS module for AWS MediaTailor SSAI

[avinash-newrelic]

Summary

Adds NRMediaTailorTracker — a new iOS / tvOS SDK module that emits New Relic ad telemetry for AWS MediaTailor server-side-stitched ads playing through AVPlayer. Mirrors the role and event surface of NRTrackerIMA: attach to the player, hear about ads, emit events. Passive observer — no UI, no ad decisioning, no beacon firing.

Before: customers playing MediaTailor streams got CONTENT_* events from NRAVPlayerTracker and zero ad-side telemetry. Ads played; New Relic was blind to them.

After: customers get the full ad event vocabulary (AD_BREAK_START, AD_REQUEST, AD_START, AD_QUARTILE×3, AD_END, AD_BREAK_END, AD_ERROR, plus AD_PAUSE / AD_RESUME / AD_SKIP) with full metadata: availId, creativeId, adSystem, vastAdId, adTitle, creativeSequence, skipOffset, adProgramDateTime, availProgramDateTime, noFill, podCountMismatch, isBumper.

What's in the module

The module owns six subsystems and 17 source files, all behind a single public class (NRTrackerMediaTailor) re-exported through the umbrella header.

Subsystem	Role
Detection (MTDetector)	URL heuristics — recognize MediaTailor URLs, extract session ID, derive tracking URL via URL-rewrite fallback
Parser (MTManifestParser protocol + MTHlsParser + MTDashParser)	Walk the personalized manifest, produce ad-break geometry + recover the tracking URL from the manifest's marker
Model (8 classes)	Decoded tracking-JSON model + runtime break / pod state with firing flags
Tracking client (MTTrackingClient)	GET /v1/tracking/<sessionId> with proper NextToken round-trip pagination, 5 s timeout, one retry on transient network errors, cancellable
Scheduler (MTAdScheduleMerger)	4-pass avail matcher reconciling manifest geometry with tracking metadata; manifest-geometry-wins rule; compound de-dup key
State machine (MTPlayheadStateMachine)	250 ms playhead poll loop driving delegate callbacks at every meaningful transition; fired-flag dedup

The customer app's integration is four method calls: parse manifest → fetch tracking JSON → merge → install schedule. Everything else (HTTP lifecycle, pagination, retry, dedup, state transitions, attribute enrichment, KVO pause/resume) is module-internal.

Format support

• HLS via MTHlsParser — default for AVPlayer consumers
• DASH via MTDashParser — for customers using third-party players (THEOplayer, Bitmovin, Shaka) with their own DASH playback
• Custom parsers can be injected via the MTManifestParser protocol for non-standard CDN layouts

Parity with the Android reference + 15 documented fixes

Module is in parity with video-agent-android/NRMediaTailorTracker, with all 15 bugs from NRMediaTailorTracker_BUGS_TO_FIX.md fixed:

Group A (atomic-fact violations in Android, fixed in iOS):

• A1: Drop ?t=<wallclock> cache-buster — replaced with proper NextToken pagination
• A2: Empty avails → no-fill (AD_BREAK_START → AD_ERROR(NO_FILL) → AD_BREAK_END, no AD_START)
• A3: Pod-count mismatch keeps manifest geometry, enriches each pod with closest tracking ad
• A4: Compound de-dup key (availId, availProgramDateTime ?? startTimeMs) for live HLS sliding-window stability
• A5: Configurable playhead poll interval
• A6: Oversize pods clamped to break boundary (with telemetry counter)
• A7: DASH multi-period detection requires every representation to match an ad marker
• A8: Missing startTimeInSeconds logs warning + queues MISSING_AVAIL_START, then falls back

Group B (additional bugs surfaced by cross-referencing AWS atomic facts):

• B1: NextToken round-tripped (entire pagination contract Android ignored)
• B2: creativeId is primary identity; (availId, adId) composite fallback
• B3: GET retained for Android parity (atomic fact says POST — divergence documented in MTTrackingClient.h)
• B4: Tracking URL recovered from manifest marker (primary); URL-rewrite as fallback
• B5: trackingEvents[*].startTimeInSeconds documented as relativeToAdStartMs to prevent semantic confusion
• B6: New AD_ERROR event vocabulary with 7-value MTAdErrorCode
• B7: availProgramDateTime / adProgramDateTime always emitted (empty when nil) for reliable live correlation

Anti-pattern guardrails

10 explicit non-goals documented in CONTRIBUTING.md and at the top of NRTrackerMediaTailor.m:

1. No VAST beacon firing
2. No VAST wrapper resolution
3. No ad personalization / targeting
4. No cross-session ad caching
5. No manifest query parameter modification
6. No avail suppression (BEHIND_LIVE_EDGE etc.)
7. No ad UI rendering / player pausing / app-business-logic callbacks
8. No assumption every avail has ads
9. No pre-firing impression beacons before playback confirmation
10. No OMID / viewability handoff

Platform support

• iOS 12.0+
• tvOS 12.0+
• Objective-C, matching every sibling tracker in the repo

Verification

• 132 unit tests passing, 0 failures
• 89.92% line coverage on NRMediaTailorTracker.framework
• Both iOS and tvOS schemes build cleanly
• Smoke-test integration wired into Examples/iOS/SimplePlayerWithAds (the ad-tracking example), alongside the existing IMA path

Release-pipeline integration

The new module is wired into the same release machinery as NRAVPlayerTracker and NRIMATracker:

• build-xcframeworks.sh now produces NRMediaTailorTracker.xcframework alongside the existing three modules' xcframeworks for inclusion in the GitHub Release xcframeworks.zip
• .github/workflows/ios-publish.yml validates and publishes NRMediaTailorTracker.podspec to CocoaPods trunk
• .github/workflows/ios-release.yml version-bumps NRMediaTailorTracker.podspec and the hardcoded @"<version>" in -[NRTrackerMediaTailor getTrackerVersion]

A pre-existing telemetry bug was surfaced and fixed while wiring ios-release.yml: the base NRVideoTracker.getTrackerVersion returns NSNull, so without a per-module override the new module's events would report trackerVersion = NSNull in NRDB. Added the override in commit 1909b13.

Test plan

• Run xcodebuild test against NRMediaTailorTrackerTests on iPhone 16 simulator (expect 132/132 passing)
• Verify -enableCodeCoverage YES shows ≥70% line coverage on the framework target (latest local: 89.92%)
• Build NRMediaTailorTracker-iOS scheme against iphonesimulator SDK
• Build NRMediaTailorTracker-tvOS scheme against appletvsimulator SDK
• Smoke-test integration: cd Examples/iOS/SimplePlayerWithAds && pod install, open the workspace, set the MediaTailor session URL via defaults write com.newrelic.SimplePlayerWithAds MediaTailorSampleURL "<your-url>" (or the MT_SAMPLE_URL env var), run the app, tap MediaTailor Sample, confirm in a proxy capture that /v1/tracking/<sessionId> requests round-trip nextToken between consecutive calls
• Confirm in NRDB that AD_BREAK_START → AD_START → 3× AD_QUARTILE → AD_END → AD_BREAK_END fires for at least one ad break on the integration stream, and that trackerVersion = "4.2.0" (not NSNull) on every event

Notes for reviewers

• The customer app drives polling cadence in v1 — the tracker doesn't auto-poll the tracking API. Typical usage is to re-fetch every 5–10 seconds for live streams, often aligned to EXT-X-TARGETDURATION.
• The NRMediaTailorTracker_*.md planning / reference docs at the repo root are intentionally untracked per project convention and are not part of this PR.

[skatti97]

Nice work overall on the A1–A8/B1–B7 fixes vs. the Android reference.

[skatti97]

SCTE-35 EventStream presentationTime isn't offset by the enclosing <Period>'s start. Per the DASH spec, EventStream Event presentationTime is relative to the containing Period's start, but this computes startMs directly from presentationTime with no addition of _currentPeriod.startMs. Contrast with finalizeCurrentPeriod (the non-EventStream branch), which correctly does p.hasStart ? p.startMs : _runningPriorPeriodEndMs. For any MPD with a <Period start="PT100S"> containing an EventStream ad marker, the resulting MTAdBreak.startTimeMs will be wrong by the Period's start offset, causing MTPlayheadStateMachine to fire AD_BREAK_START/quartiles at the wrong playhead position. The only EventStream fixture (mediatailor_dash_dynamic_live.mpd) uses start="PT0S", which masks this.

[skatti97]

timeControlStatus KVO handler reads currentBreak/currentPod without any thread/queue guarantee, while MTPlayheadStateMachine's delegate callbacks write those same properties on the main queue. AVFoundation doesn't guarantee timeControlStatus KVO notifications land on the main thread, so this can run concurrently with the state machine's main-queue mutations. To be precise about the actual risk: since currentBreak/currentPod are declared weak, ARC's weak-accessor machinery is itself thread-safe (no memory corruption), so this isn't a crash risk — but it is a real TOCTOU-style logical race: sendPause/sendResume can fire based on a break/pod that's concurrently exiting on the main queue, producing an ad-pause event for an ad that's already ended from the state machine's point of view. Worth hopping this handler onto the main queue before touching currentBreak/currentPod, to match the stated "main-queue only" contract documented elsewhere in this class.

[skatti97]

enrichBreak: runs (and can queue an MTMergedScheduleError) before the dedup check on line 41-46 decides whether to drop this break. MTMergedScheduleError.adBreak is declared weak, and MergedSchedule.breaks is the only strong owner of MTAdBreak instances in the default (HLS) parsing path. If this break turns out to be a dedup duplicate (same key as an earlier break in this same call — the A4 "live window slide" case), it's enriched — possibly queuing an error — and then dropped from outBreaks at line 46. Once mergeManifestBreaks: returns, nothing retains that dropped break, so the queued error's weak adBreak becomes nil. MTPlayheadStateMachine.drainPendingErrorsForBreak: matches via err.adBreak != brk, which can never match a nil adBreak, so the queued error (e.g. a MISSING_AVAIL_START warning) is silently swallowed. Suggest either skipping enrichment for a break you already know will be deduped, or resolving the dedup key before enriching.

[skatti97]

This treats a legitimate zero-position break the same as an "unset" one. br.startTimeMs is a primitive NSTimeInterval with no sentinel for "unset" — a preroll break parsed at position 0 (a completely normal, correct value) looks identical here to "never set." When the avail is missing startTimeInSeconds (the A8 case) and the break's own startTimeMs happens to be 0.0 because it's a real preroll, this overwrites the correct value with firstAd.startTimeMs, desyncing the break from its own pods (which still start at 0). The existing test testA8_missingAvailStartTime_logsAndQueuesError actually constructs this exact 0→42000ms overwrite but only asserts on the error code/count, not on the resulting startTimeMs, so it wouldn't catch a regression here. Consider gating this fallback on whether the break's start was itself inferred/unknown, rather than on the raw value being 0.0.

[skatti97]

Non-strict <= means a tied delta lets a later avail silently replace an earlier match. bestDelta starts at the full tolerance and this loop updates best/bestDelta whenever delta <= bestDelta, so two avails equidistant from br.startTimeMs resolve to whichever is later in iteration order rather than the first-found. Contrast with the sibling helper elsewhere in this file that uses bestDelta = INFINITY with a strict <, keeping the first-found candidate on ties — this loop is inconsistent with that convention. avails isn't sorted or deduped before this pass, so ties are reachable whenever the tracking API returns two unconsumed avails at the same tolerance-boundary distance. Untested today (no test exercises two candidates at an equal delta). Suggest switching to strict < to match the sibling helper's tie-breaking behavior.

[skatti97]

NRVAVideo.h still declares the old no-arg +(id)createAdTracker; selector, which no longer has an implementation after this rename to createAdTrackerForConfig:. (The header itself isn't touched by this PR's diff, so I can't anchor a comment directly on it — flagging here instead.) Any caller invoking [NRVAVideo createAdTracker] per the still-published public header would crash at runtime with "unrecognized selector sent to class." Nothing in this repo calls the bare selector today, so it's not an active crash, but the public API contract is broken silently. Worth removing (or updating) the stale declaration in NRVAVideo.h line 178 in the same PR.

[skatti97]

Ad-hoc error domain/codes instead of the module's own MTTrackingErrorDomain/MTTrackingErrorCode. fromJSONData: builds NSErrors with domain string @"MTTrackingResponse" and raw codes 1/2, rather than the shared error domain used everywhere else in this module (e.g. MTTrackingClient.m). Any caller that switches on MTTrackingErrorDomain/MTTrackingErrorCodeInvalidResponse or ParseFailed (as NRTrackerMediaTailor.m does for the client's errors) will never match an error from an empty-body or non-object JSON response here — it's silently misclassified into an unlisted domain. Suggest reusing MTTrackingErrorDomain with an appropriate MTTrackingErrorCode here for consistency.

[skatti97]

Shared infrastructure hardcodes a MediaTailor-specific branch rather than a generic per-tracker configuration contract. This if (adTracker && config.adConfig.type == NRAdTrackerTypeMediaTailor) block lives in core addPlayer: and pushes MediaTailor-specific fields (adSegmentPrefix, trackingUrl) via KVC. It also checks respondsToSelector:@selector(setAdSegmentPrefix:) and then calls setValue:forKey:@"adSegmentPrefix" — two different identifiers (a selector and a KVC key string) that aren't tied together, so a future rename of one and not the other would pass the guard and then crash with NSUnknownKeyException. Longer-term, a third tracker type will need another type-switch branch bolted onto this same shared method. A -configureWithAdConfig:player: method that each tracker subclass implements (called uniformly, without NRVAVideo.m knowing tracker-specific field names) would avoid both the KVC/selector drift risk and the growing type-switch.

[skatti97]

Follow-up pass focused purely on code quality (reuse + simplification), no correctness bugs in this batch. 6 findings below.

[skatti97]

Same isKindOfClass:[NSString class]] ? ... : nil guard hand-copied 9 times. This exact pattern — extract a dictionary value, verify it's actually a string, fall back to nil — appears here and at MTAvail.m:32, MTAd.m:44, MTNonLinearAvail.m:26, and MTTrackingEvent.m:28-30,45: nine call sites across four files, each re-deriving the identical check. A small shared helper (e.g. MTStringOrNil(dict, key)) would remove the duplication and give one place to harden the check later (trimming whitespace, tolerating NSNull, etc.) instead of nine.

[skatti97]

Three near-identical blocks differing only by a threshold and a flag name. checkQuartilesForPod: repeats the same if (progress >= X && !pod.hasFiredQN) { pod.hasFiredQN = YES; ... } shape three times for 0.25/Q1, 0.50/Q2, 0.75/Q3 — nothing differs structurally between them. Iterating a small static array of (threshold, quartileNumber) pairs in one loop would remove the copy-paste and the risk of a future edit mismatching a threshold with the wrong flag (or a 4th checkpoint being added as a 4th near-identical block).

[skatti97]

hasFiredAdStart/hasFiredQ1/hasFiredQ2/hasFiredQ3 (lines 47-50) are declared but never read or written anywhere in the module. Quartile/ad-start firing is actually tracked one level down on MTAdPod, which has its own working copies of these same flags that MTPlayheadStateMachine actually uses. The only place these four properties are touched at all is a default-value assertion in MTAdDecodeTests.m (always-passing, since nothing ever sets them). Beyond being dead weight, they're actively misleading — a future contributor skimming this header would reasonably assume break-level quartile tracking happens here, and either build on top of these stale fields or duplicate the (already-correct) pod-level tracking a second time. Suggest deleting all four properties and their corresponding test assertions.

[skatti97]

if (self.isDisposed) { return; } is copy-pasted into 11 methods (this line plus 192, 214, 234, 248, 256, 264, 275, 283, 290, 297), including every MTPlayheadStateMachineDelegate callback. It works today, but it's structurally optional — a new delegate/public method added later that forgets to paste this guard would silently act on a torn-down tracker. Since dispose already tears down self.stateMachine and detaches the player, setting self.stateMachine.delegate = nil before doing so would make the six delegate callbacks structurally impossible to invoke post-dispose, removing the need for the guard on those six specifically (the public entry points like setPlayer:/startTrackingWithSchedule: would still need it, since those can be called directly regardless of the delegate link).

[skatti97]

currentState is a manually-synced cache instead of a computed value. It's independently assigned at (at least) 4 separate spots in this file — line 117 (entering a break), 147 (exiting), 158 (entering a break, no-fill branch), 167 (entering a pod) — rather than being derived on read from currentAdBreak/currentAdPod/isNoFill, which the object already tracks. A future transition path that forgets to update currentState would leave it stale while the rest of the object has already moved on, with nothing to catch the mismatch. Computing it on read instead (if (!self.currentAdBreak) return MTAdStateContent; if (self.currentAdBreak.isNoFill) return MTAdStateNoFill; return self.currentAdPod ? MTAdStateInPod : MTAdStateInBreak;) removes this whole category of "forgot to update it" bug.

[skatti97]

Four parallel (BOOL capturing_, NSMutableString *_Text) pairs (lines 69-74, plus the top-level pair above) track what's structurally a single piece of state: "which BaseURL level am I currently inside, if any." The same 4-way if/else-if chain over these pairs is repeated in didStartElement (~173-192), foundCharacters (~280-296), and didEndElement (~314-344) — their mutual exclusivity is only an implicit convention enforced by re-deriving the same chain three times. A single _baseURLCaptureTarget enum (None/TopLevel/Period/Adaptation/Representation) plus one shared text accumulator would collapse all three call sites to a single switch/if, and make "at most one level capturing at a time" a structural invariant instead of a convention three separate methods have to independently maintain.