# Flutter SDK

URL: https://traqio.app/docs/sdks/flutter
Last updated: 2026-10-22

Add Traqio to a Flutter app: the traqio package reads the Play Install Referrer on Android, registers with SKAdNetwork on iOS and forwards deep links.

`traqio` is the Traqio SDK for Flutter: a Dart package with an Android and an iOS plugin. On Android it reads the **Google Play Install Referrer** for deterministic attribution; on iOS it registers installs with **SKAdNetwork**. It queues events in `shared_preferences`, records app opens from the app lifecycle, and forwards deep links. No pasteboard, and no advertising id — the opt-in the iOS, Android and React Native SDKs offer is not in this one yet.

## Requirements

- Dart 3, Flutter 3.
- Android 5.0 (API 21) or later; iOS 13 or later.

## Set up

### Add the package

```bash
flutter pub add traqio
```

Until the package is on pub.dev, reference the copy we send you by path:

```yaml
# pubspec.yaml — the package you received, until it is on pub.dev
dependencies:
  traqio:
    path: ../traqio
```

### Initialise in main()

lib/main.dart:
```dart
import 'package:flutter/widgets.dart';
import 'package:traqio/traqio.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Traqio.init(sdkKey: 'YOUR_SDK_KEY', endpoint: 'https://api.traqio.app');
  runApp(const MyApp());
}
```

`init` reports the install on first launch, resolves the deferred deep link and records the app open. Awaiting it before `runApp` makes sure the URL that opened the app is not missed.

### Track events and set the user id

```dart
Traqio.setUserId(user.id); // after sign-in — same id as RevenueCat's app_user_id
Traqio.track('signup');
Traqio.track('purchase', value: 9.99, currency: 'EUR');
```

Names Meta and TikTok can optimise on: [Event names](https://traqio.app/docs/concepts/events-and-revenue#names).

### Declare the SKAdNetwork endpoint

ios/Runner/Info.plist:
```xml
<key>NSAdvertisingAttributionReportEndpoint</key>
<string>https://api.traqio.app</string>
```

## Deep links

```dart
final unsubscribe = Traqio.onDeepLink((link) {
  if (link.deepLink != null) router.go(link.deepLink!);
});

// The install's deferred link, or null:
final deferred = await Traqio.getDeferredDeepLink();
```

The plugin forwards URLs on its own and never consumes them: your router still receives every one. An iOS app on the UIScene lifecycle does not get the app-delegate callbacks the plugin listens to, and forwards URLs itself:

```dart
// iOS apps on the UIScene lifecycle only: forward the URL yourself
Traqio.handleUrl(url.toString());
```

## Consent

```dart
await Traqio.setConsent(granted); // sharing with ad networks, not measurement
```

## API

| Call | What it does |
| --- | --- |
| init(sdkKey:, endpoint:, userId:, deepLinking: true, consent:) | Start once. |
| track(name, value:, currency:) | Queue an event; batches of 20, retried with backoff. |
| setUserId(id) | Attach your user id from now on. |
| setConsent(granted) | Persist the user's ad-sharing consent. |
| onDeepLink(listener) | Subscribe; returns the unsubscribe function. |
| getDeferredDeepLink() | The install's deferred link, or null. |
| handleUrl(url) | Resolve a URL that reached the app another way. |

## Not in this SDK yet

- **iOS conversion values and Apple Ads.** Installs are registered with SKAdNetwork, but no conversion value is set and no Apple Ads token is reported.
- **Install Referrer retries.** The referrer is read once at first launch; if Google Play does not answer, the install is reported organic.
- **Purchase transaction ids, AdMob ad revenue, in-app erasure.** Use [RevenueCat](https://traqio.app/docs/integrations/revenuecat) for purchases and the [server-side erasure](https://traqio.app/docs/concepts/privacy#erasure).

> **Proof so far** The Dart code is analysed in CI and the Android half has run end to end on an emulator; the iOS plugin has not been compiled by Traqio yet. The first production app is also the first full test of its native halves.

## Frequently asked questions

**Does the Flutter SDK set SKAdNetwork conversion values?**
Not yet. On iOS it registers each install with SKAdNetwork, so installs from ad networks are attributed through Apple's postbacks, but it does not set conversion values from your mapping, so those postbacks carry no revenue signal. The React Native and native iOS SDKs do set them.

**Do I need to forward deep links myself?**
Usually not. The plugin forwards the launch intent and new intents on Android, and universal links and URL opens received by the iOS app delegate. Only an iOS app on the UIScene lifecycle passes URLs to Traqio.handleUrl itself.