Quickstart

From an empty dashboard to your first attributed install, on iOS, Android, Flutter or React Native.

You need an AppRefer account and an app you can build. Each step below shows all four SDKs; pick your platform's tab. The full references are iOS, Android, Flutter and React Native.

Working with an AI coding agent?

Agents can create the app, tracking links and integrations for you through AppRefer's MCP server and REST API. See AI agents and MCP, then come back for the in-app steps (install and configure).

1. Create an app and copy its key

In the dashboard, add your app (its App Store and Google Play links help AppRefer route clicks and show store details). Its SDK keys are on the app's Settings page, where you can also copy or rotate them. Each app has two:

pk_live_… for release builds: real attribution, events forwarded to your ad networks.
pk_test_… for development: sandbox data, shown in the Debugger's sandbox view and never forwarded.

SDK keys are public by design (they ship inside your app). Keep organisation API keys (ak_…) on your server.

2. Install the SDK

// Xcode: File > Add Package Dependencies…
// https://github.com/AppAgentic/apprefer-ios-sdk  (from 0.11.0, product "AppRefer")

// or Package.swift
.package(url: "https://github.com/AppAgentic/apprefer-ios-sdk", from: "0.11.0")

iOS (including Flutter and React Native) needs iOS 15 or later. Expo apps need a development build.

3. Configure at launch

Call configure once, as early as possible. The first launch resolves attribution; later launches return the cached result. It never throws.

import AppRefer

@main
struct MyApp: App {
    init() {
        Task { await AppRefer.configure(apiKey: "pk_test_...") }
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

When someone signs in, call setUserId with your app's user id so Support and product events carry the account.

iOS privacy manifest

Declare only trk.apprefer.com under NSPrivacyTrackingDomains in PrivacyInfo.xcprivacy. Never add apprefer.com: it carries the first-party requests (analytics, Billing, Support) that must keep working when a user doesn't allow tracking. The SDK reads App Tracking Transparency but never shows the prompt; if your app shows it, call trackingConsentDidChange() afterwards. On Android, pass your consent flow's answer to setTrackingConsent.

4. Create a tracking link

In the dashboard, open your app's Links page and create a link for each campaign: pick the network and name it. Use the generated URL as the ad's destination. It records the click (with the network's click id) and sends the user to the right store.

Meta, TikTok and most networks: https://apprefer.com/api/c/<linkId>
Google Ads: https://apprefer.com/g/<linkId>, a landing page with store buttons that Google accepts as a final URL
ChatGPT Ads: https://apprefer.com/o/<linkId>

Store page overrides, custom product pages and UTM handling are in Tracking links.

5. Connect your ad networks

Under Settings → Integrations, connect each network you want conversions sent to (Meta, Google Ads, TikTok, ChatGPT Ads). On iOS, Apple Ads installs are matched through AdServices, with no setup. Each guide lists exactly what to paste: Integrations.

6. Check it in the Debugger

Run a build with the pk_test_ key and open the Debugger with the sandbox view on. The configure call and its attribution appear within seconds; tracked events follow. To test a real match, tap your tracking link on the device first, then install and open the app. Switch to pk_live_ for release.

7. Optional: subscriptions with AppRefer Billing

AppRefer Billing handles App Store, Google Play and Stripe subscriptions itself: it verifies purchases, keeps entitlements and sends each conversion to your ad networks from the same attribution. Turn it on for the app first (store credentials and products), as described in Billing; paywall setup is in Offerings.

AppReferBilling.configure(entitlementsByProduct: ["pro_yearly": ["premium"]])

let offering = try await AppReferBilling.offerings().currentOffering(forPlacement: "onboarding")
if let annual = offering?.annual {
    _ = try await AppReferBilling.purchase(package: annual)
}
let premium = await AppReferBilling.customerInfo().entitlements["premium"]?.isActive == true

When a user signs in or out, also call Billing's logIn / logOut. Already on RevenueCat? Keep it running and send its webhook to AppRefer (RevenueCat), or move over without a data export as the Billing page explains.

8. Optional: in-app Support

A help chat your team answers from the AppRefer inbox, with reply notifications, a help centre and an optional AI assistant. Set it up in Support, then open it from a Help button:

AppRefer.support.open()

Next steps

Track the moments that matter with trackEvent: Events.
Understand how installs are matched: Attribution.
Handle consent and account switching (setCollectionEnabled, reset()): see your platform's SDK page and Privacy.
Automate setup and reporting: REST API and AI agents and MCP.

Check an install from your terminal (test key)Terminal

curl -X POST https://apprefer.com/api/track/configure \
  -H "Content-Type: application/json" \
  -H "X-AppRefer-Key: pk_test_..." \
  -d '{"device_id": "quickstart-test-001"}'