In-app doorverwijzingen

Laat de gebruikers van je app doorverwijzers worden vanuit je app. Met één SDK-aanroep toon je een kant-en-klaar scherm Vriend uitnodigen, geef je elke gebruiker een eigen code en link, en zie je hoeveel vrienden ze hebben binnengebracht, zodat je ze in je app kunt belonen met tegoed, tokens of gratis tijd.

In-app doorverwijzers zijn gewone affiliates. Ze krijgen een login voor het dashboard, verschijnen in je affiliatelijst en kunnen commissie verdienen, in-app beloningen of allebei.

Nieuw met deze functie? De pagina over het doorverwijzingsprogramma voor mobiele apps laat zien wat je gebruikers zien en welke beloningen je kunt aanbieden. Deze handleiding behandelt de installatie.

Hoe het werkt

1. Je app meldt de gebruiker aan. De SDK stuurt het e-mailadres en de naam van de gebruiker. Insert Affiliate maakt hun affiliateaccount aan, hun shortcode en (bij bedrijven met Insert Links) hun link.
2. De gebruiker deelt. Het kant-en-klare scherm toont hun code en link met de knoppen Copy en Share. Delen gebeurt via het eigen deelmenu van de telefoon.
3. Vrienden worden zoals gewoonlijk toegeschreven. Installaties, events en aankopen vanaf het apparaat van de vriend worden aan de doorverwijzer toegeschreven, precies zoals bij elke andere affiliate.
4. Jij beloont ze. De SDK, een webhook en de publieke API rapporteren allemaal een aantal doorverwijzingen. Als dat stijgt, geef je de beloning.

Zo ziet het scherm eruit

Het kant-en-klare scherm Vriend uitnodigen in een live app, van aanmelden, via de code en link van de doorverwijzer met Copy en Share, tot de beloningscodes die ze hebben verdiend:

Instellen in je dashboard

1. Ga naar Instellingen → In-app doorverwijzingen
2. Zet Laat gebruikers vanuit je app doorverwijzer worden aan
3. Kies Wat telt als doorverwijzing:
   • Een vriend doet een aankoop (aanbevolen): telt nieuwe aankopen, geen verlengingen
   • Een vriend voltooit een in-app-event: telt een bijgehouden event zoals signup. Voer de eventnaam in die je app verstuurt.
   • Een vriend installeert de app: telt toegeschreven installaties en keren dat de app wordt geopend. Dit is het makkelijkst te vervalsen, zie hoe veilig de telling is en de regels van de stores.
4. Zet eventueel E-mailcode verplicht stellen voor nieuwe doorverwijzers aan als je app e-mailadressen niet zelf verifieert
5. Stel de Kop, de Knopkleur en de Beloningstekst in die op het kant-en-klare scherm worden getoond. Het voorbeeld werkt bij terwijl je typt.
6. Klik op Doorverwijzingsinstellingen opslaan

Wijzigingen in de teksten en de kleur van het scherm komen direct in je app terecht, zonder dat er een nieuwe release nodig is.

Toevoegen aan je app

Elke SDK heeft dezelfde methodes. De snelste route is het kant-en-klare scherm, dat de aanmelding, de stap met de e-mailcode en het delen voor je afhandelt.

React Native

import { ReferAFriend } from 'insert-affiliate-react-native-sdk';

<ReferAFriend
  visible={showReferral}
  onClose={() => setShowReferral(false)}
  email={currentUser.email}
  name={currentUser.name}
/>

Swift (iOS)

InsertAffiliateSwift.showReferAFriend(
  from: viewController,
  options: ReferAFriendOptions(email: currentUser.email, name: currentUser.name)
)

Flutter, Android (Java/Kotlin), Unity en JavaScript gebruiken dezelfde methodenamen. Bekijk de README van elke SDK voor de exacte syntax: Swift, Android, React Native, Flutter, Unity, JavaScript.

De teksten op het scherm aanpassen

Het scherm wordt geleverd met Engelse tekst. Je app kan elk label op het scherm vervangen met een strings-optie, die je meegeeft wanneer je het scherm opent. Zo vertaal je het scherm, want wij leveren geen vertalingen mee, en zo pas je de formulering aan zodat die klinkt als je app.

<ReferAFriend
  visible={showReferral}
  onClose={() => setShowReferral(false)}
  strings={{
    emailLabel: 'Correo electrónico',
    joinButton: 'Obtener mi enlace',
    codeSentNotice: 'Enviamos un código de 6 dígitos a {email}.',
    shareButton: 'Compartir',
    premiumUntil: 'Premium gratis hasta {date}',
  }}
/>

Regels voor elke SDK:

• Vervang alleen wat je wilt. Een sleutel die je weglaat, of instelt op een lege string, houdt onze Engelse tekst. Een sleutel die we niet kennen, wordt genegeerd.
• Behoud de placeholders. {email} in codeSentNotice en {date} in premiumUntil worden ingevuld wanneer de tekst wordt getoond.
• De kop en de beloningstekst zitten niet in strings. Die komen uit je dashboard, en elke SDK heeft een eigen optie om ze per aanroep te vervangen.

De sleutels die de meeste SDK's gemeen hebben:

Het scherm van elke SDK is een beetje anders, dus elke README bevat de volledige lijst met onze Engelse standaardteksten. De JavaScript SDK splitst copyCodeButton en copyLinkButton en heeft geen kop "Your code", en de SDK's voor Android, Unity, Flutter en React Native voegen sleutels toe voor eigen labels, zoals een aparte titel "Your link" of de placeholdertekst in de velden.

Een foutcode waarvoor we geen sleutel hebben, valt terug op errorServer.

Het scherm stylen

Hetzelfde optie-object bepaalt ook het uiterlijk, per aanroep:

• Kleur: primaryColor, een #RRGGBB-waarde die de knopkleur uit je dashboard vervangt.
• Lettertype: fontName in Swift, fontFamily in React Native, Flutter en JavaScript, font in Unity en setTypeface in Android.
• Hoekradius: cornerRadius voor de knoppen, de velden en het scherm zelf.
• Deeltekst: shareMessage, het bericht waarmee het deelmenu begint.

Je eigen scherm bouwen

Liever je eigen ontwerp? Sla ons scherm over en roep de methodes zelf aan. Ze zijn alles wat het kant-en-klare scherm gebruikt.

Roep ze in deze volgorde aan:

1. getReferralProgramConfig() wanneer je scherm opent. Als het niet aan staat, toon het scherm dan niet.
2. getMyAffiliateDetails() tegelijkertijd. Komen er gegevens terug, dan is dit apparaat al gekoppeld, dus ga direct naar de aangemelde status.
3. Niet aangemeld: vraag een e-mailadres en een naam en roep dan createAffiliateForUser aan. created gaat naar de aangemelde status, verificationRequired gaat naar de stap met de code.
4. Code nodig: vraag de 6-cijferige code en roep verifyAffiliateCode aan. Om een nieuwe code te sturen, roep je createAffiliateForUser opnieuw aan.
5. Aangemeld: toon de shortcode en link, referralCount, totalEarned en currency, en bied kopiëren en delen aan.
6. Beloningen: rewardsGranted en premiumUntil gaan over gratis premiumtijd. rewardCodes bevat storecodes, elk met code, store en redeemUrl. Toon alleen de codes voor de telefoon die de gebruiker gebruikt, want een App Store-code kan niet op Android worden ingewisseld en een Google Play-code niet op iPhone.
7. Fouten: elke fout komt terug als een code, zoals PROGRAM_DISABLED, AFFILIATE_LIMIT_REACHED, INVALID_EMAIL, INVALID_CODE, TOO_MANY_CODES of RATE_LIMITED, zodat je je eigen teksten kunt schrijven.
8. setReferrerAccount wanneer de gebruiker later een abonnement neemt of inlogt, en signOutAffiliate() wanneer ze uitloggen.

Twee dingen om te weten voordat je begint:

• Een ontbrekend resultaat zegt niet waarom. getMyAffiliateDetails() geeft niets terug, zowel wanneer het apparaat niet gekoppeld is als wanneer het verzoek is mislukt. Controleer daarna isUserAnAffiliate() om ze uit elkaar te houden: is dat nog steeds true, dan is het verzoek mislukt en is het de moeite waard om het opnieuw te proberen.
• Een paar hulpfuncties van het scherm zijn intern. Beloningscodes filteren op store, de deeltekst opbouwen en een getypte code opschonen zijn niet openbaar, dus je scherm schrijft die zelf. Het zijn elk een paar regels bovenop wat de methodes al teruggeven, en shareReferralLink regelt de deeltekst.

redeemUrl en dashboardUrl komen van onze server, dus controleer dat elk ervan begint met https:// voordat je ze opent.

Herinstallaties en nieuwe telefoons

Wanneer een gebruiker doorverwijzer wordt, krijgt hun telefoon een privé inlogtoken dat bewijst wie ze zijn. Op iPhone wordt het in de Keychain bewaard, dus meestal blijft het behouden als de app wordt verwijderd en opnieuw wordt geïnstalleerd.

Als het token verloren gaat (een nieuwe telefoon, of een herinstallatie op Android), geeft het opnieuw aanmelden met hetzelfde e-mailadres niet direct toegang. In plaats daarvan:

1. createAffiliateForUser geeft verificationRequired terug en we e-mailen de gebruiker een 6-cijferige code
2. De gebruiker voert die in en je app roept verifyAffiliateCode aan
3. De telefoon is weer gekoppeld. Hun doorverwijzingen, verdiensten en dashboard blijven ongewijzigd.

Het kant-en-klare scherm toont deze stap automatisch. Codes verlopen na 10 minuten en werken niet meer na 5 foute pogingen, en we sturen maximaal 3 codes per uur naar hetzelfde e-mailadres (daarna geeft createAffiliateForUser TOO_MANY_CODES terug). Iedereen die al je affiliate is, inclusief creators met een dashboard, bevestigt altijd een code wanneer ze een nieuwe telefoon koppelen. Dit voorkomt ook dat iemand de doorverwijzingen van een ander kan bekijken door diens e-mailadres in te typen.

Doorverwijzers belonen

Stel dit in via Instellingen → In-app doorverwijzingen → Beloningen voor doorverwijzers. Het geldt voor elke nieuwe doorverwijzer die zich via je app aansluit:

• Commissie in geld: je standaardcommissie, geen geld (alleen beloningen), of een andere commissie alleen voor doorverwijzers.
• Korting voor hun vriend: kies een van je aanbiedingscodes voor iOS, Android en web. Vrienden die de link of code van een doorverwijzer gebruiken, krijgen deze.
• Hun beloning per doorverwijzing: Niets extra (alleen commissie), Gratis premiumtijd, automatisch gegeven of Ik beloon ze zelf.

referralCount telt elke vriend één keer en gaat alleen maar omhoog.

Gratis premiumtijd, automatisch gegeven

We geven de beloning via wat je ook voor aankopen gebruikt, op het moment dat een doorverwijzing telt:

Vertel ons wie de doorverwijzer is in je aankoopsysteem, zodat we het juiste account belonen:

// When they join (RevenueCat app user ID or Adapty customer user ID)
await createAffiliateForUser(email, name, { appUserId: revenueCatAppUserId });

// Or later, e.g. once they subscribe (Android: their Play purchase token)
await setReferrerAccount({ appUserId, playPurchaseToken });

Als er een doorverwijzing binnenkomt voordat je app dit heeft verstuurd, wacht de beloning en wordt die gegeven zodra het binnenkomt.

Stuur op Android het Play-aankooptoken van de doorverwijzer zodra ze een abonnement nemen. Zonder dat token kunnen we niet zien dat ze abonnee zijn, dus krijgen ze in plaats daarvan een promotiecode, en Google laat iemand die eerder een abonnement heeft gehad er geen inwisselen.

App Store-aanbiedingscodes: we maken eenmalige codes voor je aan met je App Store Connect-sleutel. Iemand kan maar één code per aanbieding inwisselen, dus kies je aanbiedingen op volgorde: de 2e beloning van een doorverwijzer komt uit je 2e aanbieding, enzovoort. De aanbieding bepaalt wat ze krijgen, bijvoorbeeld een maand gratis. Elke doorverwijzer kan één App Store-beloning krijgen per aanbieding die je kiest (tot 20 aanbiedingen). Hebben ze ze allemaal gehad, dan worden verdere beloningen als failed getoond, dus kies genoeg aanbiedingen of beloon de rest zelf.

Google Play-promotiecodes: Google biedt ons geen manier om promotiecodes aan te maken, en alleen mensen die nog nooit een abonnement hebben gehad kunnen er een inwisselen. Daarom schuift bij abonnees de factuur op, en krijgen alle anderen een code uit een lijst die je uploadt:

1. Open in Play Console Monetize with Play > Promo codes en maak een promotie met one-time codes voor je abonnement, met een gratis proefperiode van 3 tot 90 dagen. Google staat 10.000 codes per abonnement per kwartaal toe.
2. Download de CSV en upload die in Instellingen > In-app doorverwijzingen, met de einddatum van de promotie. We stoppen 2 dagen daarvoor met het uitdelen van codes.
3. Elke beloning gebruikt de volgende ongebruikte code. Als ze op zijn, wachten beloningen en gaan ze binnen het uur na je volgende upload de deur uit.

Zelf belonen

Hoe veilig is de telling? Dat hangt af van wat je telt:

• Aankopen kunnen niet worden vervalst. Een aankoop telt pas nadat die is geverifieerd tegen het bonnetje van de store via je aankoopverificatie (App Store, Google Play, RevenueCat, Adapty en de rest), precies zoals elke affiliateverkoop. Beloningen op basis van aankopen zijn veilig, inclusief gratis maanden.
• Aanmeldingen en installaties worden door je app gerapporteerd, dus een aangepaste app of gescripte aanroepen kunnen ze vervalsen. Gebruik ze voor kleine extraatjes en tel aankopen voor alles wat waardevol is.

Voor de sterkste setup geef je beloningen vanaf je server. Je backend leest de geverifieerde telling via de webhook of de publieke API, in plaats van te vertrouwen op wat de telefoon laat zien.

Webhook: referral.created

Als je webhooks hebt ingesteld, sturen we referral.created elke keer dat er iets gebeurt dat je als doorverwijzing telt:

{
  "event": "referral.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "short_code": "a1b2c3d4",
  "trigger": "purchase",
  "referral_count": 3,
  "reward_status": "not_automatic",
  "occurred_at": "2026-09-18T12:00:00.000Z"
}

Beloon tot en met referral_count. Omdat het een lopend totaal is, beloon je nooit twee keer, en de volgende levering haalt alles in wat je hebt gemist. Webhooks worden niet opnieuw verstuurd, dus voor het volledige beeld check je de publieke API, die altijd het actuele aantal toont.

reward_status vertelt wat er met onze automatische beloning gebeurde toen de doorverwijzing werd geregistreerd:

• granted: gegeven
• not_automatic: wij geven geen beloning. Je hebt Ik beloon ze zelf gekozen, dus beloon ze nu, of je hebt Niets extra (alleen commissie) gekozen.
• waiting_for_account: we kennen het account van de doorverwijzer in je aankoopsysteem nog niet, of je aankoopsysteem heeft nog geen gegevens van ze. We proberen het elk uur opnieuw, dus dit lost zichzelf op zodra hun account bestaat.
• waiting_for_codes: we wachten tot Apple aanbiedingscodes aanmaakt, of tot jij meer Google Play-promotiecodes uploadt. We proberen het elk uur opnieuw.
• failed: de beloning kon niet worden gegeven, bijvoorbeeld omdat er een sleutel of instelling ontbreekt. De meest voorkomende oorzaken zijn geen ingestelde App Store Connect-sleutel of aanbiedingen (zodat doorverwijzers op iPhone niet beloond kunnen worden), een ontbrekende naam voor de entitlement of het toegangsniveau, en een doorverwijzer die alle aanbiedingen die je hebt ingesteld al heeft gehad.
• capped: boven de maandelijkse limiet, beloon deze niet

Het wordt één keer verstuurd, wanneer de doorverwijzing wordt geregistreerd. Als een wachtende beloning later wordt gegeven, wordt er geen tweede webhook verstuurd.

Publieke API

GET /public/v1/affiliates/{identifier} (het e-mailadres of de shortcode van de affiliate) bevat een referrals-object met trigger (wat je programma telt), referralCount, installCount, eventCount en purchaseCount. De publieke API is beschikbaar op het Enterprise-plan.

Zelfdoorverwijzingen en limieten

• Elke vriend telt één keer. Installaties en events worden gekoppeld aan de telefoon van de vriend, dus een vriend die zich twee keer aanmeldt, is één doorverwijzing. Aankopen worden gekoppeld aan het app-account van de vriend (hun RevenueCat app user ID of Adapty customer user ID). Zonder zo'n ID wordt elke aankoop afzonderlijk gekoppeld, dus een vriend die twee verschillende producten koopt, kan twee keer tellen.
• Een doorverwijzing heeft een vriend nodig die we kunnen identificeren. Een installatie of event dat zonder apparaat-ID binnenkomt, wordt niet geteld.
• Jezelf doorverwijzen telt niet. Een installatie of event vanaf de eigen telefoon van de doorverwijzer wordt geregistreerd, maar niet geteld of beloond. Bij aankopen kunnen we de eigen aankoop van de doorverwijzer alleen herkennen als je app hun app user ID heeft verstuurd (zie hierboven) en dezelfde ID met de aankoop meekomt. Zonder die ID wordt een doorverwijzer die op de eigen telefoon koopt, geteld zoals elke vriend.
• Maandelijkse limiet (optioneel). Standaard uit. Zet Beloningen per doorverwijzer per maand beperken aan om beloningen te begrenzen. Doorverwijzingen boven de limiet tellen nog wel mee voor hun totaal, maar leveren die maand geen beloning op.

Programmastatistieken

Het tabblad In-app doorverwijzingen toont je doorverwijzers, het aantal doorverwijzingen in totaal en deze maand, de gegeven beloningen en je topdoorverwijzers.

Regels van de stores

Doorverwijzingsprogramma's zijn toegestaan in de App Store en Google Play. Het kant-en-klare scherm volgt deze regels al voor je:

• Delen is optioneel. Zet nooit een functie achter delen, en beloon nooit een beoordeling of review.
• Alleen het deelmenu. Het scherm vraagt geen toegang tot Contacten en heeft geen optie "iedereen uitnodigen".
• Beloon echte acties. Aankopen of in-app-events belonen is het veiligst. Google Play let op apps die installaties belonen.
• Gratis premiumtijd. Geef die via App Store-aanbiedingscodes, Google Play-promotiecodes of een opgeschoven Google Play-factuur, een promotionele entitlement in RevenueCat of een toegangsniveau in Adapty, in plaats van via een eigen codesysteem.
• Geen cryptobeloningen voor het uitnodigen van mensen.

Goed om te weten

• Doorverwijzers nemen een plek in. Elke doorverwijzer telt mee voor de affiliatelimiet van je plan, net als elke affiliate. Wanneer je de limiet bereikt, geeft createAffiliateForUser AFFILIATE_LIMIT_REACHED terug.
• Een e-mailadres is verplicht om doorverwijzer te worden. Daarmee loggen ze in op hun dashboard.
• Links. Elke doorverwijzer krijgt een link op dezelfde manier als elke nieuwe affiliate: bedrijven met Insert Links krijgen er automatisch een gegenereerd, bedrijven met Short Code Only delen de code, en bedrijven met Branch, AppsFlyer en RevenueCat Web Purchase Link krijgen de volgende link uit hun geüploade deeplinks. Als je geüploade links op zijn, kunnen nieuwe doorverwijzers zich nog steeds aansluiten en hun code delen, dus houd de lijst aangevuld.
• Commissie. Doorverwijzers krijgen de commissie die je kiest onder Beloningen voor doorverwijzers. Kies Geen geld (alleen beloningen) als je alleen in-app beloningen wilt geven.
• Ze terugvinden. In-app doorverwijzers hebben een badge In-app in je affiliatelijst, en je kunt filteren op hoe affiliates zich hebben aangesloten.