How to Build a Custom Attribution System for Shopify App Installs

How to Build a Custom Attribution System for Shopify App Installs

Off-the-shelf attribution tools are designed for e-commerce stores, not Shopify app developers. The App Store sits on a third-party domain where no tracking scripts can run, so standard solutions like Meta Ads pixel events cannot measure installs. If you want to know which ads drive installs and which installs become paying merchants, you need to build the system yourself.

Architecture Overview

The system has four components: a redirect endpoint that captures ad click data, a data store that persists click records, a matching engine that connects installs to clicks, and a reporting layer that extends attribution to revenue.

Ad clicks hit your redirect endpoint, which captures identifiers, stores them, sets a cookie, and redirects to the App Store listing. When the merchant installs and triggers OAuth, the matching engine finds the best click match. The install record is then enriched with downstream events as they occur.

Component 1: The Redirect Endpoint

Choosing Your Infrastructure

The redirect endpoint must be fast (under 200ms response time), reliable (100% uptime during ad campaigns), and on the same root domain as your OAuth callback. Serverless functions work well: AWS Lambda with API Gateway, Cloudflare Workers, or Vercel Edge Functions.

The same-domain requirement is critical. If your redirect lives at yourapp.com/go/install and your OAuth callback is at yourapp.com/auth/callback, the first-party cookie set during the redirect is accessible during OAuth. If they are on different domains, you lose cookie-based matching entirely.

What to Capture

Parse every available identifier from the incoming request:

UTM parameters: utm_source, utm_medium, utm_campaign, utm_content, utm_term. These identify the channel, campaign, and creative.

Platform click IDs: gclid (Google), fbclid (Meta), ttclid (TikTok), msclkid (Microsoft Ads). These allow you to report conversions back to ad platforms for optimization.

Browser fingerprint data: IP address (check X-Forwarded-For for proxied requests), user agent string, and Accept-Language header.

Timestamp and session ID: Record the exact UTC time and generate a UUID v4 as the primary identifier for this click event.

Setting the Cookie

Set a first-party cookie via HTTP response headers, not JavaScript. Safari's ITP limits JavaScript-set cookies to 7 days, while HTTP-set cookies persist up to 400 days. Use your server-side tracking infrastructure:

Set-Cookie: _app_attr_id={session_id}; Domain=yourapp.com; Path=/; Max-Age=2592000; Secure; HttpOnly; SameSite=Lax

The 30-day Max-Age balances coverage (merchants who delay installation) with match accuracy (longer windows increase false match risk).

Issuing the Redirect

Return a 302 redirect to your App Store listing URL. The complete endpoint flow should take under 100ms. Write the database record asynchronously after sending the redirect to avoid latency.

Component 2: The Data Store

Schema Design

You need two primary tables:

Click events table: session_id (primary key), utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid, ttclid, ip_address, user_agent, accept_language, timestamp, landing_url.

Install events table: install_id (primary key), shop_domain, matched_session_id (foreign key to clicks), match_method (cookie, fingerprint, ip_only), match_confidence (float 0-1), install_timestamp, trial_started_at, converted_to_paid_at, plan_name, monthly_revenue, churned_at.

Use a database that supports fast lookups by IP address and time range. PostgreSQL with appropriate indexes works well. For high-volume apps, consider a time-series partition on the click events table.

Retention Policy

Retain click events for 90 days. After that, unmatched clicks are unlikely to match future installs and the data has no analytical value. Retain install records indefinitely, as they are the basis for lifetime revenue attribution.

Component 3: The Matching Engine

The matching engine runs when your OAuth callback fires. It receives the merchant's shop_domain and needs to find the click event that led to this install.

Matching Cascade

Apply matching methods in order of confidence:

Level 1: Cookie match (confidence 0.95+). Check for the _app_attr_id cookie in the OAuth callback request. If present, query the click events table by session ID. This is a deterministic match assuming the same browser was used for both the ad click and the install.

Level 2: Fingerprint match (confidence 0.6-0.8). Query click events where IP address and user agent match within a configurable time window (default 48 hours). If multiple match, select the most recent with the strongest UTM data.

Level 3: IP-only match (confidence 0.3-0.5). Match on IP address only. This catches browser switches on the same network. Flag these matches distinctly in reporting.

Level 4: No match. If no click event matches, the install is unattributed. Do not force a match. Unattributed installs are expected and may represent organic installs, word-of-mouth referrals, or ad-driven installs that fell outside your matching capabilities.

Handling Edge Cases

Multiple merchants from the same IP. Agencies and co-working spaces produce multiple installs from the same IP. When multiple unmatched click events exist for an IP, do not match. Flag these for manual review.

Reinstalls. A merchant who uninstalls and reinstalls should not be attributed as a new install. Check your install history table for the shop_domain before creating a new record.

Component 4: Revenue Attribution

Install attribution is the foundation, but the business question is which ads generate revenue, not just installs.

Enriching the Install Record

As each merchant progresses through your funnel, update the install record: trial start date, first payment date, plan tier, monthly recurring revenue, expansion revenue from plan upgrades, and churn date if applicable.

Calculating Channel-Level Metrics

With install-to-revenue connections in place, calculate the metrics that drive budget decisions:

Cost per install (CPI) by channel: ad spend divided by attributed installs. Segment by match confidence to understand how sensitive the number is to matching methodology.

Install-to-paid conversion rate by channel: percentage of attributed installs that become paying merchants. This often varies dramatically by channel. Google Ads search campaigns targeting merchants with specific problems tend to produce higher conversion rates than Meta Ads awareness campaigns.

Payback period by channel: months until cumulative merchant revenue exceeds acquisition cost.

ROAS by channel: total lifetime revenue from attributed merchants divided by total ad spend. Track ROAS at 3, 6, and 12 months after install to understand how channel value evolves.

Incrementality Validation

Your attribution system measures correlation: a click happened, then an install happened, so the click gets credit. But some of those merchants would have found your app without the ad. Incrementality testing measures causation.

Run periodic tests by pausing ads on specific channels for defined periods and measuring the install rate change. If you normally get 10 installs per day with Google Ads running and 6 per day without, Google is driving approximately 4 incremental installs daily, not the 7-8 that your attribution system might claim.

This validation step prevents you from overvaluing channels and overspending. It is the same principle that e-commerce brands apply when they use causal inference to separate truly incremental revenue from revenue that would have occurred regardless.

Deployment and Iteration

Deploy the redirect endpoint and cookie-based matching first. Add fingerprint matching once you have enough data to validate accuracy. Add revenue attribution once merchants progress through your funnel. Track your match rate weekly and investigate if it drops below 50%.

Always segment reports by match confidence. High-confidence matches drive campaign optimization. Medium-confidence matches contribute to channel-level analysis. Low-confidence matches are directional only.

Building custom attribution requires engineering investment, but the alternative is spending on ads with zero visibility into outcomes. Even a basic implementation puts you ahead of competitors who link ads directly to the App Store.

For Shopify merchants looking to solve the attribution challenge on their storefront side, get started with measurement that connects ad spend to revenue. For a deeper look at how pet brands, beauty brands, and fashion brands approach multi-channel attribution, request a demo to see causal measurement applied to your specific data.