Agent instructions

Tap App Link + Adapty

You are a coding assistant helping a developer integrate Tap App Link (creator dashboards, tracked install links, and discount codes for apps) with Adapty. Tap App Link matches installs client-side via an SDK and attributes purchase revenue server-side via a Adapty 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 Adapty user id

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

1. Call Adapty.identify with a stable customer_user_id you control (your logged-in user id).
2. Pass that same string to setAppUserId. Webhooks send customer_user_id. Tap App Link also accepts profile_id if customer_user_id is empty.
3. Call setAppUserId immediately after trackInstall, before the first purchase.

await TapAppLink.trackInstall();
await adapty.identify(myUserId);
await TapAppLink.setAppUserId(myUserId);

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 an Adapty placement or paywall id and present that paywall after getOffer() or applyCode().

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

4. Configure the Adapty webhook

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

1. Open Integrations, then Webhook in the Adapty dashboard.
2. Turn the integration on.
3. Adapty uses one form with separate Production and Sandbox fields. Fill each pair from the matching Tap App Link environment.
4. For Tap App Link Production: paste the production webhook URL into Production endpoint URL, and the production Authorization value into Authorization header value for production endpoint.
5. For Tap App Link Sandbox: paste the sandbox webhook URL into Sandbox endpoint URL, and the sandbox Authorization value into Authorization header value for sandbox endpoint.
6. Paste each Authorization value exactly as copied, including the word Bearer. Adapty does not add Bearer for you.
7. In Events names, leave Adapty's default event ids. Renaming them means Tap App Link will ignore those events.
8. Enable the event types in the list below. Extra enabled events are ignored.
9. Save. Adapty immediately POSTs an empty JSON object {} to the URL. Tap App Link replies 2xx with JSON, which completes Adapty's verification.

Paste the copied value into Authorization header value for the matching Adapty environment. Include the word Bearer. Adapty sends that string as the Authorization header with no extra prefix.

Enable events: subscription_started / subscription_initial_purchase, non_subscription_purchase, trial_converted, subscription_renewed, subscription_renewal_cancelled / subscription_cancelled, subscription_expired, subscription_refunded, non_subscription_purchase_refunded, billing_issue_detected. Extra events are ignored. Sandbox Adapty 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.