streamplay_analytics 0.1.0

One analytics module for the Flutter app — swap the vendor (Mixpanel, PostHog, ...) from the CMS, no code change. Dart port of @matchbest-group/streamplay-analytics (the web SDK — separate repo, strea [...]

streamplay_analytics (Flutter/Dart)

The Flutter/Dart port of @matchbest-group/streamplay-analytics — the web SDK, which lives in its own separate repo, streamplay-analytics-sdk. Same 4-function contract, same event names/fields — one analytics module that swaps Mixpanel/PostHog based on what's picked in the CMS, no app code change needed.

This is a standalone repo, not a folder inside streamplay-analytics-sdk — deliberately, so the mobile team never needs any access to that other (private) repo. See "How to use this in the app" below.

Full spec: ANALYTICS_PHASE_5_FLUTTER_PRD.md in streamplay_backend. Event names/fields: ANALYTICS_EVENT_REFERENCE.md in streamplay_backend.

Status

Written without a Flutter/Dart toolchain available to run the full package (none was installed when it was written) — not yet run, built, or tested against a real flutter pub get / flutter test.

What HAS been verified: the core logic (the state machine, the event queue, the auto-fill/snapshot rules, the backend-call handling) was validated using a plain Dart install and a temporary copy that swapped out only the 2 files needing real Flutter plugins — all 40 tests passed, and dart analyze found no issues.

Still needs a real Flutter environment to verify:

1. flutter pub get resolving cleanly with the real mixpanel_flutter/posthog_flutter versions.
2. flutter test passing end-to-end (including the 2 vendor adapter files, untested here).
3. lib/src/adapters/mixpanel_adapter.dart and posthog_adapter.dart checked against whatever exact plugin version gets installed — those two plugins' setup APIs have changed across major versions, and the calls here are written from general knowledge of the APIs, not verified against a specific installed version.

How to use this in the app

There's no pub.dev publish step — Dart has no private-registry equivalent to npm/GitHub Packages (pub.dev only hosts fully public packages), so publishing this would make it public. Instead: copy the code in, once.

1. Clone this repo.
2. Copy lib/ into the Flutter app's own repo.
3. Add this package's 3 dependencies (http, mixpanel_flutter, posthog_flutter — see pubspec.yaml) into the app's own pubspec.yaml.
4. Commit — from here on it's just the app's own code, no further connection to this repo needed.

Don't reference this repo as a live pubspec.yaml git dependency instead — that would require the app's CI/CD pipeline to have its own git credentials to clone this repo on every build, an avoidable extra token/access setup. Copying the code in needs none of that, and — since this is its own repo containing only this package — nobody needs access to anything beyond what they're copying.

Once copied in, the app just does:

import 'package:streamplay_analytics/streamplay_analytics.dart';

await initAnalytics(InitAnalyticsConfig(
  talentId: tenantId,
  platform: Platform.isIOS ? 'ios' : 'android',
  apiBaseUrl: 'https://apigw2.streamplay.ai', // confirm the real reachable URL — see PRD §3
));

trackEvent('video_play', {'videoId': videoId, 'position': position});
identifyUser(userId);
resetUser();

One Flutter-specific difference from the web SDK

The web SDK auto-reads screenName from window.location.pathname — there is no equivalent automatic "current page" on Flutter. Call setScreenName() from a NavigatorObserver (or wherever this app already tracks navigation) on every screen change, or screenName will just read "unknown" on every event. See lib/src/context.dart's header comment.

Folder structure

lib/
├── streamplay_analytics.dart   → the only file the app imports
└── src/
    ├── core.dart                → the "brain": the 4 functions, state machine
    ├── queue.dart                → holds events fired too early (cap 50)
    ├── context.dart              → auto-fills userId/screenName/timestamp/talentId/platform
    ├── config_client.dart        → calls GET /api/v1/client/bootstrap
    ├── adapter_registry.dart     → picks the right adapter for the active tool
    └── adapters/
        ├── adapter.dart          → the shared init/track/identify/reset shape
        ├── mixpanel_adapter.dart
        └── posthog_adapter.dart
test/                             → mirrors the web SDK's test coverage