Agent instructions

Tap App Link + Qonversion

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

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

1. Call Qonversion.identify with a stable user id you control. That becomes custom_user_id on webhooks.
2. Pass that same string to setAppUserId. If you skip identify, custom_user_id is empty and matching falls back to Qonversion's own user_id.
3. Call setAppUserId immediately after trackInstall, before the first purchase.

await TapAppLink.trackInstall();
await Qonversion.getSharedInstance().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 a Qonversion offering id and present that offering after a match or code redeem.

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

4. Configure the Qonversion webhook

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

1. Open Integrations, then Webhooks in the Qonversion dashboard.
2. Qonversion uses one form with a main URL, a Sandbox Webhook URL, and a single Header Authorization-Token.
3. For sandbox: paste the Tap App Link sandbox webhook URL into Sandbox Webhook URL, and the sandbox signing secret into Header Authorization-Token (raw secret, no Bearer). Qonversion prefixes Basic. Save and verify a sandbox purchase.
4. An empty Sandbox Webhook URL means sandbox events fail to deliver.
5. When you go live: paste the Tap App Link production webhook URL into the main URL field, and the production signing secret into Header Authorization-Token. Save again. Qonversion's single token means you switch the token when you switch environments.
6. Enable the event types in the list below. Leave Qonversion's default event names.
7. Save. Qonversion sends a request to the URL and activates the integration when it receives 2xx.

Paste the signing secret into Header Authorization-Token. Use the raw secret, without Bearer. Qonversion sends it as Authorization: Basic {token}, using the token as you pasted it.

Enable events: subscription_started, in_app_purchase, trial_converted, subscription_renewed, subscription_canceled / subscription_cancelled / trial_canceled, subscription_expired / trial_expired, subscription_refunded / in_app_refunded, subscription_upgraded / subscription_product_changed, subscription_billing_retry / trial_billing_retry. Extra events are ignored. Sandbox Qonversion 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.