# Onside Install Attribution Flow
## π 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
```json
{
"token": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": 1704067200000
}
```
2. `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 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.
{% hint style="info" %}
Other flows (older iOS, Android, Chrome) trigger different modals and events (e.g. get\_approved.opened, go\_to\_safari.click).
{% endhint %}
***
## π¦ 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](https://onside.io/schema/ads-conversions.json).
Event example
```json
[
{
"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 |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.onside.io/api/onside-install-attribution-flow.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.