Installation Identifiers

Installation Identifiers are the unique keys that link a user’s app installation to their subsequent purchases. They are the “glue” between your app, BitEasy, and your IAP provider (RevenueCat, Apple, etc.).

How it Works

Defer/Preflight/Claim: When a user installs your app via a referral link, the BitEasy SDK or your code sends a request to /claim. BitEasy records the attribution and accepts a stable installation identifier - this could be a randomly generated string, user ID, etc.
Purchase: The user makes a purchase. Your app sends this purchase to your IAP provider (e.g., RevenueCat), typically including the installation identifier as the app_user_id or similar metadata.
Webhook: Your IAP provider sends a webhook to BitEasy with the purchase details.
Attribution: BitEasy looks up the installation identifier from the webhook payload in its database to find the original referring partner and records the earning.

Why is this important?

If the installation identifier sent during the /claim call doesn’t match the user ID in the purchase webhook, BitEasy cannot attribute the sale to the partner.

Supported Providers

BitEasy supports different strategies depending on your IAP provider:

RevenueCat (`app_user_id`)

Use your own custom user ID or RevenueCat’s anonymous ID as the installation identifier.

RevenueCat Setup Guide

Apple (Original Transaction ID)

Use the App Store’s original_transaction_id as the stable identifier for the user’s install.

Apple Setup Guide

Attribution Flow

sequenceDiagram
    participant User
    participant App
    participant BitEasy
    participant IAP as IAP Provider

    User->>App: Clicks Referral Link & Installs
    App->>BitEasy: POST /defer (referralCode)
    BitEasy-->>App: OK (Recorded)
    
    User->>App: Makes Purchase
    App->>IAP: Process Purchase (with ID)
    IAP-->>App: Success
    IAP->>BitEasy: Webhook (Purchase + ID)
    BitEasy->>BitEasy: Match ID to Attribution
    BitEasy->>BitEasy: Record Partner Earning