Fix adobe-edge web: "Session ID is not available" race on media events

[tvanlaerhoven]

Summary

On web, AdobeEdgeHandler treated trackSessionStart() as fire-and-forget: it flipped _sessionInProgress = true immediately, so any media event fired before the edge network returned a sessionId was rejected by alloy with
Failed to trigger media event: media.bitrateChange. Session ID is not available for playerId: <uuid>.

The session is now only considered active once the start is confirmed, events are queued until then, and failed starts are retried:

startSession(mediaLength, attempt, sessionMetadata?) {
  const generation = ++this._sessionGeneration;   // invalidates in-flight starts on reset/sourcechange
  this._sessionStarting = true;
  Promise.resolve(tracker.trackSessionStart(...))
    .then((result) => {
      if (generation !== this._sessionGeneration) { /* orphan: complete if needed, then end */ return; }
      if (result?.sessionId) { this._sessionInProgress = true; flush(this._eventQueue); }
      else                   { this.retryStartSession(generation, mediaLength, attempt, customMetadata); }
    })
    .catch(() => this.retryStartSession(...));     // no more unhandled rejections
}

Other behaviour worth calling out:

• maybeStartSession() is retried once the media tracker promise resolves, so a loadedmetadata that arrives before the tracker is ready no longer silently skips the session start.
• Retries: 3 attempts with 1s/2s backoff. After giving up, _sessionStartAbandoned is set and events are dropped (not queued) until a sourcechange/stopAndStartNewSession starts a fresh session.
• The custom metadata from updateMetadata() is snapshotted for the first attempt and reused by every retry, so a retried session start still reports the customer's metadata instead of an empty object. Metadata set after the snapshot is kept for the next session.
• If playback ends while a start is still in flight, _completeOnConfirm remembers it so the late-confirmed session is completed (sessionComplete) before it is ended, instead of losing the completion.
• The pending-event queue is capped at MAX_EVENT_QUEUE_SIZE = 500 (oldest dropped first), so a start that never resolves cannot grow the queue without bound.

Testing

In adobe-edge: npm test (18 tests, new sessionStart.test.ts covers queue/flush, retry + recovery, rejection, tracker-not-ready race, metadata on retries, late completion, queue cap and orphan close), npm run typescript, npm run build.

Link to Devin session: https://dolby.devinenterprise.com/sessions/37fdbe28150a45588efc33754efcdd32
Requested by: @tvanlaerhoven

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 9ff1ccc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@theoplayer/react-native-analytics-adobe-edge	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

🟡 A viewing session can be left open forever when the viewer switches videos quickly

The late-confirmed old session is left open (the closing step is skipped by the !this._sessionStarting guard at adobe-edge/src/internal/web/AdobeEdgeHandler.ts:519) whenever a new session has already begun starting, so that viewing session is never closed and keeps counting as active in Adobe.
Impact: Adobe reports an abandoned, never-ending playback session (inflated viewing time / missing session end) when a viewer changes source before the previous session start was confirmed.

Generation guard skips the orphan close while a newer start is in flight

Flow:

1. loadedmetadata starts session A; trackSessionStart is in flight, _sessionStarting = true, generation = g.
2. sourcechange → maybeEndSession() → reset() (adobe-edge/src/internal/web/AdobeEdgeHandler.ts:605-621) increments the generation and sets _sessionStarting = false. No sessionEnd is sent because _sessionInProgress is still false.
3. The new source fires loadedmetadata and startSession() for session B begins, setting _sessionStarting = true again — this typically happens well within the edge round-trip that the PR is built around.
4. Session A's promise now resolves with a sessionId. The generation mismatch branch is taken, but the extra guard !this._sessionStarting && !this._sessionInProgress is false, so neither sessionComplete nor sessionEnd is sent for session A.

The guard exists because a single MediaTracker instance (this._tracker, obtained once via media.getInstance()) is shared by all sessions, so ending "the tracker" would end the wrong session. A per-session tracker instance would allow closing the orphan correctly.

Prompt for agents

In adobe-edge/src/internal/web/AdobeEdgeHandler.ts, startSession() handles the case where an in-flight trackSessionStart resolves after the session was superseded (generation mismatch). It only sends sessionComplete/sessionEnd when no newer session is starting or in progress (`!this._sessionStarting && !this._sessionInProgress`). When a sourcechange is quickly followed by a new loadedmetadata, the newer start is already in flight, so the older, now-confirmed edge session never receives a sessionEnd and stays open on Adobe's side.

Root cause: a single MediaTracker instance (created once with media.getInstance() in the constructor) is shared across all sessions, so ending the tracker would end whichever session it currently owns, not the orphaned one. Consider obtaining a fresh tracker instance per session (media.getInstance() inside startSession, keeping a reference alongside the generation) so an orphaned session can be completed/ended on its own tracker without affecting the newer session, and destroy() it afterwards. Alternatively, delay starting a new session until any in-flight start has settled.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

The behaviour is real: on a fast sourcechange → loadedmetadata, session A's late confirmation hits the generation-mismatch branch while _sessionStarting is true for session B, so no sessionEnd is sent for A. Two corrections to the impact: on main today the same scenario sends no sessionEnd either (A was never marked in progress), so this is not a regression; and the edge closes idle media sessions server-side after its inactivity timeout, so A is abandoned rather than "never-ending" — the missing signal is an explicit end, which does skew session duration.

The suggested fix is viable: in the pinned alloy (getMediaAnalyticsTracker → getInstance) each getInstance() call builds a fresh tracker with its own session state, so a per-session tracker would let the orphan be ended on its own instance while B keeps its own. That is a broader change than the race this PR fixes (every sendEvent currently routes through the single shared this._tracker), so I'd rather not slip it in here unannounced.

@tvanlaerhoven: want me to do the per-session tracker in this PR, or leave it as a follow-up given it is not a regression?