api.langify · October 2026

UTM Tracking

From campaign to revenue: where do our installs come from – and which of them pay?

← → to navigate · F for fullscreen
Why

The question behind it

Not just how many shops a campaign brings, but which of them upgrade – and how much MRR that creates.

Flow

Five steps from click to report

1

Capture

Click on /install?utm_… → row in install_attribution, cookie with install_uid

2

Link

OAuth callback after install → install_uid is assigned to the shop

3

Evaluate

Plan change → shop_plan_event + GA4 event with UTM data

4

Report API

/v2/api/staff/report, JWT with scope report

5

Intranet

KPIs, revenue & MRR per source, journeys, PDF

The key

One ID ties it all together

install_uid = 3f6c2a1e-8b7d-4c3e-…
CreatedAPI generates a UUID v4 when the click is captured
Travelsv1 stores it as a cookie in the merchant's browser
ReturnsOAuth callback sends it back → shop_id is set
Referencedevery plan event carries attribution_install_uid

Only new installs and re-installs are linked – logins into existing shops change nothing.

Steps 1 + 2

Capture and link

POST /auth/remote/install-attribution

  • utm_source … utm_term, landing_url, referer
  • trimmed, truncated, empty → NULL
  • referrer_domain = host without www.
{ "success": true,
  "install_uid": "3f6c2a1e-…" }

POST /auth/remote/oauth/callback

  • validate JWT (remote-auth) + Shopify HMAC
  • new shop or re-install → link()
  • sets shop_id and install_date
  • no matching UID → silently ignored
Step 3

On every plan change

Database: shop_plan_event

  • upgrade, downgrade or cancel
  • old/new plan, price (USD, monthly)
  • attribution_install_uid → link to the campaign

Google Analytics 4

  • Events plan_change and plan_<target>
  • UTM as install_source, install_campaign, …
  • client_id = sha1(shopId) – pseudonymous, per shop
Steps 4 + 5

Reporting in the intranet

intern.lovely-app.com/report · role reporting or admin · live from the API, 1 h Redis cache

KPIs

Attributions (of which linked), plan events, breakdown by source, medium, campaign

Revenue & MRR

per source, per plan, revenue lost to cancellations and downgrades

Journeys

Plan history per shop: stable, cancelled, switchers, trial only, reactivated

Drill-down

Click a source or medium to filter the table; linked only via linked=1

Year over year

same period one year earlier, via compare=1

PDF export

all filters, A4 landscape, ready to share

Value

What we can answer now

Which campaign drives the most installs?
What is the click-to-install conversion per source?
Which sources bring paying customers – and how much MRR?
How does this compare to last year?
Limits

Known gaps and open issues

Re-install via new campaign → 502

shop_id is UNIQUE; a second link() for the same shop fails.

No cookie, no attribution

Blocked cookies, a different browser or direct App Store installs → unknown.

debug_mode=true in GA4

All events land in the DebugView – review for production.

GA4 needs custom dimensions

install_* parameters must be registered; no link to the web session.

More details

Questions?

Full documentation with endpoints, data model and SQL examples: Documentation (HTML / PDF)

→ Open the documentation

DE