@capgo/capacitor-install-referrer

Capacitor plugin for install attribution. Android reads Google Play Install Referrer, and iOS uses Apple AdServices attribution tokens with optional Apple Search Ads attribution lookup.

Compatible with Capacitor 8.

Platform behavior

• Android returns the Play install referrer string, click timestamp, install timestamp, and instant experience flag.
• iOS returns an AdServices attribution token. Set fetchAppleAttribution to true to ask Apple for the attribution payload directly from native code.
• iOS does not provide a generic App Store install referrer equivalent to Google Play. Apple AdServices covers Apple Search Ads attribution.
• Web is unavailable and rejects the call.

Install

bun add @capgo/capacitor-install-referrer
bunx cap sync

Usage

import { InstallReferrer } from '@capgo/capacitor-install-referrer';

const result = await InstallReferrer.getReferrer();

if (result.platform === 'android') {
  console.log(result.referrer);
}

if (result.platform === 'ios') {
  console.log(result.attributionToken);
}

Fetch the Apple attribution payload from iOS native code:

const result = await InstallReferrer.getReferrer({
  fetchAppleAttribution: true,
  appleAttributionRetryCount: 3,
  appleAttributionRetryDelayMs: 5000,
});

console.log(result.appleAttribution);

GetReferrer() is also available as a deprecated compatibility alias for apps migrating from cap-play-install-referrer.

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.. | v8.. | Yes | | v7.. | v7.. | On demand | | v6.. | v6.. | No |

API

• getReferrer(...)
• GetReferrer(...)
• getPluginVersion()
• Interfaces

Base API for retrieving install referrer and attribution details.

getReferrer(...)

getReferrer(options?: GetReferrerOptions | undefined) => Promise<GetReferrerResult>

Returns native install attribution details.

Android reads the Google Play Install Referrer API. iOS returns an Apple AdServices attribution token and can optionally fetch Apple's attribution payload.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | GetReferrerOptions |

Returns: Promise<GetReferrerResult>

Since: 8.0.0

GetReferrer(...)

GetReferrer(options?: GetReferrerOptions | undefined) => Promise<GetReferrerResult>

Backward-compatible alias for plugins inspired by cap-play-install-referrer.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | GetReferrerOptions |

Returns: Promise<GetReferrerResult>

Since: 8.0.0

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Interfaces

GetReferrerResult

Install referrer and attribution details returned by the native platform.

| Prop | Type | Description | Since | | ---------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----- | | platform | string | Platform that produced the result. Android returns android; iOS returns ios. | 8.0.0 | | referrer | string | Android only. Raw Google Play install referrer string. | 8.0.0 | | clickTimestampSeconds | number | Android only. Client-side click timestamp in seconds. | 8.0.0 | | installBeginTimestampSeconds | number | Android only. Client-side install begin timestamp in seconds. | 8.0.0 | | googlePlayInstantParam | boolean | Android only. True when the user launched your app's instant experience. | 8.0.0 | | attributionToken | string | iOS only. Apple AdServices attribution token. Send this token to your backend, MMP, or Apple's AdServices API within its TTL. | 8.0.0 | | appleAttribution | AppleAttributionRecord | iOS only. Apple AdServices attribution payload when fetchAppleAttribution is true. | 8.0.0 |

AppleAttributionRecord

Install attribution values returned by Apple AdServices.

Apple may add fields over time, so unknown keys are preserved.

| Prop | Type | Description | Since | | ----------------- | -------------------- | --------------------------------------------------------------------- | ----- | | attribution | boolean | True when Apple found a matching Apple Search Ads attribution record. | 8.0.0 |

GetReferrerOptions

Options for reading install attribution.

| Prop | Type | Description | Default | Since | | ---------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | fetchAppleAttribution | boolean | iOS only. When true, the plugin sends the AdServices attribution token to Apple and returns the attribution payload in appleAttribution. Leave this false when you want to send attributionToken to your own backend or MMP. | false | 8.0.0 | | appleAttributionRetryCount | number | iOS only. Number of times to retry Apple's attribution endpoint after a 404 response. Apple can return 404 when the token is valid but attribution data is not ready yet. | 3 | 8.0.0 | | appleAttributionRetryDelayMs | number | iOS only. Delay between Apple attribution retries, in milliseconds. | 5000 | 8.0.0 |

PluginVersionResult

Plugin version payload.

| Prop | Type | Description | | ------------- | ------------------- | ----------------------------------------------------------- | | version | string | Version identifier returned by the platform implementation. |