Onside Attribution

This document outlines the two key parts of the Onside attribution system: client-side tracking and server-side webhooks.

Part 1: Client-Side Attribution Flow

Client-side attribution is a browser-based mechanism that allows Onside to identify and track visitors using a persistent token called onside_token.

Flow Description

• When a new user lands on the store page, Onside creates a persistent token (onside_token) stored in the browser. This token is used to associate install link requests with the same visitor and to maintain long-term attribution across sessions.

• Initial visit (no existing cookies): When a visitor lands on the store for the first time, no Onside cookies are found. The client generates and stores a unique identifier called onside_token (using cookies). This token acts as the anonymous visitor ID for future attribution events.

• Install link request: Upon page load, the client immediately sends a request to the backend API to generate the install link. This ensures the link is ready before the user clicks the install button. The onside_token is included in this request to ensure the install can be attributed to the same visitor session. The token itself does not contain personal data '97 it only serves as a unique visit reference.

• Token lifetime and renewal: The onside_token is valid for 6 months from the last visit. Each time the user revisits the website, the expiration date of the token is automatically extended by another 6 months. This ensures smooth attribution for recurring visitors without requiring re-identification.

• Returning visitors: If the visitor returns within 6 months, the existing onside_token is reused for all future requests. If the token has expired or the user manually cleared their cookies, a new token will be generated during the next visit.

Part 2: Attribution Events

This section describes how attribution events are tracked and sent. These events are delivered via two methods: Google Tag Manager (GTM) for client-side landing page events, and Webhooks for server-side installation and app events.

Process Description

• The attribution process is divided into five main stages, using both deterministic and probabilistic methods:

  1. Initial Visit & Web Attribution (Deterministic Approach): A user visits our landing page, triggering the landing_page_visited event. We log this visit, including their IP address and referrer information. When they click the "Install" button, the install_button_tapped event is fired, and we initiate the installation process.

  2. Marketplace Installation (Deterministic Approach): Installing the marketplace on a device triggers the store_app_installed event.

  3. First Launch & Mobile Attribution (Probabilistic Approach): On first launch, the marketplace app registers itself with our backend. The backend attempts to match the mobile launch to the initial web session using the user's IP address.

  4. User Verification & Final Attribution (Probabilistic Approach): When the user signs in and verifies their account, we create a user record and link it to the mobile installation and the original web visit. This completes the attribution chain.

  5. App Installation (Probabilistic Approach): When a user installs an application from the marketplace, it triggers the app_installed event. Similar to the first launch attribution, the backend then attempts to match this installation event to the original web session using the user's IP address.

For the probabilistic stages of attribution, Onside uses an IP matching technique. When a mobile event (like a first launch or app install) occurs, the backend looks for a web session from an unmatched user with the nearest IP address within a 24-hour window preceding the event. This method successfully attributes approximately 67% of users.

Event Delivery and Labels

Landing Page Events (via Google Tag Manager)

Onside uses Google Tag Manager (GTM) to send client-side events related to user activity on the landing page. The specific configuration of these events is managed within your GTM container.

Server-Side Events (via Webhooks)

Onside sends server-side attribution events as webhooks using an HTTPS POST request. Each event is delivered as a JSON payload.

• landing_page_visited: User opened the landing page from an ad.

• install_button_tapped: User tapped the "install" button on the landing page.

• store_app_installed: User installed the Onside store app.

• app_installed: User installed the app via the Onside store.

• app_launched: User opened the app.

Webhook Event Structure

All webhook events conform to the schema

Field	Description	Required
onside_event_id	unique identifier for deduplication (uuid)	+
conversion_label	type of event Server-Side Events (via Webhooks)	+
conversion_time	RFC 3339 timestamp of when the event occurred	+
app_id	ApplicationApple Id (uint64)	+ for conversion_label = app_installed and app_launched
gclid	Google Ads click identifier (from web campaigns)	-
gbraid	Identifier for click-based attribution on iOS (Google Ads)	-
wbraid	Identifier for view-through attribution on iOS (Google Ads)	-

Usage

• Webhook events are sent via POST requests directly to the endpoint you provide. These events can be exported to Google Ads for conversion tracking and optimization. Events can be deduplicated using the onside_event_id field.2