Skip to main content

jatayu_flutter 0.1.0 copy "jatayu_flutter: ^0.1.0" to clipboard
jatayu_flutter: ^0.1.0 copied to clipboard

unlisted

Mobile analytics, attribution, observability, and remote configuration for the Jatayu platform.

Jatayu for Flutter #

pub package

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 #

  1. 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).
  2. 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());
}
  1. 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'});

endpoint must 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 with allowInsecureLocalhost: true.

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, records app_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 ArgumentError before anything is queued. All callbacks run on the main Flutter isolate, and the optional onDiagnostic callback 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'});
// 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);
  • pendingReferralCode holds a staged code (Play referrer jatayu_referral_code or 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_open starts a session. Returning to the foreground after sessionTimeout (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 storageNamespace stable 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 custom httpClient is 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.

1
likes
0
points
56
downloads

Publisher

verified publisheraravindchowdary.com

Weekly Downloads

Mobile analytics, attribution, observability, and remote configuration for the Jatayu platform.

Repository (GitHub)
View/report issues

Topics

#analytics #attribution #remote-config

License

unknown (license)

Dependencies

crypto, flutter, http, shared_preferences, uuid

More

Packages that depend on jatayu_flutter

Packages that implement jatayu_flutter