A connection you can build on.

01 / YOUR WORKSPACE

Give your app a home.

Create an account, then a workspace and application in the developer dashboard. Enter your app’s canonical store destinations. Create an affiliate, assign a commission rate, and generate a tracking link.

02 / INSTALL

Build the React Native package.

Start from a checkout of the Relay Track repository. The compatibility baseline is Expo 54, React Native 0.81, and React 19.1. Bare React Native apps must install Expo modules first.

1# From the Relay Track repository
2cd sdk/react-native
3npm ci
4npm pack
5
6# In your Expo 54 / React Native 0.81 app
7npx expo install expo-crypto @react-native-async-storage/async-storage
8npm install /path/to/relay-track-react-native-0.1.0.tgz
9npx expo run:android

Replace the archive path with the file produced by npm pack. Expo supplies the expo-modules-core peer. The native Android bridge requires a new native build; Expo Go and over-the-air JavaScript updates cannot install it.

For iOS, follow your host app’s CocoaPods/prebuild workflow. Installation reporting and eligible direct-link evidence are supported. User-mediated referral paste is available in source; configure the dedicated HTTPS domain and native Paste control in dashboard Setup, then validate on a physical iPhone.

03 / PUBLIC APP CONFIGURATION

Initialize once. Keep the evidence.

Copy the public application UUID from Developer setup in your dashboard. Replace the example API origin with your reachable HTTPS backend. Initialize the SDK at app startup.

1import { RelayTrack } from '@relay-track/react-native';
2
3await RelayTrack.initialize({
4  applicationId: 'YOUR_PUBLIC_APPLICATION_UUID',
5  apiBaseUrl: 'https://YOUR_API_HOST',
6  allowedLinkUrls: [], // Android referrer still enabled
7});
8
9const installationId = await RelayTrack.getInstallationId();
10const attribution = await RelayTrack.getAttribution();

The SDK persists an application-local installation ID and pending evidence, with bounded delivery retries. Read attribution after initialization; an unresolved result is not permission to invent a referral.

Native and Flutter source previews.

Choose one SDK engine per app installation. Swift and Kotlin have their own durable storage; switching from React Native does not migrate its installation identity. Flutter uses the native engines and has no Dart attribution engine.

1In Xcode, choose Add Package Dependencies → Add Local.
2Select relay-track/sdk/swift and link the RelayTrack product.
3No React Native or Expo dependency.

1import RelayTrack
2
3let config = try RelayConfiguration(
4    applicationID: "YOUR_PUBLIC_APPLICATION_UUID",
5    apiBaseURL: "https://YOUR_API_HOST",
6    iosLinkOrigin: "https://YOUR_PUBLIC_APPLICATION_UUID.YOUR_LINK_DOMAIN"
7)
8try await RelayTrack.shared.initialize(config)
9let attribution = try await RelayTrack.shared.attribution()
10try await RelayTrack.shared.retryPending()
11// Forward cold/warm links and scene lifecycle; see the package README.

1// settings.gradle.kts — source integration
2include(":relay-track")
3project(":relay-track").projectDir = file("../relay-track/sdk/kotlin/relay-track")
4
5// app/build.gradle.kts
6// Use the documented compatible AGP/Kotlin plugins and Java 17.
7dependencies {
8    implementation(project(":relay-track"))
9    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
10}
11// Enable core library desugaring in android.compileOptions.

1import com.relaytrack.sdk.RelayTrack
2import com.relaytrack.sdk.RelayConfiguration
3
4// Inside a host coroutine:
5RelayTrack.initialize(applicationContext, RelayConfiguration(
6    applicationId = "YOUR_PUBLIC_APPLICATION_UUID",
7    apiBaseUrl = "https://YOUR_API_HOST"
8))
9val attribution = RelayTrack.getAttribution()
10RelayTrack.retryPending()
11// Forward Activity lifecycle with setActive; Play Referrer is native.

1# pubspec.yaml — local source dependency
2dependencies:
3  relay_track:
4    path: ../relay-track/sdk/flutter
5
6# The local iOS example uses CocoaPods:
7flutter:
8  config:
9    enable-swift-package-manager: false
10# Follow the README for iOS 15.1 and Android desugaring setup.

1import 'package:relay_track/relay_track.dart';
2
3await RelayTrack.initialize(const RelayConfiguration(
4  applicationId: 'YOUR_PUBLIC_APPLICATION_UUID',
5  apiBaseUrl: 'https://YOUR_API_HOST',
6  iosLinkOrigin: 'https://YOUR_PUBLIC_APPLICATION_UUID.YOUR_LINK_DOMAIN',
7));
8final attribution = await RelayTrack.getAttribution();
9await RelayTrack.retryPending();
10// iOS: offer RelayReferralPasteButton after initialization.
11// Forward host lifecycle and incoming links; see the example.

04 / THE SERVER BOUNDARY

Bind identities you have verified.

Send the installation UUID to your own authenticated backend. Your server must verify its user and that installation’s association with the session before calling Relay Track. Arbitrary user or billing customer IDs from a device are not proof of ownership.

Create a host-server credential in API keys. Keep it in your server’s secret storage, separate from webhook authorization. These are server HTTP contracts, not mobile SDK calls.

1// Run on your trusted server after authenticating your user.
2// Never send HOST_SERVER_SECRET to your mobile app.
3POST /v1/applications/{application_id}/identity-bindings
4Authorization: Bearer <HOST_SERVER_SECRET>
5Content-Type: application/json
6
7{
8  "install_id": "<verified installation UUID>",
9  "external_user_id": "<authenticated user ID>"
10}

Assign or verify the RevenueCat App User ID on your server. Bind it to the same authenticated host user, then configure RevenueCat in the app with that verified customer identity.

1POST /v1/applications/{application_id}/billing-identities
2Authorization: Bearer <HOST_SERVER_SECRET>
3Content-Type: application/json
4
5{
6  "provider": "revenuecat",
7  "external_user_id": "<same authenticated user ID>",
8  "provider_customer_id": "<server-assigned RevenueCat App User ID>"
9}

05 / SUBSCRIPTION EVENTS

Connect the existing billing flow.

1. In Integrations, configure the RevenueCat app ID and accepted environment. This provider mapping is fixed after setup; select the correct app.
2. Create a separate RevenueCat webhook credential in API keys and save the reveal-once value securely.
3. In RevenueCat, configure the webhook URL shown by Relay Track and its Authorization header: Bearer <webhook credential>. Match the configured environment.
4. Continue using RevenueCat for offerings, purchases and entitlements. Relay Track handles eligible received financial events and affiliate accruals.

Initial purchases and renewals create distinct transactions. Supported full refunds add immutable offsets at the original commission rate. Ordinary cancellation and expiration do not trigger refunds or reverse commissions.

HTTP receipt means durable acceptance, not proof of completed financial processing. Inspect observed integration activity and reports; missing identity can defer processing. Events that never reach Relay Track cannot appear as received revenue.

06 / VERIFY THE CONNECTION

Test a real acquisition path.

1. Use an enrolled Google Play tester with your app available on its testing track. Begin before installing the app.
2. On the Android phone, open the affiliate link, follow its redirect to Google Play, and install from that redirected listing.
3. Launch and initialize with the correct public application ID and HTTPS origin. Confirm the attribution result and installation identity.
4. Authenticate your app user and complete both authorized server bindings. With Google license testing configured, make an actual sandbox purchase through RevenueCat.
5. Check provider webhook delivery, then sandbox transactions and commissions in your dashboard. Verify the original affiliate, revenue, currency, and applied rate.

Do not sideload, inject referrer data, or manually handle a link as a substitute for real Play acceptance. Keep sandbox and production reports separate. For deferred or failed received events, use protected operator inspection/replay; no automated payout or unattended recovery SLA is implied.