feat(npaw): add @theoplayer/react-native-analytics-npaw connector

[tvanlaerhoven]

Summary

New JS-only analytics connector @theoplayer/react-native-analytics-npaw (under npaw/), structured like the youbora connector but stripped of all native iOS/Android/web modules. It integrates NPAW through the npaw-plugin-react-native JS plugin only, so it works on iOS, Android and web via the unified react-native-theoplayer facade.

The core idea: NPAW's bundled Theoplayer adapter (in the separate npaw-plugin-adapters package) is web-only — it hooks web-THEOplayer DOM events and reads web-only props. Instead, this package ships its own cross-platform adapter classes that NPAW instantiates via registerAdapterFromClass / registerAdsAdapterFromClass. NPAW copies our methods onto its own runtime adapter object and assigns this.player, so our getters/listeners run against NPAW's adapter with the RN player attached — no native code required.

What's here

• NpawConnector(player, config) + useNpaw(config) hook. Config:

  interface NpawConnectorConfig {
    accountCode: string;
    analytics?: NpawAnalyticsOptions; // per-video content.* options
    plugin?: NpawPluginOptions;       // host, sessionRecovery, ...
    logLevel?: LogLevel;
  }

  Runtime option APIs: setVideoOptions(options, videoKey?) (per-video), setAnalyticsOptions(options) (global), setLogLevel(level), destroy().

• TheoplayerAdapter — video adapter. Subscribes to unified PlayerEventType events and maps them to NPAW's fire* API:

  • PLAY/PLAYING → fireStart/fireJoin/fireResume, PAUSE → firePause, WAITING → fireBufferBegin, SEEKING/SEEKED → fireSeekBegin/fireSeekEnd, TIME_UPDATE establishes start/join + ends seek/buffer, SOURCE_CHANGE/ENDED → fireStop, ERROR → fireError.
  • Getters: playhead, duration, isLive, resource, rendition, bitrate, getSubtitles() (active showing subtitle/caption track language) and getVideoLanguage() (active audio track language) — both feed NPAW's auto-detection of subtitle/audio-language usage.
  • getVersion() is player-independent (static, manifest-based) because NPAW calls it during adapter construction before this.player is set.

• TheoplayerAdsAdapter — ads adapter. Subscribes to AD_EVENT and maps subtypes: AD_BREAK_BEGIN/END → fireBreakStart/fireBreakStop, AD_BEGIN → fireStart+fireJoin, quartiles → fireQuartile(1|2|3), AD_SKIP → fireSkip, AD_CLICKED → fireClick, AD_END → fireStop, AD_ERROR → fireError. Getters serve ad duration/resource/title/position(pre|mid|post)/skippable. AD_BUFFERING is intentionally skipped (THEOplayer has no reliable matching buffer-end event).

• Registered in the root workspaces; only dependency is npaw-plugin-react-native.

• e2e app (apps/e2e): useNpawConnector() wired into App.tsx like the other connectors, Npaw.spec.ts create/use/destroy test with a dummy account code, NPAW_ACCOUNT_CODE in .env.example, tsconfig path + metro connector entry. Sample analytics demonstrates content.title + a content.metadata object.

Scope / gap check

Reviewed against NPAW's shipped plugin API + option registry. Content metadata, subtitles and audio language are wired; all other NPAW options (the full content.*/user.*/ad.*/parse.*/… set) are supported generically via analytics / setVideoOptions / setAnalyticsOptions. Getters NPAW can't be reliably fed from the RN facade cross-platform (throughput, dropped frames, fps, codecs) are intentionally left to NPAW defaults.

Notes / caveats

• Not runtime-tested against a live NPAW account or a real ad source from here — the event→fire* mappings are verified against NPAW's shipped types and the plugin source, but a smoke test in an app (playback + ads) is worth doing before release.
• LogLevel is a local enum mirroring the plugin's numeric values, since the RN entry only default-exports NpawPlugin.

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

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9a0359d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[devin-ai-integration]

Devin Review found 4 potential issues.

[devin-ai-integration]

Devin Review found 2 new potential issues.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

Devin Review found 1 new potential issue.