Agent instructions

Tap App Link + RevenueCat

You are a coding assistant helping a developer integrate Tap App Link (creator dashboards, tracked install links, and discount codes for apps) with RevenueCat. Tap App Link matches installs client-side via an SDK and attributes purchase revenue server-side via a RevenueCat webhook. Promo codes are a second attribution path when the viewer types a code at checkout.

1. Install and configure the Tap App Link SDK

If the project is missing the SDK, add it for the target platform, then call configure once on launch. Use the sandbox key and environment on test builds, production on store builds.

• React Native / Expo (development client; Expo Go cannot load Play Install Referrer): yarn add @tapapplink/react-native
• iOS: Swift Package https://github.com/tapapplink/tapapplink-ios
• Android: implementation("com.github.tapapplink:tapapplink-android:0.1.1")
• Flutter: tapapplink: ^0.1.2

import { TapAppLink } from "@tapapplink/react-native";
import Purchases from "react-native-purchases";

TapAppLink.configure({
  publicKey: "YOUR_TAPAPPLINK_KEY",
  environment: __DEV__ ? "sandbox" : "production",
});

await TapAppLink.trackInstall();
await TapAppLink.setAppUserId(await Purchases.getAppUserID());

const offer = TapAppLink.getOffer();
if (offer?.billingOfferId) {
  const offerings = await Purchases.getOfferings();
  const discounted = offerings.all[offer.billingOfferId];
  // Present this offering on the paywall
}

2. Track the install, then bridge the RevenueCat user id

Call trackInstall() on every launch. It only records once per install. Immediately after, call setAppUserId() with Purchases.getAppUserID() / Purchases.shared.appUserID. That bridge attaches webhook events to the creator who drove the install.

1. After Purchases.configure, read the App User ID with Purchases.getAppUserID() (iOS: Purchases.shared.appUserID).
2. If you call Purchases.logIn, call setAppUserId after logIn so the id matches the one RevenueCat puts on webhooks as app_user_id.
3. Call setAppUserId immediately after trackInstall, before the first purchase.

await TapAppLink.trackInstall();
await TapAppLink.setAppUserId(await Purchases.getAppUserID());

3. Wire creator discount codes

After a match, getOffer() returns the creator's discount. If the user types a code in-app, call applyCode() so they still attribute to that creator.

await TapAppLink.applyCode("SARAH10");
const offer = TapAppLink.getOffer();

Map discount.billingOfferId to a RevenueCat Offering identifier and present Purchases.getOfferings().all[billingOfferId].

Full product guide: https://tapapplink.com/docs/concepts/promo-codes/

4. Configure the RevenueCat webhook

Human click path: https://tapapplink.com/docs/integrations/revenuecat/. Follow those dashboard steps. Summary:

1. Open your project in the RevenueCat dashboard.
2. In the left menu, open Integrations, then Webhooks.
3. Choose Add new configuration.
4. Name it so you can tell environments apart, for example Tap App Link sandbox or Tap App Link production.
5. Paste the Tap App Link webhook URL for this environment.
6. Set the Authorization header to the value copied from Tap App Link, including the word Bearer.
7. Under which purchases to send, pick sandbox purchases for Tap App Link Sandbox, or production purchases for Tap App Link Production. RevenueCat is one project: this filter is store sandbox vs live, not a separate RevenueCat environment.
8. Leave the webhook scoped to all apps in the project unless you only want one app.
9. Leave event types enabled for the list below, or send all events. Unknown types are ignored.
10. Save. Use Send test event from this configuration to confirm Tap App Link returns 2xx, then make a sandbox purchase on a TestFlight or Play license tester build.

Paste the copied value into RevenueCat's Authorization header field, including the word Bearer.

Enable events: INITIAL_PURCHASE, NON_RENEWING_PURCHASE, TRIAL_CONVERTED, RENEWAL, CANCELLATION, UNCANCELLATION, EXPIRATION, REFUND, BILLING_ISSUE, PRODUCT_CHANGE. Extra events are ignored. Sandbox RevenueCat events must hit the Tap App Link sandbox environment URL. Production events must hit production. Mixing them puts test events into live payouts.

5. Verify

1. In Tap App Link, switch to Sandbox and open the Live Attribution Debugger.
2. Start a link session, scan the QR, then launch the test build with the sandbox SDK key.
3. Confirm the timeline reaches install matched and billing customer linked. If you retry, call resetForTesting() in debug builds first.
4. Trigger a sandbox purchase and confirm the webhook returns 2xx.
5. Optionally start a promo-code watch and redeem a creator code with applyCode().

Hard constraints

• Do not modify billing validation, receipt verification, or the purchase flow. Tap App Link is attribution-only.
• Keep Production and Sandbox keys on the matching builds. Never ship a sandbox key to the store.
• Ask the developer before changing code outside SDK initialization, user-id bridging, offer presentation, and code redemption.
• Prefer the public docs at https://tapapplink.com/docs/ over guessing API shapes.

Human quick start: https://tapapplink.com/docs/quick-start/. Questions: support@tapapplink.com.