jatayu_flutter 0.1.0
jatayu_flutter: ^0.1.0 copied to clipboard
Mobile analytics, attribution, observability, and remote configuration for the Jatayu platform.
Jatayu for Flutter #
Mobile analytics, attribution, error tracking, and remote configuration for iOS and Android, backed by the Jatayu platform.
- Analytics — offline-first event queue with batched delivery, sessions, screens, and client-reported revenue.
- Identity — anonymous installs, user IDs, traits, groups, Firebase Auth, and server-minted identity tokens.
- Remote config — typed flags and values per environment, cached offline, refreshed in the background.
- Attribution — Play Install Referrer on Android; SKAdNetwork and AdAttributionKit bridges on iOS; referral codes and campaign links.
- Observability — automatic Dart/Flutter error capture plus timed traces.
- Uninstall signals — APNs / FCM token registration for server-side invalidation checks.
Requires Dart >=3.3.0, Flutter >=3.19.0, iOS 13+ or Android API 21+. Flutter Web and desktop are not supported.
Install #
flutter pub add jatayu_flutter
import 'package:jatayu_flutter/jatayu_flutter.dart';
Quickstart #
- In the Jatayu dashboard, open Applications and create (or select) your app. Copy the public SDK key and note your Jatayu server origin (for example
https://analytics.your-domain.com). - Initialize once, before
runApp, with collection switched off until your app has permission to collect analytics:
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await Jatayu.initialize(JatayuOptions(
endpoint: 'https://analytics.your-domain.com',
writeKey: 'YOUR_APP_WRITE_KEY',
appVersion: '1.0.0', // or 'auto' to read the native app version
consent: false,
));
runApp(const MyApp());
}
- After the user accepts (your own consent UI, onboarding step, or settings toggle), enable collection:
await Jatayu.instance.setConsent(true);
await Jatayu.instance.track('product_view', {'product_id': 'pro'});
endpointmust be an HTTPS origin (https://host, no path or query string). Plain HTTP is accepted only for local development hosts (localhost,127.0.0.1,10.0.2.2,::1) together withallowInsecureLocalhost: true.
Consent and privacy #
Collection is opt-in. The SDK sends nothing until consent is granted:
consent: false(the default) at initialize means no identifiers are created, no events are queued, and no network calls are made.setConsent(true)creates the installation ID, recordsapp_open, flushes, and fetches remote config.setConsent(false)clears queued events, cached config, and installation identity on-device and stops future collection. A request already accepted by the server cannot be recalled; use the dashboard's erasure operation for server-side data.- Consent here is an application-level collection switch, not Apple ATT authorization. The SDK requests no IDFA, GAID, hardware identifier, fingerprinting, or location permissions.
- On-device storage (SharedPreferences) is app-private but not encrypted. Do not put secrets or sensitive personal data in event properties. Registered push tokens are encrypted server-side.
- Invalid event arguments throw
ArgumentErrorbefore anything is queued. All callbacks run on the main Flutter isolate, and the optionalonDiagnosticcallback receives non-sensitive diagnostic messages only (no payloads or keys).
Tracking events #
final analytics = Jatayu.instance;
await analytics.track('product_view', {'product_id': 'pro'});
await analytics.screen('checkout'); // sends screen_view with {'screen': 'checkout'}
await analytics.revenue(29.99, 'USD'); // sends purchase with revenue + currency
await analytics.flush(); // optional: deliver now instead of waiting for the next batch
Rules enforced client-side (violations throw before queueing):
- Event names: up to 100 characters, matching
[a-zA-Z_$][a-zA-Z0-9_.$ -]*. - Properties: property names up to 100 characters; total encoded size up to 16 KB.
- Revenue: finite, non-negative amount up to 100,000,000 with an uppercase ISO 4217 currency (
'USD','EUR', …).
pendingEventCount exposes the number of events still queued, and installationId the stable per-install anonymous ID.
Identity #
// Tie the install to your own user record.
await Jatayu.instance.identify('your-internal-user-id',
properties: {'plan': 'pro'},
setOnce: {'signup_source': 'referral'},
);
// Update traits without changing the user ID (sends properties_updated).
await Jatayu.instance.setUserProperties({'plan': 'team'});
await Jatayu.instance.setUserProperties({'first_seen': '2026-01-01'}, once: true);
// Group the user (up to 20 group types; sends group_assigned and refreshes config).
await Jatayu.instance.setGroup('organization', 'acme', properties: {'plan': 'pro'});
await Jatayu.instance.removeGroup('organization'); // sends group_removed
// Clear the local user and start fresh (sends identity_reset).
await Jatayu.instance.resetIdentity();
- User IDs: 1–200 characters, must not start with
anon:. - Group types: start with a letter, up to 50 characters of
[word chars, '.', '-']; keys up to 200 characters. - Switching to a different user ID rotates the anonymous ID and clears traits, groups, and the previous identity token.
Firebase Auth and server-minted identity #
// Host app signs in with Firebase, then hands the ID token over (refresh it on expiry).
await Jatayu.instance.authenticateFirebase(firebaseIdToken);
// Or mint identity server-side and pass it to the client.
// The token comes from POST /api/server/users (server key). Never embed a server secret in an app.
await Jatayu.instance.setIdentityToken(userId: 'user_123', token: serverMintedToken);
Authenticated requests automatically carry the identity token (X-Jatayu-User) for referrals and config personalization.
Remote config #
Publish values per environment (production / staging) in the dashboard; the SDK caches them per environment, refreshes every five minutes, uses ETags, and falls back to cached values offline. Missing, disabled, or out-of-rollout keys return your typed fallback.
await Jatayu.instance.fetchConfig();
final enabled = Jatayu.instance.getBool('onboarding_v2', fallback: false);
final welcome = Jatayu.instance.getString('welcome_message', fallback: 'Hi!');
final price = Jatayu.instance.getNumber('price', fallback: 9.99);
final card = Jatayu.instance.getJson<Map<String, dynamic>>('home_card');
// React to background refreshes.
Jatayu.instance.onConfigChanged.listen((values) => updateUi(values));
configVersion exposes the currently applied config version.
Errors and performance traces #
Dart/Flutter exceptions are captured automatically (captureFlutterErrors: true, the default) without replacing your existing error handlers. Native process crashes, ANRs, hangs, and native stack symbolication are not captured.
// Manual reporting.
await Jatayu.instance.recordError(error, stackTrace, fatal: false);
// Time an operation; records a trace event with durationMs + success, and still rethrows.
final products = await Jatayu.instance.trace('api.products', loadProducts,
properties: {'source': 'home'});
Referrals and campaign links #
// Authenticated users can create a referral link to share.
final link = await Jatayu.instance.createReferralLink(); // {'code': ..., 'url': ...}
// Redeem a code entered by the user (e.g. from an install referrer or a shared link).
await Jatayu.instance.redeemReferral('ABCD1234');
// Pass inbound app/universal links from your host link handler.
// /r/<code> links stage a referral (redeemed automatically once authenticated);
// /l/<id> links resolve the campaign and record campaign_open.
final result = await Jatayu.instance.handleLink(incomingUri);
pendingReferralCodeholds a staged code (Play referrerjatayu_referral_codeor an/r/link) until the user authenticates, at which point it is redeemed automatically.- Android campaign attribution reads the Play Install Referrer after consent and matches the click ID server-side to the same app within seven days, once only. The referrer is client-supplied, not an attested anti-fraud signal; sideloaded installs may have no referrer.
Push tokens and uninstall signals #
Forward tokens from your existing messaging integration — the SDK installs no push SDK and shows no permission prompts:
await Jatayu.instance.registerPushToken(token: fcmToken, provider: PushProvider.fcm);
// Re-register whenever the token rotates. APNs hex tokens use PushProvider.apns.
Tokens must be 16–4096 characters. In the dashboard's Uninstall signals page, paste the FCM service account (Android) or add the APNs .p8 signing key (iOS). Token invalidation is delayed and is not definitive proof of an uninstall.
iOS attribution (SKAN / AdAttributionKit) #
// iOS only; call both when ad networks use both Apple frameworks.
await Jatayu.instance.updateConversionValue(12, coarseValue: 'medium');
await Jatayu.instance.updateAdAttributionValue(12);
- Conversion values are 0–63. SKAN updates need iOS 14+ (coarse values 16.1+); AdAttributionKit needs iOS 17.4+ and an Xcode SDK that includes it.
- Set the numeric App Store ID in Jatayu → Applications, and add to your app's
Info.plist:
<key>NSAdvertisingAttributionReportEndpoint</key>
<string>https://your-registrable-domain.com</string>
<key>AttributionCopyEndpoint</key>
<string>https://your-registrable-domain.com</string>
- Apple resolves the registrable domain and ignores subdomains. Your domain must route these HTTPS endpoints to Jatayu (no write keys in these URLs — Apple signatures authenticate the postbacks):
POST /.well-known/skadnetwork/report-attribution/
POST /.well-known/appattribution/report-attribution/
A bare hosting subdomain is not a verified Apple postback setup: connect an owned domain and verify delivery from a real device. For APNs, the host app registers for remote notifications, forwards the device token, and enables Background Modes → Remote notifications. The package ships a privacy manifest — review your app's disclosure for the data you choose to send.
Android notes #
Minimum API 21; the plugin builds with Java 17, Kotlin, and Gradle. Internet permission is included. The Play Install Referrer (v2.2) is read through a native bridge only after collection consent. Use your existing Firebase Messaging integration to obtain tokens and forward refreshes to registerPushToken.
Delivery, sessions, and lifecycle #
app_openstarts a session. Returning to the foreground aftersessionTimeout(default 30 minutes) starts a new session.- Events are queued persistently and sent in batches of 100 every
flushInterval(default 15 seconds) and when the app backgrounds. Every event carries a stable UUID and the server deduplicates retries. - Retries use exponential backoff up to five minutes and honor
Retry-After. Failed batches stay queued;flush()retries immediately. - The queue defaults to 1,000 events (configurable up to 10,000 via
maxQueueSize); the oldest events are dropped at capacity. Events older than 29 days are dropped before sending, matching the server's 30-day timestamp window. - A heartbeat is sent every 30 seconds while foregrounded (powers live-user counts); call
heartbeat()to send one manually. - Keep
storageNamespacestable across write-key rotation to preserve the installation ID, and use a distinct namespace per project if one host app initializes multiple projects. - Shut down in tests or on full teardown with
await Jatayu.shutdown()(flushes, restores error handlers, closes owned HTTP clients). A customhttpClientis owned by its creator.
Options reference #
| Option | Default | Notes |
|---|---|---|
endpoint |
required | Jatayu server origin, HTTPS (see local-dev exception above). |
writeKey |
required | App's public SDK key from Applications. |
appVersion |
'auto' |
'auto' reads the native app version; any other value is sent as-is. |
consent |
false |
Grant only after your app has permission to collect analytics. |
environment |
'production' |
'production' or 'staging'; selects the remote-config environment. |
storageNamespace |
'default' |
Unique per project inside one host app; keep stable across key rotation. |
flushInterval |
15 s | Minimum 1 second. |
configFetchInterval |
5 min | Background remote-config refresh cadence. |
sessionTimeout |
30 min | Foreground gap that starts a new session. |
maxQueueSize |
1000 |
1–10,000; oldest events dropped at capacity. |
captureFlutterErrors |
true |
Forward Dart/Flutter errors while preserving existing handlers. |
allowInsecureLocalhost |
false |
Allow HTTP only for local-dev hosts. Never enable in production. |
httpClient |
owned client | Inject for tests or controlled networking. |
onDiagnostic |
null |
Non-sensitive diagnostics; payloads and keys are omitted. |
Example app and verification #
The example/ app exercises connect, consent, identify, groups, events, and remote config:
flutter pub get
flutter analyze
flutter test
cd example
flutter pub get
flutter run --dart-define=JATAYU_ENDPOINT=https://your-domain.com \
--dart-define=JATAYU_WRITE_KEY=your-write-key
For a local server use http://10.0.2.2:3001 on an Android emulator or http://localhost:3001 on the iOS Simulator, with allowInsecureLocalhost: true and a matching dev network policy.
Sources: SKAN verification, AdAttributionKit, Apple copy endpoints, Play Install Referrer, FCM registration management.
Support #
Report issues at https://github.com/kamaravichow/jatayu/issues.