Connecting an iOS app
To attribute App Store purchases to affiliates, you need to connect your app under iOS Apps. This lets Attribloom receive Apple's App Store Server Notifications and match purchases to the affiliate who drove them.
Fields when connecting an app
Display name. Your label for the app inside the Attribloom dashboard. For your reference only.
Bundle ID. The reverse-DNS identifier from Xcode or App Store Connect (for example, `com.example.myapp`). This must exactly match the bundle ID that Apple includes in purchase notifications. If it doesn't match, purchases will not attribute.
App Store app ID. The numeric Apple ID shown in the App Store URL for your app (for example, `1234567890`).
Environment. Choose Production for live App Store builds, or Sandbox for TestFlight and Xcode test purchases. Sandbox purchases are never billed and never pay commission. They are useful for testing your integration only.
After connecting
After saving, Attribloom gives you a Forwarding URL and a one-time forwarding secret. Keep App Store Connect pointed at your own App Store Server Notifications V2 server. After your server receives Apple's request, relay the unchanged `signedPayload` to the Forwarding URL and sign that relay with the forwarding secret. Attribloom verifies the merchant HMAC first, then verifies Apple's JWS inside the payload.
Do not set the Attribloom Forwarding URL in App Store Connect. Apple does not add the merchant HMAC headers, so a direct request would be rejected. If you do not have an ASSN server yet, deploy a small relay and use its URL in App Store Connect.
Verifying ownership
Attribloom flips your app to Active once it receives one valid Apple-signed test notification for your bundle ID. There is no "Send Test Notification" button in App Store Connect; the test notification is an App Store Server API call. Add your App Store Server API key in Attribloom and click Verify, and Attribloom asks Apple to send the test for you. If you would rather not add the key, request a test notification yourself with the App Store Server API and Attribloom auto-detects it when it arrives.
How purchases are attributed
There are two supported paths. Use the direct StoreKit 2 path below if your server receives Apple's notifications. If purchases already flow through RevenueCat, connect RevenueCat under Integrations instead.
RevenueCat sets Apple's appAccountToken to its own app user ID, so the token Attribloom issues never reaches Apple on a RevenueCat app. Send it as the RevenueCat subscriber attribute instead: resolve the token at first launch exactly as below, then before the first purchase call `Purchases.shared.attribution.setAttributes(["attribloom_ref": token.uuidString])`. The attribute may also hold the affiliate's referral code. Attribloom preserves the binding across RevenueCat anonymous IDs, aliases, and transfer events, so renewals keep crediting the same affiliate.
To check the wiring before release, make a sandbox purchase after following an affiliate link. The RevenueCat page under Integrations lists it as a test purchase that would credit that affiliate, or says why it would not. Test purchases never create commission.
Attribution works via the appAccountToken, a UUID that Attribloom issues and ties to the referring affiliate. Your app does not generate this UUID itself. A self-made UUID will not attribute, because the token has to be the one Attribloom minted for that affiliate.
After an explicit referral link, user-initiated paste, or referral-code entry, your app fetches the token from Attribloom's bind endpoint. Network/IP matching is retired and must never establish attribution. When applicable permission allows, your app may attach the current account’s cached token to a StoreKit 2 purchase without waiting for an attribution network request. When Apple's notification arrives, Attribloom reads the token and credits the right affiliate. The token must be set at purchase time; it cannot be added retroactively.
What the affiliate link shows on iPhone
The affiliate's link records the click and shows an App Store interstitial. The user taps Continue to the App Store. That tap copies a signed click token to the clipboard, then opens the App Store. After installation, offer a user-initiated paste action that sends the token to the bind endpoint. Do not inspect the clipboard automatically. This clipboard tap path is the deterministic, preferred bridge from the browser to the installed app.
RevenueCat event rules
Only Production Apple App Store purchase, renewal, and refund events affect real money. The commission base is the purchased-currency price after RevenueCat's reported store commission and tax. Sandbox events never create a conversion, commission, or live-sales signal; a sandbox purchase only reports which affiliate it would have credited. Apple support refunds arrive as RevenueCat `CANCELLATION` with `cancel_reason: CUSTOMER_SUPPORT`; verified negative refund amounts use the existing ledger clawback. Explicit `REFUND` deliveries are also compatible. A voluntary `UNSUBSCRIBE` cancellation does not reverse a paid period. Refunds received before their purchase stay pending for recovery.
RevenueCat setup and recovery
Connect an active verified Production Apple app and supply the exact RevenueCat dashboard app public ID (`providerAppId`). This must match webhook `event.app_id`; subscriber IDs and Apple bundle IDs are different identifiers. Connections created before app scoping keep processing; saving the providerAppId restricts the webhook to that app. Configure the webhook signing secret and the referral subscriber attribute in both Attribloom and RevenueCat.
Authenticated delivery bytes persist before processing. Transient failures return503 and remain pending; the existing worker retries pending receipts after provider retries are exhausted. Duplicate economic Apple transactions are deduplicated across direct notifications and RevenueCat. Source-rejected events are retained for investigation without commission.
Use account-scoped AttribloomKit token storage and create the client for the current signed-in app account. Preserve the complete binding result, including offer context. On account changes, switch to that account's storage; do not reuse another account's token. Offer code entry and explicit paste when a fresh install has no referral. Failed attribution must not block purchase, entitlement delivery or restore. Deterministic identifiers do not establish an automatic ATT exemption; assess the actual cross-company data flow.