# Store Attribution Webhooks

## Process Description

The attribution process is divided into five main stages:

1. **Initial Visit & Web Attribution**: \
   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:**\
   Installing the marketplace on a device triggers the `store_app_installed` event.
3. **First Launch & Mobile Attribution**: \
   On first launch, the marketplace app registers itself with our backend. The backend attempts to match the mobile installation to the initial web visit using the user's IP address.
4. **User Verification & Final Attribution**: \
   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**: \
   The mobile app is installed on the user's device, which triggers the `app_installed` event.

## Delivery method

Onside sends attribution events as webhooks using an HTTPS POST request.

* Each event is delivered as a JSON payload following the schema below.
* You can get these events set up for your account by providing your webhook endpoint URL to your Onside account manager.

## Event structure

All 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 | type of event ([see below](https://docs.onside.io/api/store-attribution-webhooks#conversion-labels)) | +                                                             |
| 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)                                          | -                                                             |

<details>

<summary>Event example</summary>

```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-"
  }
]
```

</details>

### Conversion labels

The following conversion events are supported:

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

### Usage

* Events are sent via POST webhooks directly to the endpoint you provide.
* These events are exported to Google Ads for conversion tracking and optimization.
* Each event should include the `gclid`, `gbraid`, or `wbraid` parameter if available to ensure correct attribution.
* Events can be deduplicated using the `onside_event_id` field.