Mobile app integration

If your product is a mobile app (or has a mobile app alongside a website), you can still track referrals with Partnero. Since mobile apps don’t have browser cookies, you handle referral attribution through deep links and the REST API instead of the PartneroJS SDK.

Before proceeding, you should have a program created on Partnero. If you haven’t created one yet, refer to the Knowledge Base for guidance.

How mobile referral tracking works

In a web integration, PartneroJS reads the referral key from the URL and stores it in a cookie. In a mobile app, your code does the same thing manually:

A partner or customer shares a referral link (e.g., yoursite.com?ref=PARTNER_KEY)
Someone taps the link on their phone
Your app opens via a deep link and extracts the referral key from the URL
When the user signs up, your app sends the referral key to your backend
Your backend calls the Partnero API to create the customer with the referral attribution
When the user makes a purchase, your backend records the transaction via the API

Never call the Partnero API directly from the mobile app. Always route API calls through your backend to keep your API key secure.

Prerequisites: Set up deep links

Before your app can receive referral links, configure deep linking so URLs on your domain open your app:

iOS universal links

Add an apple-app-site-association file to your domain’s .well-known directory.
Configure Associated Domains in Xcode (applinks:yoursite.com).
Handle incoming URLs in SceneDelegate or AppDelegate.

Apple documentation: Supporting universal links

Android app links

Add intent filters to your AndroidManifest.xml for your domain.
Host a Digital Asset Links JSON file at yoursite.com/.well-known/assetlinks.json.
Handle incoming intents in your activity.

Android documentation: Verify Android app links

React Native / Flutter

Both iOS and Android native configurations above are still required. Use libraries like react-native-linking (React Native) or app_links (Flutter) to handle incoming URLs in your framework code.

What if the app isn’t installed? The referral link opens your website instead. If PartneroJS is installed on your site, the cookie is set and tracking works normally through the web. Consider adding a smart banner or redirect to the app store so users can install the app without losing the referral.

Step 1: Extract and store the referral key

When your app opens from a referral link, parse the referral key from the URL and store it persistently. The default query parameter is ref, but your program may use a different one (e.g., via).

iOS (Swift)
Android (Kotlin)
React Native
Flutter (Dart)

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard let url = userActivity.webpageURL else { return }
    
    if let components = URLComponents(url: url, resolvingAgainstBaseURL: true),
       let referralKey = components.queryItems?.first(where: { $0.name == "ref" })?.value {
        UserDefaults.standard.set(referralKey, forKey: "partnero_referral_key")
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    
    intent?.data?.let { uri ->
        val referralKey = uri.getQueryParameter("ref")
        if (referralKey != null) {
            getSharedPreferences("partnero", MODE_PRIVATE)
                .edit()
                .putString("referral_key", referralKey)
                .apply()
        }
    }
}

import { Linking } from 'react-native';
import AsyncStorage from '@react-native-async-storage/async-storage';

Linking.addEventListener('url', async (event) => {
  const url = new URL(event.url);
  const referralKey = url.searchParams.get('ref');
  
  if (referralKey) {
    await AsyncStorage.setItem('partnero_referral_key', referralKey);
  }
});

import 'package:app_links/app_links.dart';
import 'package:shared_preferences/shared_preferences.dart';

final appLinks = AppLinks();

appLinks.uriLinkStream.listen((Uri uri) async {
  final referralKey = uri.queryParameters['ref'];
  if (referralKey != null) {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString('partnero_referral_key', referralKey);
  }
});

Use persistent storage (UserDefaults, SharedPreferences, AsyncStorage) so the key survives app restarts. If the user opens the app from a referral link but doesn’t sign up immediately, the key is still available later. When the user creates an account, include the stored referral key in your sign-up request to your backend. Your backend then passes it to the Partnero API. Your app → Your backend: Include the referral key alongside the normal sign-up data your app already sends:

{
  "email": "[email protected]",
  "name": "John",
  "password": "...",
  "referral_key": "PARTNER_KEY_FROM_STORAGE"
}

Your backend → Partnero API: Your backend reads the referral_key from the sign-up request and calls the Partnero API. The field name depends on your program type:

Affiliate program
Refer-a-friend program

Use partner.key to attribute the customer to the referring partner:

curl --location 'https://api.partnero.com/v1/customers' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "partner": {
      "key": "PARTNER_KEY_FROM_SIGNUP"
    },
    "key": "customer_123",
    "email": "[email protected]",
    "name": "John"
  }'

Use referring_customer.key to link the new customer to the referrer:

curl --location 'https://api.partnero.com/v1/customers' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "referring_customer": {
      "key": "REFERRAL_KEY_FROM_SIGNUP"
    },
    "key": "customer_456",
    "email": "[email protected]",
    "name": "John"
  }'

After the customer is created successfully, clear the stored referral key from the app to avoid duplicate attributions.

Partnero ignores requests with an invalid referral key. You can safely send the referral key for every sign-up—only users who arrived via a valid referral link will be attributed.

Step 3: Track transactions

When a user makes a purchase, your backend records the transaction:

curl --location 'https://api.partnero.com/v1/transactions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer": {
      "key": "customer_123"
    },
    "key": "order_789",
    "amount": 49.99,
    "action": "sale"
  }'

If you use Stripe, Paddle, or another supported payment processor, transactions are tracked automatically through Partnero’s integrations—no API call needed for this step.

Step 4: Show referral data in-app (refer-a-friend)

For refer-a-friend programs, you can build an in-app referral screen showing the user their referral link, stats, and rewards. Fetch this data through your backend: Use GET /v1/customers//stats to get the customer’s referral link, click count, and social sharing links:

curl --location 'https://api.partnero.com/v1/customers/customer_123/stats' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Display the referral_link with a “Copy link” or “Share” button in your app.

Reward balance

Use GET /v1/customers//balance to show how much the user has earned from referrals:

curl --location 'https://api.partnero.com/v1/customers/customer_123/balance' \
  --header 'Authorization: Bearer YOUR_API_KEY'

List of referred friends

Use GET /v1/customers//referrals to show who the user has referred:

curl --location 'https://api.partnero.com/v1/customers/customer_123/referrals' \
  --header 'Authorization: Bearer YOUR_API_KEY'

URL formats reference

Your Partnero program may use different URL formats. Make sure your app handles whichever one you’ve configured:

Format	Example URL	How to extract
Query parameter (default)	`yoursite.com?ref=KEY`	Parse `ref` query param
Custom parameter	`yoursite.com?via=KEY`	Parse your custom param name
Path-based	`yoursite.com/KEY`	Parse first path segment

You can find your program’s URL format in Programs → Settings → Referral links in the Partnero dashboard.

Best practices

Use persistent storage for the referral key so it survives app restarts and delayed sign-ups
Always call the Partnero API from your backend to keep your API key out of the mobile app
Install PartneroJS on your website as a fallback for users who don’t have the app installed
Clear the referral key after successful sign-up to prevent duplicate attributions
Test with real devices since deep link behavior varies across iOS and Android versions

Getting started

Tracking integration

No-code solutions

Programs

Webhooks

Mobile app integration

How mobile referral tracking works

Prerequisites: Set up deep links

Step 1: Extract and store the referral key

Step 3: Track transactions

Step 4: Show referral data in-app (refer-a-friend)

Reward balance

List of referred friends

URL formats reference

Best practices

Next steps

API reference

Webhooks

Getting started

Tracking integration

No-code solutions

Programs

Webhooks

Documentation Index

​How mobile referral tracking works

​Prerequisites: Set up deep links

​Step 1: Extract and store the referral key

​Step 2: Send the referral key during sign-up

​Step 3: Track transactions

​Step 4: Show referral data in-app (refer-a-friend)

​Referral link and share stats

​Reward balance

​List of referred friends

​URL formats reference

​Best practices

​Next steps

API reference

Webhooks

How mobile referral tracking works

Prerequisites: Set up deep links

Step 1: Extract and store the referral key

Step 2: Send the referral key during sign-up

Step 3: Track transactions

Step 4: Show referral data in-app (refer-a-friend)

Referral link and share stats

Reward balance

List of referred friends

URL formats reference

Best practices

Next steps