Flutter Play Install Referrer

A minimal, clean, production-ready Flutter plugin to securely fetch Google Play Install Referrer details using native Kotlin.

This plugin connects directly to the official Google Play Store Install Referrer API and exposes the attribution data to Flutter via MethodChannel. It is designed to be lightweight, straightforward, and secure.

---

Features

• ⚡ Lightweight & Minimal: Exposes a single, straightforward API to fetch referrer details without extra bloat.
• 🔌 Native Connection Teardown: Ensures Google Play connection is safely closed after every query, preventing background resource leaks.
• ⚙️ Robust Error Handling: Seamlessly maps native connection codes (like FEATURE_NOT_SUPPORTED or SERVICE_UNAVAILABLE) into descriptive Dart exceptions.

---

Installation

Add this package to your pubspec.yaml dependencies:

dependencies:
  flutter_play_install_referrer:
    path: /path/to/flutter_play_install_referrer # Or from pub.dev when published

Then fetch dependencies in your project:

flutter pub get

---

Setup

No complex native configuration is required! The plugin handles all platform bindings automatically.

Android Setup

In your Android project, the dependency to the official Google Play Install Referrer Client library is managed by the plugin's build.gradle:

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

Make sure your target device has Google Play Services and the Google Play Store installed.

---

Usage

Simple Usage Example

Import the plugin in your Dart file:

import 'package:flutter_play_install_referrer/flutter_play_install_referrer.dart';

Retrieve the referrer details:

try {
  // Fetch install referrer details
  final details = await PlayInstallReferrer.getInstallReferrer();

  print('Referrer String: ${details.installReferrer}');
  print('Click Timestamp: ${details.referrerClickTimestampSeconds} sec');
  print('Install Timestamp: ${details.installBeginTimestampSeconds} sec');
} catch (e) {
  print('Error fetching referrer details: $e');
}

---

API Reference

PlayInstallReferrer Class

static Future<ReferrerDetails> getInstallReferrer()

Fetches the install referrer details from the Google Play Store client.

---

ReferrerDetails Model

class ReferrerDetails {
  /// The raw referrer parameter string from Google Play Store (e.g., utm_source%3Dtest)
  final String? installReferrer;

  /// Timestamp in seconds when the referral click occurred
  final int? referrerClickTimestampSeconds;

  /// Timestamp in seconds when the app installation began
  final int? installBeginTimestampSeconds;
}

---

Play Store Testing Steps

The Install Referrer data can only be fetched if the app has been downloaded from the Google Play Store.

To test custom referrers during local development:

1. Open the emulator: Ensure the emulator has Google Play Store installed.
2. Prime the Play Store with a test referrer URL: Run the following command from your terminal:

   adb shell am start -a android.intent.action.VIEW -d "https://play.google.com/store/apps/details?id=YOUR_PACKAGE_NAME\&referrer=utm_source%3Dtest_source%26utm_medium%3Dtest_medium%26utm_campaign%3Dtest_campaign"
   

   (Replace YOUR_PACKAGE_NAME with your example application ID, e.g. com.fitelo.flutter_play_install_referrer.flutter_play_install_referrer_example)
3. Keep the Play Store open: Leave the Play Store screen open (do not click install, and do not close it).
4. Run the App: Launch your app directly from your IDE/command line onto the emulator. When you trigger PlayInstallReferrer.getInstallReferrer(), it will fetch the primed referrer values successfully!

---

Limitations

• Store Dependent: Only works for installs initiated through the official Google Play Store client. Side-loaded APKs or debugging builds will not return referrer parameters unless mock values are injected.
• Validity Duration: Referrer details are generally retained by Google Play Services for around 90 days from the app installation date.