> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partnero.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mobile app integration
> Integrate Partnero affiliate and refer-a-friend tracking into iOS, Android, React Native, and Flutter mobile apps using the REST API.
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](https://help.partnero.com) 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:
1. A partner or customer shares a referral link (e.g., `yoursite.com?ref=PARTNER_KEY`)
2. Someone taps the link on their phone
3. Your app opens via a deep link and extracts the referral key from the URL
4. When the user signs up, your app sends the referral key to your backend
5. Your backend calls the Partnero API to create the customer with the referral attribution
6. 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:
1. Add an `apple-app-site-association` file to your domain's `.well-known` directory.
2. Configure Associated Domains in Xcode (`applinks:yoursite.com`).
3. Handle incoming URLs in `SceneDelegate` or `AppDelegate`.
Apple documentation: [Supporting universal links](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app)
1. Add intent filters to your `AndroidManifest.xml` for your domain.
2. Host a Digital Asset Links JSON file at `yoursite.com/.well-known/assetlinks.json`.
3. Handle incoming intents in your activity.
Android documentation: [Verify Android app links](https://developer.android.com/training/app-links/verify-android-applinks)
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`).
```swift theme={null}
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")
}
}
```
```kotlin theme={null}
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()
}
}
}
```
```javascript theme={null}
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);
}
});
```
```dart theme={null}
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.
## Step 2: Send the referral key during sign-up
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:
```json theme={null}
{
"email": "user@example.com",
"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:
Use `partner.key` to attribute the customer to the referring partner:
```bash theme={null}
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": "user@example.com",
"name": "John"
}'
```
Use `referring_customer.key` to link the new customer to the referrer:
```bash theme={null}
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": "user@example.com",
"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:
```bash theme={null}
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](https://help.partnero.com), 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:
### Referral link and share stats
Use [GET /v1/customers/{id}/stats](/api-reference/refer-a-friend/customers#get-customer-stats) to get the customer's referral link, click count, and social sharing links:
```bash theme={null}
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/{id}/balance](/api-reference/refer-a-friend/customers#get-customer-balance) to show how much the user has earned from referrals:
```bash theme={null}
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/{id}/referrals](/api-reference/refer-a-friend/customers#get-customer-referrals) to show who the user has referred:
```bash theme={null}
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
## Next steps
Full REST API documentation
Get notified when referrals convert