Store Attribution Webhooks

This page describes how attribution events are tracked and sent from the Onside store. These events are primarily used to measure conversions for ad campaigns and connect them with user actions inside

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.

Field	Description	Required
onside_event_id	unique identifier for deduplication (uuid)	+
conversion_label	type of event (see below)	+
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)	-

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

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.