funnelgrove Docs

Appearance

Integration Overview ​

The web funnel sells the subscription. Your app connects that purchase to an authenticated account through verified email, while an optional iOS Universal Link preserves deterministic click attribution.

The Flow ​

text
Visitor completes the web funnel and checkout
  -> opens a FunnelsGrove Universal Link
  -> installed app records the open and receives clickId + destination
  -> user signs in and verifies email ownership
  -> customer backend binds clickId with verifiedEmail
  -> backend verifies subscription with that same email
  -> active user is returned with stable user.user_id
  -> backend tracks the login and saves user.user_id on the account
  -> later app opens verify access again with the saved ID

With the app installed, iOS delivers the Universal Link directly to the app, which records the open through the public app-open endpoint. Without the app installed, the HTTP request reaches the resolver, which records the click and returns a direct 302 to the configured App Store URL.

The app link is optional for access. A direct install can still resolve an active subscription after verified login, but it remains unattributed when no deterministic click handoff exists.

The Trust Rule ​

Verify email ownership before looking up a subscription by email. A typed, prefilled, or link-provided value is not proof of ownership.

The link and returned clickId are attribution signals only. They never contain user identity, prove ownership, or grant paid access. The authenticated customer backend performs exact click binding and identity calls; neither the project SDK secret nor an attribution admin credential belongs in the app or browser.

Identity And Access ​

  1. Call POST /sdk/public/users/verify_subscription with the verified email. It returns active, the test mode flag, and, when a user matches, user.user_id without changing state.
  2. If access is active, call POST /sdk/public/users/track_login with that user_id.
  3. Save the exact returned ID on the authenticated app account.
  4. On later app opens, verify access again with the saved ID.

Verification is read-only. Login tracking records App Login only after ownership and active access have been proven.

Responsibilities ​

AreaResponsibility
Web funnelCapture email, show the paywall, and complete checkout.
Billing systemCreate and track the subscription.
Link resolverHandle uninstalled-device HTTP requests, record the click, and redirect to the configured store.
AppReceive the Universal Link, record the app open, persist clickId, and route the returned destination.
Customer backendVerify login email, bind clickId, verify access, track login, and save the stable FunnelsGrove user ID.
FunnelsGrove SDK APIResolve project-scoped subscription state and record App Login.
App backend webhook receiverOptionally receive signed funnel user, payment, and subscription updates.

FAQ ​

The app records the link open and receives a clickId. The customer backend binds that exact click only after it verifies the signed-in user's email.

Use the account's verified email after login. If it matches an active funnel user, track the login with the returned user.user_id; the install remains unattributed.

What if the user paid but has not logged in to the app? ​

Wait until the user signs in and proves email ownership. Do not infer identity from the URL, device, IP address, or User-Agent.

Which platforms fit this flow? ​

Version 1 provides native iOS Universal Links. Android App Links, install referrer, deferred attribution, fingerprinting, and probabilistic attribution are outside this version.

Next ​