tracking_kit

tracking_kit is a Flutter plugin that gives the host app one tracking API for Firebase, Adjust, TikTok, Meta/Facebook, Sentry, AppsFlyer, and future third-party tracking providers.

The host app does not clone or directly own vendor SDK setup code. It installs this library, passes provider config once at startup, and sends normalized events through TrackingKit.

Clean Architecture Flow

Host app
  |
  | configure(), trackEvent(), setUserId()
  v
lib/tracking_kit.dart
  Public facade and typed Dart API
  |
  v
Domain
  Entities: TrackingKitConfig, TrackingEvent, provider configs
  Use cases: ConfigureTracking, TrackEvent
  Repository contract: TrackingRepository
  |
  v
Data
  TrackingRepositoryImpl
  MethodChannelTrackingPlatformDataSource
  |
  v
Native plugin bridge
  Android: TrackingDispatcher -> provider clients
  iOS: TrackingDispatcher -> provider clients
  |
  v
Third-party SDKs
  Firebase, Adjust, TikTok, Meta, Sentry, AppsFlyer

Rules:

• Domain code has no Flutter, Android, iOS, or third-party SDK dependency.
• Data code converts typed Dart models to MethodChannel maps.
• Native code owns provider dispatch and must fail safely if an optional vendor SDK is unavailable.
• Host apps pass config and events only.

Flutter Host App

Add the package:

dependencies:
  tracking_kit:
    git:
      url: <tracking_kit_repository_url>
      ref: main

Configure once before sending events:

import 'package:tracking_kit/tracking_kit.dart';

Future<void> bootstrapTracking() async {
  await TrackingKit.instance.configure(
    const TrackingKitConfig(
      appName: 'My Host App',
      enabledProviders: {
        TrackingProvider.firebase,
        TrackingProvider.adjust,
        TrackingProvider.tiktok,
        TrackingProvider.meta,
        TrackingProvider.sentry,
        TrackingProvider.appsFlyer,
      },
      firebase: FirebaseTrackingConfig(),
      adjust: AdjustTrackingConfig(
        appToken: 'adjust_app_token',
        environment: TrackingEnvironment.production,
      ),
      tiktok: TikTokTrackingConfig(
        appId: 'tiktok_app_id',
        tiktokAppId: 'tiktok_business_app_id',
      ),
      meta: MetaTrackingConfig(
        applicationId: 'facebook_app_id',
        clientToken: 'facebook_client_token',
      ),
      sentry: SentryTrackingConfig(
        dsn: 'https://public@sentry.example/1',
        environment: 'production',
      ),
      appsFlyer: AppsFlyerTrackingConfig(
        devKey: 'appsflyer_dev_key',
        appleAppId: '123456789',
      ),
      defaultParameters: {
        'app_channel': 'store',
        'tenant': 'main',
      },
    ),
  );
}

Track events:

await TrackingKit.instance.trackEvent(
  'checkout_started',
  parameters: {
    'sku': 'pro_monthly',
    'source': 'pricing',
  },
);

await TrackingKit.instance.trackPurchase(
  transactionId: 'order-1001',
  value: 9.99,
  currency: 'USD',
  parameters: {'sku': 'pro_monthly'},
);

await TrackingKit.instance.setUserId('user-123');
await TrackingKit.instance.setUserProperties({
  'plan': 'pro',
  'country': 'VN',
});

iOS Host App

Minimum iOS version: 14.0.

Flutter integration is automatic after the package is added. The host app only needs normal vendor account files/metadata that cannot be generated by the library, for example:

• Firebase: GoogleService-Info.plist
• Meta/Facebook: FacebookAppID, FacebookClientToken, URL scheme in Info.plist
• AppsFlyer: Apple app id passed through AppsFlyerTrackingConfig
• Sentry: DSN passed through SentryTrackingConfig
• TikTok: app id values passed through TikTokTrackingConfig
• ATT consent flow if the product needs IDFA-based attribution

Example Info.plist keys for Meta:

<key>FacebookAppID</key>
<string>facebook_app_id</string>
<key>FacebookClientToken</key>
<string>facebook_client_token</string>
<key>FacebookDisplayName</key>
<string>My Host App</string>
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fbfacebook_app_id</string>
    </array>
  </dict>
</array>

Call TrackingKit.instance.configure(...) from Flutter during app startup. Native Swift receives the config and fans out to provider clients.

Android Host App

Minimum Android SDK: 24.

Flutter integration is automatic after the package is added. The host app only needs normal vendor account files/manifest metadata that cannot be generated by the library, for example:

• Firebase: google-services.json
• Meta/Facebook: app id/client token metadata and URL scheme
• AppsFlyer, Adjust, TikTok, Sentry: keys passed through TrackingKitConfig
• Advertising ID permission if attribution requires it

Example AndroidManifest.xml metadata for Meta:

<application>
  <meta-data
    android:name="com.facebook.sdk.ApplicationId"
    android:value="@string/facebook_app_id" />
  <meta-data
    android:name="com.facebook.sdk.ClientToken"
    android:value="@string/facebook_client_token" />
</application>

Call TrackingKit.instance.configure(...) from Flutter during app startup. Native Kotlin receives the config and fans out to provider clients.

Native Provider Behavior

Third-party dependencies are owned by this package:

• Flutter plugin dependencies in pubspec.yaml: Firebase Core, Firebase Analytics, Adjust, Meta/Facebook App Events, Sentry, AppsFlyer.
• Android native dependency in android/build.gradle.kts: TikTok Business Android SDK.
• iOS native dependency in ios/tracking_kit.podspec: TikTokBusinessSDK.

The TikTok Flutter wrapper is intentionally not used because its Android registrant currently fails under the AGP/Flutter setup used by this package. TikTok still remains inside this library through native Android/iOS dependencies, so host apps do not need to clone or add it themselves.

The native bridge accepts these commands:

• configure: stores default parameters and creates enabled provider clients.
• track: merges default parameters and sends the event to every enabled provider.
• setUserId: updates providers that support user identity.
• setUserProperties: updates providers that support user attributes.
• setEnabled: pauses or resumes dispatch.
• flush: flushes providers that expose a flush API.
• reset: clears runtime state.

Provider clients are isolated behind the dispatcher. If a vendor SDK is not linked or not initialized yet, the reflective client ignores that provider instead of crashing the host app.

Event Naming

Use stable snake-case event names:

app_opened
screen_view
signup_started
signup_completed
checkout_started
purchase
subscription_cancelled

Keep parameters primitive and serializable: String, int, double, bool, or null.

Production Checklist

• Configure providers once, before the first tracked event.
• Keep secrets out of source control; pass environment values from the host app config.
• Gate provider enablement by environment and consent.
• Do not send PII unless the product and vendor contracts allow it.
• Add vendor account files to host apps, not to this package.
• Run flutter test before publishing.