Attribution Modes

BitEasy supports two primary attribution modes: explicit (code-based) and best-effort (time-window).

Code-Based Attribution (Recommended)

This is the default and recommended mode.

Characteristics:

• User sees a referral code
• User explicitly confirms attribution
• Deterministic and auditable
• Strongest guarantees

This mode uses:

• /defer-preflight
• /defer
• /claim

Explicit Flow

sequenceDiagram
    participant User
    participant Web as Your Website
    participant API as BitEasy API
    participant App
    
    User->>Web: Clicks Referral Link
    Web->>API: deferPreflight(referrer)
    API-->>Web: claimCode (e.g. ABCD)
    Web->>User: Shows Code
    User->>App: Installs & Opens
    App->>User: Asks for Code
    User->>App: Enters "ABCD"
    App->>API: claimAttribution(code="ABCD")
    API-->>App: Success (Attributed)

1. User opens a referral link on the web
2. Your site calls deferPreflight
3. BitEasy issues a short-lived claim code
4. The user sees the code (copy or QR)
5. User clicks “Get for iOS / Android”
6. Your site calls defer (records platform)
7. User installs the app
8. App calls claimAttribution with the code

Attribution is now complete.

Time-Window Attribution (Best-Effort)

This is an optional fallback.

Characteristics:

• No user-visible code
• Strict time window (10 minutes)
• Ambiguity is rejected
• Silent failure if uncertain

This mode exists for convenience, not as a primary growth mechanism.

Time-Window Flow

sequenceDiagram
    participant User
    participant Web as Your Website
    participant API as BitEasy API
    participant App
    
    User->>Web: Clicks Referral Link
    Web->>API: defer(platform="ios")
    Note right of API: Starts attribution window
    User->>App: Installs & Opens (within 10m)
    App->>API: claimAttribution(no code)
    API->>API: Validates & Checks Ambiguity
    alt Secure Match Found
        API-->>App: Success (Attributed)
    else Ambiguous Match
        API-->>App: Not Found (Silent Fail)
    end

Ambiguity Rules

To prevent false attribution, BitEasy enforces strict rules for window-based claims:

1. Time Limit: The install must occur within 10 minutes of the defer call to be considered.
2. Strict Uniqueness: If multiple referral links were clicked for the same app/platform on the same network within the window, attribution fails.
   • We do not guess which link was “last click”.
   • We do not probabilistically match.
   • If there is ambiguity, we attribute to nobody.

This ensures that every window-based attribution we record is high-confidence, even without a code.

Privacy & Compliance

BitEasy:

• does not fingerprint
• does not track users across apps
• does not infer identity
• does not auto-claim attribution

Attribution only happens when:

• the user explicitly provides a code
• or a strict, short time-window matches unambiguously