### Retrieve Install Referrer Details

Source: https://context7.com/lschmierer/android_play_install_referrer/llms.txt

Use this static async getter to open a connection to the Play Store Install Referrer service and get all attribution data for the current install. The connection is established only once; subsequent calls return the cached result. Throws a PlatformException on iOS or if the Play Store service is unavailable.

```dart
import 'package:android_play_install_referrer/android_play_install_referrer.dart';

Future<void> fetchReferrer() async {
  try {
    final ReferrerDetails details = await AndroidPlayInstallReferrer.installReferrer;

    // The raw referrer string from the Play Store link (URL-decoded)
    // e.g. "utm_source=google&utm_medium=cpc&utm_campaign=brand"
    print('Install referrer: ${details.installReferrer}');

    // Client-side timestamp (seconds since epoch) when the user clicked the referral link
    print('Referrer click (client): ${details.referrerClickTimestampSeconds}');

    // Client-side timestamp (seconds since epoch) when the installation began
    print('Install begin (client):  ${details.installBeginTimestampSeconds}');

    // Server-side timestamps for higher attribution accuracy
    print('Referrer click (server): ${details.referrerClickTimestampServerSeconds}');
    print('Install begin (server):  ${details.installBeginTimestampServerSeconds}');

    // App version string at the time of first install (may be null)
    print('Install version: ${details.installVersion}');

    // True if the app's Google Play Instant experience was used within the last 7 days
    print('Instant param: ${details.googlePlayInstantParam}');
  } on PlatformException catch (e) {
    // Common error codes:
    //   SERVICE_DISCONNECTED  – Play Store not connected (transient)
    //   SERVICE_UNAVAILABLE   – Connection couldn't be established
    //   FEATURE_NOT_SUPPORTED – API not available on this Play Store version
    //   DEVELOPER_ERROR       – Incorrect usage / general error
    //   PERMISSION_ERROR      – App not allowed to bind to the service
    print('Error ${e.code}: ${e.message}');
  }
}
```

--------------------------------

### Get Install Referrer Details

Source: https://github.com/lschmierer/android_play_install_referrer/blob/master/README.md

Use this snippet to retrieve the install referrer details from Google Play. Ensure Google Play Services are available on the Android device.

```Dart
ReferrerDetails referrerDetails = await AndroidPlayInstallReferrer.installReferrer;
```

--------------------------------

### Add android_play_install_referrer to pubspec.yaml

Source: https://context7.com/lschmierer/android_play_install_referrer/llms.txt

Add the package to your Flutter project's pubspec.yaml file and run flutter pub get to install it.

```yaml
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  android_play_install_referrer: ^0.4.0
```

```bash
flutter pub get
```

--------------------------------

### AndroidPlayInstallReferrer.installReferrer

Source: https://context7.com/lschmierer/android_play_install_referrer/llms.txt

Retrieves install referrer details from the Google Play Store. This is the primary entry point for the plugin. It establishes a connection to the Install Referrer service only once and caches the result for subsequent calls. Throws a PlatformException if the service is unavailable or on iOS.

```APIDOC
## AndroidPlayInstallReferrer.installReferrer 

### Description
Retrieves install referrer details from the Google Play Store. This is the primary entry point for the plugin. It establishes a connection to the Install Referrer service only once and caches the result for subsequent calls. Throws a PlatformException if the service is unavailable or on iOS.

### Method
`static Future<ReferrerDetails> get installReferrer`

### Parameters
None

### Response
#### Success Response
- **ReferrerDetails** (object) - An object containing install attribution data.
  - **installReferrer** (string) - The raw referrer string (URL-decoded).
  - **referrerClickTimestampSeconds** (int) - Client-side timestamp (seconds since epoch) when the referral link was clicked.
  - **installBeginTimestampSeconds** (int) - Client-side timestamp (seconds since epoch) when the installation began.
  - **referrerClickTimestampServerSeconds** (int) - Server-side timestamp for referrer click.
  - **installBeginTimestampServerSeconds** (int) - Server-side timestamp for install begin.
  - **installVersion** (string?) - The app version string at the time of first install (may be null).
  - **googlePlayInstantParam** (bool) - True if the app's Google Play Instant experience was used within the last 7 days.

#### Error Response
- **PlatformException** - Thrown on iOS or if the Play Store service is unavailable. Common error codes include `SERVICE_DISCONNECTED`, `SERVICE_UNAVAILABLE`, `FEATURE_NOT_SUPPORTED`, `DEVELOPER_ERROR`, `PERMISSION_ERROR`.

### Request Example
```dart
import 'package:android_play_install_referrer/android_play_install_referrer.dart';

Future<void> fetchReferrer() async {
  try {
    final ReferrerDetails details = await AndroidPlayInstallReferrer.installReferrer;
    print('Install referrer: ${details.installReferrer}');
    print('Referrer click (client): ${details.referrerClickTimestampSeconds}');
    print('Install begin (client):  ${details.installBeginTimestampSeconds}');
    print('Referrer click (server): ${details.referrerClickTimestampServerSeconds}');
    print('Install begin (server):  ${details.installBeginTimestampServerSeconds}');
    print('Install version: ${details.installVersion}');
    print('Instant param: ${details.googlePlayInstantParam}');
  } on PlatformException catch (e) {
    print('Error ${e.code}: ${e.message}');
  }
}
```
```

--------------------------------

### Example Google Play Store Link with Referrer Data

Source: https://github.com/lschmierer/android_play_install_referrer/blob/master/README.md

Illustrates how to construct a Google Play Store link that includes custom referrer data. Replace 'com.example.myapp' with your application's ID. The '%3D' is the URL-encoded representation of '='.

```https
https://play.google.com/store/apps/details?id=com.example.myapp&referrer=someKey%3DsomeValue
```

--------------------------------

### URL Encoding Example for Referrer Data

Source: https://github.com/lschmierer/android_play_install_referrer/blob/master/README.md

Shows a custom key-value pair encoded for use in a referrer URL. '%3D' represents the '=' character.

```text
someKey%3DsomeValue
```

--------------------------------

### Build Google Play Store Referral Link

Source: https://context7.com/lschmierer/android_play_install_referrer/llms.txt

Constructs a Google Play Store referral URL, encoding attribution parameters into a single `referrer` query parameter. Special characters within the referrer value must be URL-encoded.

```dart
String buildPlayStoreReferralLink({
  required String appId,
  required Map<String, String> referrerParams,
}) {
  // Inner referrer value: "utm_source=google&utm_campaign=brand"
  final referrerValue = referrerParams.entries
      .map((e) => '${Uri.encodeComponent(e.key)}=${Uri.encodeComponent(e.value)}')
      .join('%26'); // & encoded as %26 inside the outer URL

  return 'https://play.google.com/store/apps/details'
         '?id=$appId'
         '&referrer=$referrerValue';
}

void main() {
  final link = buildPlayStoreReferralLink(
    appId: 'com.example.myapp',
    referrerParams: {
      'utm_source':   'newsletter',
      'utm_medium':   'email',
      'utm_campaign': 'launch_2024',
    },
  );

  print(link);
  // https://play.google.com/store/apps/details?id=com.example.myapp
  //   &referrer=utm_source%3Dnewsletter%26utm_medium%3Demail%26utm_campaign%3Dlaunch_2024
}
```

--------------------------------

### Integrate Referrer Fetching in Flutter Widget

Source: https://context7.com/lschmierer/android_play_install_referrer/llms.txt

Fetches referrer data during widget initialization and updates the widget's state with the result. Handles potential PlatformExceptions if the referrer is unavailable.

```dart
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:android_play_install_referrer/android_play_install_referrer.dart';

class ReferrerWidget extends StatefulWidget {
  const ReferrerWidget({super.key});

  @override
  State<ReferrerWidget> createState() => _ReferrerWidgetState();
}

class _ReferrerWidgetState extends State<ReferrerWidget> {
  String _status = 'Loading...';

  @override
  void initState() {
    super.initState();
    _loadReferrer();
  }

  Future<void> _loadReferrer() async {
    String result;
    try {
      final details = await AndroidPlayInstallReferrer.installReferrer;
      final params  = Uri.splitQueryString(details.installReferrer ?? '');
      result = 'Source: ${params['utm_source'] ?? 'organic'}\n'
               'Campaign: ${params['utm_campaign'] ?? 'none'}\n'
               'Instant: ${details.googlePlayInstantParam}';
    } on PlatformException catch (e) {
      result = 'Unavailable (${e.code})';
    }

    if (!mounted) return;
    setState(() => _status = result);
  }

  @override
  Widget build(BuildContext context) {
    return Text(_status);
  }
}
```

--------------------------------

### Parse Referrer Parameters

Source: https://context7.com/lschmierer/android_play_install_referrer/llms.txt

Parses a custom key=value referrer string from Play Store link and converts server-side click timestamp to DateTime. Assumes the Play Store link was: https://play.google.com/store/apps/details?id=com.example.app&referrer=campaign%3Dsummer%26source%3Demail.

```dart
import 'package:android_play_install_referrer/android_play_install_referrer.dart';

// Parse a custom key=value referrer string
// Assuming the Play Store link was:
// https://play.google.com/store/apps/details?id=com.example.app&referrer=campaign%3Dsummer%26source%3Demail
Future<void> parseReferrerParams() async {
  final ReferrerDetails details = await AndroidPlayInstallReferrer.installReferrer;

  final String? rawReferrer = details.installReferrer; // "campaign=summer&source=email"

  if (rawReferrer != null) {
    final Map<String, String> params = Uri.splitQueryString(rawReferrer);
    final String campaign = params['campaign'] ?? 'unknown';
    final String source   = params['source']   ?? 'unknown';

    print('Campaign: $campaign'); // Campaign: summer
    print('Source:   $source');   // Source:   email
  }

  // Convert server-side click timestamp to DateTime
  final clickTime = DateTime.fromMillisecondsSinceEpoch(
    details.referrerClickTimestampServerSeconds * 1000,
  );
  print('User clicked referral at: $clickTime');

  // Use equality and toString() built into ReferrerDetails
  print(details.toString());
  // ReferrerDetails { installReferrer: campaign=summer&source=email,
  //   referrerClickTimestampSeconds: 1700000000,
  //   installBeginTimestampSeconds: 1700000005,
  //   googlePlayInstantParam: false }
}
```

--------------------------------

### Unit Test Referrer Logic with Mock MethodChannel

Source: https://context7.com/lschmierer/android_play_install_referrer/llms.txt

Mocks the `MethodChannel` to test referrer-dependent logic without a real device or Play Store connection. Ensures all `ReferrerDetails` fields are parsed correctly.

```dart
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:android_play_install_referrer/android_play_install_referrer.dart';

void main() {
  const channel = MethodChannel('de.lschmierer.android_play_install_referrer');
  TestWidgetsFlutterBinding.ensureInitialized();

  setUp(() {
    channel.setMockMethodCallHandler((MethodCall call) async {
      if (call.method == 'getInstallReferrer') {
        return {
          'installReferrer':                    'utm_source=test&utm_campaign=ci',
          'referrerClickTimestampSeconds':       1700000000,
          'installBeginTimestampSeconds':        1700000005,
          'referrerClickTimestampServerSeconds': 1700000001,
          'installBeginTimestampServerSeconds':  1700000006,
          'installVersion':                      '1.0.0',
          'googlePlayInstantParam':              false,
        };
      }
      return null;
    });
  });

  tearDown(() => channel.setMockMethodCallHandler(null));

  test('parses all ReferrerDetails fields correctly', () async {
    final details = await AndroidPlayInstallReferrer.installReferrer;

    expect(details.installReferrer,                    'utm_source=test&utm_campaign=ci');
    expect(details.referrerClickTimestampSeconds,       1700000000);
    expect(details.installBeginTimestampSeconds,        1700000005);
    expect(details.referrerClickTimestampServerSeconds, 1700000001);
    expect(details.installBeginTimestampServerSeconds,  1700000006);
    expect(details.installVersion,                      '1.0.0');
    expect(details.googlePlayInstantParam,              false);
  });
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.