--- title: "Al Hatab Links: take people to the right place, and keep the campaign in view." url: "https://lindemann.design/work/alhatab-links/" description: "A link-routing and campaign-tracking service for Al Hatab Foods, with recorded staging validation and an updated app integration awaiting release." --- # Al Hatab Links: take people to the right place, _and keep the campaign in view._ A link in a message or on a package needs a useful destination, whether someone has the app or is browsing the web. We built Al Hatab’s link service to route those visits and record their campaign context on the brand’s own domain. The Worker is deployed; the updated app integration is awaiting release and device verification. In use - link.alhatab.app · routes ```text /install general install, source and campaign in the query /referral/:code a customer's referral /promo/:code a promotion /store/:id a store, from a map pin or a sign /product/:id a product /category/:id a category /web-to-app carry a page from the site into the app POST /track-install match an install to its click POST /track-batch events from the app, batched POST /track-event a single critical event POST /track-user-identified link a device to a signed-in customer /.well-known/apple-app-site-association Universal Links, for iOS /.well-known/assetlinks.json App Links, for Android both served by the same worker; installed-device verification is pending ``` Campaign and app routes on the brand’s link domain. - one click, three answers ```text ◆ click link.alhatab.app/promo/RAMADAN │ from a WhatsApp message │ ◇ recorded KV, 30 days · D1, kept │ click id, source, campaign, device, country │ ├─ phone, app installed opens the app on the promo ├─ phone, no app tries the app, then offers the store link └─ desktop 302 to the same page on the website bots are recognised and recorded as such, not as customers install, matched click ID connects it to the campaign install, no match recorded as organic Worker deployed; mobile release and device checks pending ``` Different destinations for phones and desktop browsers. - a click, as recorded ```text { "click_id": "c8a1…", "link_type": "promo", "promo_code": "RAMADAN", "utm_source": "whatsapp", "utm_campaign": "ramadan", "device_type": "mobile", "os": "ios", "country": "AE", "city": "Dubai", "ip": "masked or salted hash when anonymisation is enabled", "is_robot": false } ``` Campaign and device details recorded with a click. - install, then a name ```text ◇ install app opens for the first time │ sends its anonymous device id │ ◇ matched install → click c8a1… │ when the click id arrives; otherwise recorded as organic │ ◇ browsing screen views, taps, batched │ still anonymous │ ◆ sign in customer identity from CDC │ the app sends user_identified │ ├─ linked anonymous id → customer id ├─ backfilled the install and every event so far └─ from here one journey, one customer ``` Connect earlier activity to the supplied customer ID. - privacy and environments ```text ANONYMIZE_IP true · masked by default IP_SALT secret · when set, a salted hash instead ATTRIBUTION_TTL 30 days · the click window in KV testing, staging shared development KV and D1 production link.alhatab.app · own KV and D1, custom domain, certificate provisioned observability on; every request carries an id through the logs ``` Separate production storage and configurable IP masking. - Staging benchmark ```text events/req conc events median ms events/s 1 1 30 661 1.5 10 1 300 683 13.2 32 5 960 680 227.9 50 5 1500 858 281.5 32 10 960 690 456.0 50 10 1500 851 531.5 10,000 / 10,000 persisted, reconciled by exact event id 1,000 replayed acknowledged as duplicates, zero extra rows 432 / 432 requests returned 200 as expected staging, no production traffic; a short burst, not sustained capacity ``` 19 September 2026. 10,000 staging events checked, then 1,000 replayed. - automated tests ```text ✓ health check ✓ iOS Universal Links config ✓ Android App Links config ✓ clicks from email, WhatsApp, Instagram, maps ✓ install tracking ✓ batch and critical event tracking ✓ user identification, anonymous → authenticated ✓ replay: duplicates acknowledged, no extra rows 22 passed regression suite; a pre-deploy gate is not yet enforced ``` Regression checks covering routing and event storage. Organisation Al Hatab Foods, Saudi Arabia Role Architecture and engineering Stack - Cloudflare Workers - KV, D1 Status Worker live; app integration pending Since 2025 to present 1. **Route** send visitors towards the app, store or website 2. **Connect** match installs to campaigns when a click ID is available 3. **Record** acknowledge saved events and deduplicate identified retries The brief ## Keep the journey connected after someone taps. Al Hatab sends links through messages, campaigns, packaging and its website. A visitor might have the app installed, need the store listing or be using a desktop browser. The destination needs to suit that situation. The business also needs to understand which campaigns bring people into the app. We built routing and tracking together, on a link domain and infrastructure the client controls. Link routing ## Give each visitor a useful next step. The Worker handles install, referral, promotion, store, product, category and web-to-app links. It records campaign context and chooses a response for the device: a page that attempts to open the app and offers a store link, or a destination on the website. A matching click can later connect an installation to its campaign. The production configuration below is abridged to show the storage bindings and privacy settings. wrangler.toml ```toml [[env.production.kv_namespaces]] binding = "MOBILE_ATTRIBUTION" # clicks, 30-day window [[env.production.d1_databases]] binding = "DB" # clicks, installs, events, identities: kept [env.production.vars] ANONYMIZE_IP = "true" # masked; set IP_SALT for a salted hash ATTRIBUTION_TTL_SECONDS = "2592000" ``` The service also publishes the domain configuration used by iOS Universal Links and Android App Links. Following a visitor through an app-store installation is not guaranteed. If an install arrives without a matching click ID, it is recorded as organic. Verification on installed devices remains part of the app rollout. Connecting the journey ## Connect earlier activity when someone signs in. The app can send an anonymous identity with installation and activity events. After sign-in, it supplies the customer identity to the Worker, which links the two and updates earlier install and event records. This gives campaign reporting a way to connect those stages. The updated mobile integration still needs to be released and verified. Data and reliability ## Make saved events distinguishable from attempted delivery. The event endpoints acknowledge database persistence and recognise retries that retain a stable event ID. Testing and staging use development storage; production has separate storage. IP masking is enabled in the recorded configuration, with salted hashing available. Identity records can include customer contact fields supplied by the app. Forwarding to Google Analytics is best effort, separate from the database acknowledgement. On 19 September 2026, a staging benchmark saved 10,000 unique events and checked every event ID in the database. Replaying 1,000 events added no duplicate rows, and all 432 requests returned the expected acknowledgements. The test data was removed and cleanup verified. This established the result for that bounded test, not sustained production capacity or successful delivery to Google Analytics. Delivery and ownership ## A focused service in the client’s account. One Cloudflare Worker and two storage services hold the routing rules, click history and event records. The client controls the domain and infrastructure. This keeps the implementation focused on Al Hatab’s journeys while fitting beside its website, rewards area and mobile app. The reliability changes were deployed to production on 19 September 2026 after staging validation. The updated mobile client has not yet been released, and installed-device link checks remain pending. The case study separates that remaining rollout work from the Worker tests already completed.