streamplay_analytics 0.2.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 it could be published as its own clean package. This is the source — the app doesn't use this repo directly, it installs the published package (see below).

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

Status

Published: streamplay_analytics on pub.dev.

Verified with a real Flutter toolchain before publishing: flutter analyze clean, all 40 tests passing (including the 2 vendor adapter files, which were also checked directly against mixpanel_flutter/posthog_flutter's actual current example apps — not just written from memory). One real bug was found and fixed this way: posthog_adapter.dart's capture() call needed null values filtered out of event properties before sending.

How to use this in the app

Published on pub.dev — install it like any other package, no special setup:

flutter pub add streamplay_analytics

Then:

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