Flutter SDK

Complete reference for the AppRefer Flutter SDK. Supports iOS and Android with a single integration.

Installation#

Add the SDK as a git dependency in your pubspec.yaml:

dependencies:
  apprefer_flutter_sdk:
    git:
      url: https://github.com/AppAgentic/apprefer-flutter-sdk.git
      ref: main

flutter pub get

Android Setup#

To enable Google Play Install Referrer attribution on Android, add the Install Referrer library to your app-level build.gradle:

dependencies {
    implementation "com.android.installreferrer:installreferrer:2.2"
}

Configuration#

The AppReferConfig object accepts the following parameters:

API Reference#

AppReferSDK.configure(config)#

Initialize the SDK and resolve attribution. Call once at app launch. Returns the attribution result or null if the device is organic (no matching click found).

final attribution = await AppReferSDK.configure(AppReferConfig(
  apiKey: 'pk_live_your_key_here',
  debug: true,
));

AppReferSDK.trackEvent(name, ...)#

Send a custom event to AppRefer. Events can trigger ad network forwarding if configured.

await AppReferSDK.trackEvent(
  'tutorial_complete',
  properties: {'level': 3, 'time_spent': 42},
);

// With revenue
await AppReferSDK.trackEvent(
  'purchase',
  revenue: 9.99,
  currency: 'USD',
);

AppReferSDK.setAdvancedMatching(...)#

Send hashed PII to improve ad network match rates. All values are SHA256-hashed on the device before being sent to the server. The server never receives plaintext PII.

await AppReferSDK.setAdvancedMatching(
  email: 'user@example.com',
  phone: '+15551234567',
  firstName: 'Jane',
  lastName: 'Doe',
);

AppReferSDK.setUserId(userId)#

Associate a user ID with the device's attribution. This provides an additional matching signal for purchase webhooks.

// REQUIRED: Set appreferId on RevenueCat first
await Purchases.shared.setAttributes({"appreferId": attribution.deviceId});

// Then optionally set user ID for additional matching
await AppReferSDK.setUserId(Purchases.appUserID);

AppReferSDK.getAttribution()#

Returns the cached attribution from the last configure() call. Returns null if configure() has not been called yet or the device is organic.

AppReferSDK.getDeviceId()#

Returns the device ID generated by AppRefer. This is a stable UUID created on first launch and persisted across app restarts.

Attribution Model#

The Attribution object returned by configure() contains the following fields:

Full Integration Example#

This example shows a complete integration with RevenueCat, including attribution resolution, user ID linking, and advanced matching after signup:

import 'package:flutter/material.dart';
import 'package:apprefer_flutter_sdk/apprefer_flutter_sdk.dart';
import 'package:purchases_flutter/purchases_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Initialize AppRefer
  final attribution = await AppReferSDK.configure(AppReferConfig(
    apiKey: 'pk_live_your_key_here',
  ));

  // 2. Initialize RevenueCat
  await Purchases.configure(
    PurchasesConfiguration('your_revenuecat_api_key'),
  );

  // 3. CRITICAL: Link AppRefer device ID to RevenueCat
  //    This is REQUIRED for purchase attribution via webhooks
  await Purchases.shared.setAttributes({"appreferId": attribution.deviceId});

  // 4. Optional: Link RevenueCat user ID to AppRefer
  final customerInfo = await Purchases.getCustomerInfo();
  await AppReferSDK.setUserId(customerInfo.originalAppUserId);

  runApp(const MyApp());
}

// Later, after user signs up...
Future<void> onUserSignup(String email, String firstName) async {
  // 5. Send advanced matching data (hashed on-device)
  await AppReferSDK.setAdvancedMatching(
    email: email,
    firstName: firstName,
  );

  // 6. Track the signup event
  await AppReferSDK.trackEvent('signup');
}

Best Practices#

• Call configure() as early as possible in the app lifecycle (before runApp()). The sooner you call it, the more accurate the attribution window.
• Always set appreferId on RevenueCat immediately after configure(). This is the primary mechanism for matching RevenueCat purchase webhooks back to AppRefer attributions. Without it, purchases cannot be attributed.
• Optionally call setUserId() with the RevenueCat user ID for additional matching. This supplements appreferId but is not a replacement for it.
• Call setAdvancedMatching() after the user signs up or logs in. More matching data means higher match rates on Meta and other networks.
• Use pk_test_ keys during development. Sandbox events are completely isolated from production and never forwarded to ad networks.
• Enable debug: true in development to see verbose logs. Disable it in production.

Requirements#