# Onside Attribution

## 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.

{% hint style="info" %}
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.
{% endhint %}

### 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](https://onside.io/schema/ads-conversions.json)

| Field             | Description                                                                                                           | Required                                                      |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| onside\_event\_id | unique identifier for deduplication (uuid)                                                                            | +                                                             |
| conversion\_label | <p>type of event <br><a data-mention href="#server-side-events-via-webhooks">#server-side-events-via-webhooks</a></p> | +                                                             |
| 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


---

# 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-attribution.md?ask=<question>
```

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.