Installation and Attribution

This document describes the Onside API endpoint for retrieving app installation and attribution data. It is intended for use by apps and SDKs upon their first launch.

Matching approach

Client-provided data

The client sends the token (e.g., appsflyer_id) along with device information. See the request format.

Existing installation check

If an installation record with the same token already exists, we return the previously issued installation ID.

New installation logic

If no installation with that token is found, we attempt to resolve the installation as follows:

IP-based matching We compare the request’s IP address with user IPs from recent Onside Store sessions (last 24 hours).
If we find a match, we generate a new installation ID tied to that specific store user.
Device properties matching If multiple users share the same IP, we use device information to resolve the collision. If we can’t resolve the collision, we generate a completely new installation token.
If no store sessions match the request IP, we generate a completely new installation token.
Attribution resolution If the matched store user has attribution data, we include it in the response as attribution_data. Otherwise, we return no attribution data, indicating an organic user.

An example of matched installation without marketing data (Organic install):

# The JWS response
eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpY19rZXlfMSJ9.eyJpc3Mi...
# Decoded response
{
  "iss": "https://onside.io",
  "aud": "com.example.my-awesome-app",
  "iat": 1678886400,
  "exp": 1678890000,
  "jti": "4d3f2c1a-6b7c-4d3f-8c1a-6b7c4d3f8c1a",
  "request_token": "a1b2c3d4-client-random-token-5e6f",
  "installation_token": "a1b2c3d4-onside-install-token-5e6f"
 }

An example of matched installation with marketing data (Non-Organic install):

# The JWS response
eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpY19rZXlfMSJ9.eyJpc3Mi...
# Decoded response
{
  "iss": "https://onside.io",
  "aud": "com.example.my-awesome-app",
  "iat": 1678886400,
  "exp": 1678890000,
  "jti": "4d3f2c1a-6b7c-4d3f-8c1a-6b7c4d3f8c1a",
  "request_token": "a1b2c3d4-client-random-token-5e6f",
  "installation_token": "a1b2c3d4-onside-install-token-5e6f",
  "attribution_data": {
    "marketing_campaign": "summer_sale_2024",
    "source": "facebook_ads",
    "tags": ["social", "video_ad"],
    "click_id": "clk_123456789"
  }
 }

Get iOS Installation Attribution

post

/merchant-api/v1/attribution/install

Attempts to match a new app installation with attribution data.

Body

Information provided by the client device for attribution matching.

tokenstringRequired

A unique, client-generated random string to bind the installation.

Example: a1b2c3d4-client-random-token-5e6f

bundle_idstringRequired

The app's bundle identifier.

Example: com.example.my-awesome-app

device_modelstringRequired

The device model identifier (e.g., iPhone14,5).

Example: iPhone15,2

os_versionstringRequired

The version of the device's operating system.

Example: 17.2

languagestringRequired

The device's BCP 47 language code.

Example: en-US

availableCapacityintegerOptional

The available disk capacity on the device in bytes

Example: 21489729783

Responses

200

Match Found.

Returns a signed JSON Web Token (JWT) as a plain text string. The JWT payload contains the installation token and attribution data.

You must validate the JWT signature using our public key, published at: https://onside.io/.well-known/jwks.json.

Check AttributionResponse for the token schema.

application/jose

Responsestring · jwtExample: eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpY19rZXlfMSJ9.eyJpc3Mi...