Onside Install Attribution Flow

Onside uses a privacy-friendly token system to track user journeys from landing page to app install. It details events available for marketing analytics and performance.

🔍 Overview

Onside uses a lightweight client-server tracking system to attribute app installs to user actions on landing pages. This allows us to:

• Understand where installs are coming from

• Optimize user experience across devices

• Integrate with platforms like Google Ads for conversion tracking

Attribution is anonymous and relies on two browser-side tokens and server-side event reporting.

---

🔑 The Two-Token System

1. onside_token – Persistent Visitor Identifier

   • Generated on the user's first visit

   • Stored in a browser cookie for up to 6 months

   • Extended on each return visit

   • Does not contain any personal data

Example

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": 1704067200000
}

1. attribution_token – One-Time Install Attempt Token

   • Generated by the server when the page is loaded

   • Returned to the client along with the install link

   • Short-lived and used to track a single install session

How it works:

• On page load, the browser requests the install link

• The request includes the onside_token

• The server responds with:

  • Install URL (e.g. onside-app://install?token=abc123)

  • attribution_token

  • Expiry timestamp

---

🎬 Attribution in Action

User Flow Example (iPhone, iOS 18.6+):

1. Visit https://onside.io/tango to set the onside_token.

2. Page loads, triggering a request for the install link and issuing an attribution_token.

3. User clicks Install, sending an install_button_click event.

4. App opens automatically.

5. User confirms installation, sending a check_install.click event.

Other flows (older iOS, Android, Chrome) trigger different modals and events (e.g. get_approved.opened, go_to_safari.click).

---

📦 What Gets Tracked

Each install-related event includes:

• Timestamp

• Page URL and element ID

• onside_token

• attribution_token (if applicable)

• Device type and browser info

• Timezone and language

Common Events:

Event Description	Details
install_button_click	User clicked the install button
get_approved.opened	Approval modal shown
check_install.click	User confirmed they installed the app
go_to_safari.click	Prompted to open Safari (non-default browser)
is_android.opened	Android-specific fallback displayed

---

🌍 Attribution Events for Analytics

We send webhook events that match key user actions in the attribution flow. These events can be integrated into your analytics pipeline or exported to ad platforms.

🔔 Webhook Events

Each event is a POST request with a JSON payload. Webhooks include:

• Unique event ID (onside_event_id)

• Conversion label (e.g. store_app_installed)

• Timestamp (conversion_time)

• App ID (if applicable)

• Google Ads attribution parameters (optional: gclid, gbraid, wbraid)

All events conform to the schema.

Event example

[
  {
    "onside_event_id": "0197ac9c-ef28-7ee3-a5b4-533c6157d4d8",
    "conversion_label": "store_app_installed",
    "conversion_time": "2025-01-01T00:00:00Z",
    "app_id": "1234567890",
    "gclid": "EAIaIQobChMInbuctZO6jgMVEWWkBB2KrCZJEAEYASAAEgLVvfD_BwE",
    "gbraid": "0AAAAAqGACjk7bU-GTrGxRYpdqSonuTpAV",
    "wbraid": "0AAAAAqGACjmOugzfZ2SiPGY7nz370F-s-"
  }
]

📋 Supported Conversion Labels

Label	Description	Comment
landing_page_visited	User opened the landing page from an ad.	This event is not available by default. Please ask your account manager to enable it.
install_button_tapped	User tapped the “install” button on the landing page.	This event is not available by default. Please ask your account manager to enable it.
store_app_installed	User installed the Onside store app.
app_installed	User installed the end app via the Onside store.
app_launched	User opened the app.	This event is only available when the Onside SDK is integrated into the app.

---

🔐 Privacy First

We designed the attribution system to be privacy-conscious:

• No personal data is collected (no names, emails, or user IDs)

• Cookies are limited to random tokens

• Events are anonymous and compliant with GDPR principles

---

🤝 Integration Requirements

To receive webhook data, you must:

• Provide a webhook endpoint URL to your Onside account manager.

• Ensure your endpoint accepts application/json POST requests.

• Handle deduplication using the onside_event_id.

---

Token Lifecycle Summary

Token	Scope	Storage	Expiry
onside_token	Visitor session	Browser cookie	6 months (auto-extended)
attribution_token	Install session	Server-generated, client-used	A few minutes