flutter_play_install_referrer 1.0.1

A lightweight Flutter plugin to fetch Google Play Install Referrer data using native Kotlin.

Flutter Play Install Referrer

A minimal, production-ready Flutter plugin to fetch Google Play Install Referrer attribution details. This plugin provides a simple Dart interface to the official Google Play Install Referrer API via native Kotlin implementation.

---

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: ^1.0.1

Then run:

flutter pub get

---

Platform Support

Android: ✅ Requires Google Play Services and the official Google Play Store app. iOS: ❌ Not supported (Google Play Install Referrer API is Android-specific).

Requirements

• Minimum Android SDK: API 24
• Target device must have Google Play Store installed
• App must be installed through the official Play Store to retrieve referrer data

---

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;
}

---

Testing

The install referrer is only available for apps installed through the official Google Play Store. For testing:

1. Test with a real device that has the app installed from Google Play Store
2. Or use Play Console's internal testing track to test referrer URLs
3. Sideloaded or debug builds will not have access to referrer data

---

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.