Referral Programs & Mobile Sharing

Enterprise mobile app referral infrastructure with zero-PII share codes, deferred deep link attribution, tamper-evident audit ledgers, and signed real-time webhooks.

Architecture overview#

LocusVia provides complete, end-to-end referral infrastructure designed specifically for mobile apps. When a user shares a referral link, LocusVia handles unique code issuance, web-to-app deep link handoffs, deferred attribution across app store installs, automated conversion claim evaluation, and real-time webhook dispatches to your backend.

text

User A (Sharer)
  -> SDK requests share link: POST /api/v1/sdk/referrals/share
  -> LocusVia generates zero-PII link: https://go.brand.com/invite?ref=ref_8f9e1a2b...
  -> Shares link with User B (Invitee)

User B (Invitee)
  -> Clicks link -> App Store / Play Store
  -> Installs & opens app
  -> SDK restores referral context: POST /api/v1/sdk/deferred-link/resolve
  -> Completes registration or purchase: POST /api/v1/sdk/analytics/events
  -> LocusVia records conversion claim, seals Merkle audit ledger, and fires signed webhooks

Core pillars#

Zero-PII Token Storage

Participant share codes are stored only as SHA-256 hashes. No plaintext identity, email, or device tokens are exposed.

Deferred Attribution Engine

Retains the referral code across App Store and Google Play installs via hardware attestation and install referrer matching.

Autonomous Claim Evaluation

SDK conversion events automatically trigger eligibility checks, velocity caps, and self-referral rejection.

Merkle Audit Ledger

Every program creation, participant share, and claim decision is cryptographically sealed into an immutable SHA-256 hash chain.

Signed Lifecycle Webhooks

Real-time HMAC-SHA256 event delivery to reward your users immediately upon verified qualification.

Multi-Tenant Isolation

Strict tenant and environment separation ensures staging tests never pollute production reward balances.

1. Generate a referral share link in-app#

Call the client share API from your mobile app using your app's SDK credentials:

bash

curl -X POST https://api.locusvia.com/api/v1/sdk/referrals/share \
  -H "Authorization: Bearer <sdkApiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "appID": "com.example.app",
    "programId": "prog_summer2026"
  }'

Response:

json

{
  "data": {
    "participantId": "part_9a8b7c6d-5e4f-3a2b",
    "program": {
      "id": "prog_summer2026",
      "name": "Summer 2026 Referral"
    },
    "share": {
      "code": "ref_8f9e1a2b3c4d5e6f7a8b9c0d",
      "shareUrl": "https://go.brand.com/invite?ref=ref_8f9e1a2b3c4d5e6f7a8b9c0d"
    }
  }
}

2. Handle deferred attribution on first launch#

When the invitee opens the app for the first time, your app resolves deferred context:

json

// POST /api/v1/sdk/deferred-link/resolve response:
{
  "processed": true,
  "link": {
    "type": "deferred",
    "url": "https://go.brand.com/invite?ref=ref_8f9e1a2b3c4d5e6f7a8b9c0d",
    "params": {
      "ref": "ref_8f9e1a2b3c4d5e6f7a8b9c0d"
    }
  }
}

3. Ingest conversion events#

When the new user finishes registration or reaches a conversion milestone, send an SDK analytics event with the attributed clickId:

bash

curl -X POST https://api.locusvia.com/api/v1/sdk/analytics/events \
  -H "Authorization: Bearer <sdkApiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "appID": "com.example.app",
    "eventName": "registration_completed",
    "clickId": "clk_1a2b3c4d5e6f7a8b",
    "data": { "userId": "usr_998877" }
  }'

Note

LocusVia automatically pairs the conversion event with the click, evaluates program eligibility, creates a pending claim, and dispatches the lifecycle webhook.

4. Webhook payload verification#

Your backend receives a signed HTTP POST webhook when a claim is created or decided:

json

{
  "id": "evt_4f5e6d7c-8b9a-0123-4567-89abcdef0123",
  "type": "referral.converted",
  "tenantId": "tenant_acme",
  "environmentId": "prod",
  "createdAt": "2026-08-28T20:25:00.000Z",
  "data": {
    "claimId": "claim_11223344",
    "referralId": "ref_55667788",
    "programId": "prog_summer2026",
    "status": "converted"
  }
}

Verify the webhook signature using HMAC-SHA256:

typescript

import crypto from "node:crypto";

function verifyWebhookSignature(payload: string, signatureHeader: string, secret: string): boolean {
  const [timestampPart, sigPart] = signatureHeader.split(",");
  const timestamp = timestampPart.replace("t=", "");
  const signature = sigPart.replace("v1=", "");

  // Prevent replay attacks (5 minute window)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${payload}`)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Anti-abuse & compliance rules#

Self-Referral Prevention — Users cannot claim rewards by clicking their own share links.
Participant Caps — Configurable maximum conversions per participant prevent bot scraping.
HMAC-SHA256 Sealing — All webhooks and audit ledger entries are cryptographically sealed.
State Machine Monotonicity — Claims transition cleanly from eligible -> pending -> approved/denied.