Ops Lab Playbook: Attribution + Link Tracking

Last updated: 2026-03-08

1. Purpose and when to use this

Use this module to create tracked links, preview routing decisions, resolve context (ctx) tokens, and submit conversion events safely with idempotency.

2. User roles and auth modes

• Creator/operator using JWT: link writes and route previews.
• Public/visitor (no auth): redirect flow, context resolution, conversion ingestion.

3. Prerequisites checklist

• Primer completed: Onboarding and API Primer
• HANDLE exists.
• JWT_TOKEN is valid.
• Test destination URL is reachable.

4. UI onboarding flow

1. Open https://app.10x.in/apps/attribution.
2. Create or upsert a link with tracking metadata.
3. Run route preview for a target country/device/source.
4. Trigger a redirect using the public short URL.
5. Validate conversion event acceptance and dedupe behavior.

5. API workflow map

1. AT-01: PUT /v2/handles/{handle}/links/{slug} (JWT)
2. AT-02: POST /v2/handles/{handle}/links/{slug}/route-preview (JWT)
3. AT-03: GET https://{handle}.10x.in/{slug} (public redirect)
4. AT-04: GET /v2/public/context?ctx=... (public)
5. AT-05: POST /v2/public/conversions (public)
6. AT-06: replay same conversion idempotency key
7. AT-07: invalid ctx negative path
8. AT-08: write-limit enforcement sanity check (429)

6. cURL examples

Set module variables:

export SLUG="launch"
export CTX=""

AT-01 Create tracked link (JWT)

curl -sS -X PUT "${API_BASE}/v2/handles/${HANDLE}/links/${SLUG}" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "destinationUrl": "https://example.com/product",
    "tracking": {"utmSource": "suite", "utmCampaign": "spring"},
    "routingRules": []
  }'

AT-02 Route preview (JWT)

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/links/${SLUG}/route-preview" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{"country":"US","device":"mobile","source":"ad","campaign":"spring"}'

AT-04 Resolve ctx token (public)

curl -sS "${API_BASE}/v2/public/context?ctx=${CTX}"

AT-05 Submit conversion (public)

curl -sS -X POST "${API_BASE}/v2/public/conversions" \
  -H 'content-type: application/json' \
  -d '{"ctx":"'"${CTX}"'","idempotencyKey":"purchase-001","eventType":"purchase"}'

AT-06 Replay idempotent conversion

curl -sS -X POST "${API_BASE}/v2/public/conversions" \
  -H 'content-type: application/json' \
  -d '{"ctx":"'"${CTX}"'","idempotencyKey":"purchase-001","eventType":"purchase"}'

7. Expected success outputs and verification checks

• Link upsert returns slug and short URL.
• Route preview returns deterministic destination decision envelope.
• Public redirect returns 302 and location may include ctx.
• Conversion write returns accepted metadata.
• Replay with same idempotency key returns deduped/idempotent outcome.

8. Failure modes and remediation

• 400 invalid_ctx on conversion:
• Remediation: capture a fresh redirect URL and re-extract a valid ctx token.
• 401 on JWT routes:
• Remediation: refresh login and replace JWT_TOKEN.
• 429 rate_limited on write routes:
• Remediation: reduce write frequency, wait for quota window reset, or use higher plan.

9. Async behavior notes

• Link write + preview are synchronous (SYNC).
• Conversion ingestion fanout may enqueue downstream jobs via background processing.
• Idempotency lookup is synchronous before accepting duplicate conversion key.

10. Related links

• Personalization + Campaign Studio