AppsFlyer

Build a self-hosted first-party mobile attribution tracker. TypeScript, Fastify, SQLite via better-sqlite3, Vite plus React for the dashboard, Docker Compose for deployment. No accounts, no cloud services, no telemetry.

What it does:
1. Link service: POST /api/links creates a tracked link with campaign, source, medium, and an optional destination path in my app. Each link gets a short id served at GET /l/:id.
2. On click, /l/:id records a click row: timestamp, short id, user agent, platform guess from UA, referrer, IP truncated to /24 for IPv4 and /48 for IPv6, and a random click token set as a cookie. Then 302 to a universal link if the platform is iOS or Android, otherwise to a configured web fallback.
3. Serve /.well-known/apple-app-site-association and /.well-known/assetlinks.json from files in ./public so real deep links work.
4. Ingest endpoint: POST /api/events accepts { deviceId, eventName, clickToken?, platform, appVersion, ts, value? } authenticated by a shared secret in APP_INGEST_KEY. Store raw events untouched in an events table.
5. Attribution job: for each first_open event, attribute deterministically if clickToken matches a click. Otherwise do a probabilistic match against clicks in the last 24 hours on the same truncated IP and platform, and mark it as probabilistic with a confidence field. Never overwrite a deterministic match. Store results in an attributions table so the logic can be re-run idempotently.
6. Dashboard at /: table of campaigns with clicks, installs, deterministic versus probabilistic split, and any named post-install events. Date range picker. CSV export.
7. CLI script: npm run import-spend that loads a CSV of campaign,date,spend so the dashboard can show cost per install for channels I bought myself.

Explicitly out of scope, and say so in the README: SKAdNetwork and AdAttributionKit postbacks, any integration with Meta, Google, TikTok or Apple Search Ads, fraud detection, audience syncing, and a native SDK. The client side is a documented HTTP contract only.

Secrets in .env: APP_INGEST_KEY, PUBLIC_BASE_URL, WEB_FALLBACK_URL. Include a seed script with fake clicks and installs, and vitest tests covering deterministic match, probabilistic match, and the no-double-attribution rule.

# AGENTS.md — Build guide for AppsFlyer

## Project scope
A self-hosted link tracker that issues tagged deep links, logs clicks, and matches them to install and event pings from your own app SDK to give you first-party attribution for channels you control.

Catalogue verdict: no. You can absolutely build a click tracker: log clicks, generate deep links, receive install pings from your own SDK, join them in SQLite. What you cannot build is the reason AppsFlyer exists, which is that Meta, Google, TikTok and Apple do not hand raw attribution data to random self-hosted endpoints. Those self-attributing networks report only to certified measurement partners, and SKAdNetwork/AdAttributionKit postbacks are aggregated and privacy-thresholded by design. Add install fraud detection, which is a data problem across billions of devices rather than a code problem, and the gap stops being about engineering effort. The honest consolation build is a first-party attribution tracker for channels you control: your own links, emails, influencer codes, organic web to app.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- A server with a public HTTPS domain for click and postback endpoints
- Ability to add a small SDK or HTTP call to your own iOS/Android app
- Apple App Site Association and Android assetlinks.json files served for deep linking
- Your own ad account exports if you want spend numbers next to installs

## Stack and architecture
- Build a self-hosted first-party mobile attribution tracker. TypeScript, Fastify, SQLite via better-sqlite3, Vite plus React for the dashboard, Docker Compose for deployment. No accounts, no cloud services, no telemetry.
- Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
- Interface for this mobile attribution workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- On click, /l/:id records a click row: timestamp, short id, user agent, platform guess from UA, referrer, IP truncated to /24 for IPv4 and /48 for IPv6, and a random click token set as a cookie. Then 302 to a universal link if the platform is iOS or Android, otherwise to a configured web fallback.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Self-attributing network data from Meta, Google, TikTok and Apple Search Ads, which is restricted to certified measurement partners.

## Agent implementation rules
- Project rule, data: Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
- Project rule, behavior: Link service: POST /api/links creates a tracked link with campaign, source, medium, and an optional destination path in my app. Each link gets a short id served at GET /l/:id.
- Project rule, recovery: On click, /l/:id records a click row: timestamp, short id, user agent, platform guess from UA, referrer, IP truncated to /24 for IPv4 and /48 for IPv6, and a random click token set as a cookie. Then 302 to a universal link if the platform is iOS or Android, otherwise to a configured web fallback.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this mobile attribution operation with sample or user-owned data: Link service: POST /api/links creates a tracked link with campaign, source, medium, and an optional destination path in my app. Each link gets a short id served at GET /l/:id.
- Show a concrete result or export: Dashboard at /: table of campaigns with clicks, installs, deterministic versus probabilistic split, and any named post-install events. Date range picker. CSV export.
- State the practical limit: Self-attributing network data from Meta, Google, TikTok and Apple Search Ads, which is restricted to certified measurement partners.

## Engineering roadmap
1. Phase 1, architecture and data: Build a self-hosted first-party mobile attribution tracker. TypeScript, Fastify, SQLite via better-sqlite3, Vite plus React for the dashboard, Docker Compose for deployment. No accounts, no cloud services, no telemetry. Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
2. Phase 2, implement: Link service: POST /api/links creates a tracked link with campaign, source, medium, and an optional destination path in my app. Each link gets a short id served at GET /l/:id.
3. Phase 3, implement: Ingest endpoint: POST /api/events accepts { deviceId, eventName, clickToken?, platform, appVersion, ts, value? } authenticated by a shared secret in APP_INGEST_KEY. Store raw events untouched in an events table.
4. Phase 4, review and output: Attribution job: for each first_open event, attribute deterministically if clickToken matches a click. Otherwise do a probabilistic match against clicks in the last 24 hours on the same truncated IP and platform, and mark it as probabilistic with a confidence field. Never overwrite a deterministic match. Store results in an attributions table so the logic can be re-run idempotently. Dashboard at /: table of campaigns with clicks, installs, deterministic versus probabilistic split, and any named post-install events. Date range picker. CSV export.
5. Phase 5, recovery and acceptance: On click, /l/:id records a click row: timestamp, short id, user agent, platform guess from UA, referrer, IP truncated to /24 for IPv4 and /48 for IPv6, and a random click token set as a cookie. Then 302 to a universal link if the platform is iOS or Android, otherwise to a configured web fallback. Verify this invariant with a saved fixture: A replayed batch cannot double-count events; missing or late data must be labelled in the report. State the practical limit: Self-attributing network data from Meta, Google, TikTok and Apple Search Ads, which is restricted to certified measurement partners.

## Paid-product capabilities outside this build
- Self-attributing network data from Meta, Google, TikTok and Apple Search Ads, which is restricted to certified measurement partners
- SKAdNetwork and AdAttributionKit postback handling, decoding and conversion value modeling
- Install and click fraud detection, which depends on cross-advertiser device data you will never have
- Postbacks and audience syncs to thousands of ad partners and MMP-only integrations
- A maintained SDK that survives every OS release, ATT prompt change and privacy policy update
- Deterministic cross-device and cross-platform identity resolution

## Implementation prompt
Build a self-hosted first-party mobile attribution tracker. TypeScript, Fastify, SQLite via better-sqlite3, Vite plus React for the dashboard, Docker Compose for deployment. No accounts, no cloud services, no telemetry.

What it does:
1. Link service: POST /api/links creates a tracked link with campaign, source, medium, and an optional destination path in my app. Each link gets a short id served at GET /l/:id.
2. On click, /l/:id records a click row: timestamp, short id, user agent, platform guess from UA, referrer, IP truncated to /24 for IPv4 and /48 for IPv6, and a random click token set as a cookie. Then 302 to a universal link if the platform is iOS or Android, otherwise to a configured web fallback.
3. Serve /.well-known/apple-app-site-association and /.well-known/assetlinks.json from files in ./public so real deep links work.
4. Ingest endpoint: POST /api/events accepts { deviceId, eventName, clickToken?, platform, appVersion, ts, value? } authenticated by a shared secret in APP_INGEST_KEY. Store raw events untouched in an events table.
5. Attribution job: for each first_open event, attribute deterministically if clickToken matches a click. Otherwise do a probabilistic match against clicks in the last 24 hours on the same truncated IP and platform, and mark it as probabilistic with a confidence field. Never overwrite a deterministic match. Store results in an attributions table so the logic can be re-run idempotently.
6. Dashboard at /: table of campaigns with clicks, installs, deterministic versus probabilistic split, and any named post-install events. Date range picker. CSV export.
7. CLI script: npm run import-spend that loads a CSV of campaign,date,spend so the dashboard can show cost per install for channels I bought myself.

Explicitly out of scope, and say so in the README: SKAdNetwork and AdAttributionKit postbacks, any integration with Meta, Google, TikTok or Apple Search Ads, fraud detection, audience syncing, and a native SDK. The client side is a documented HTTP contract only.

Secrets in .env: APP_INGEST_KEY, PUBLIC_BASE_URL, WEB_FALLBACK_URL. Include a seed script with fake clicks and installs, and vitest tests covering deterministic match, probabilistic match, and the no-double-attribution rule.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.