App install tracking

Overview

Track app installs back to the Gravity ad that drove them. Three integration paths:

Adjust

Gravity is a native partner in Adjust. Enable the integration in Campaign Lab and pick the events to share. No URL templates.

Server-to-Server

Your backend calls the Gravity Conversions API on install. Full control over data and timing.

All three write to the same conversion pipeline. Click-through and view-through attribution are supported.

How attribution works

User sees or clicks a Gravity ad, and Gravity captures a unique click identifier
User lands on your website or App Store page
User installs and opens your app
The install is reported to Gravity (via your backend or MMP) with the click identifier
Gravity attributes the install back to the originating campaign and ad

Gravity attribution does not depend on IDFA, so this works with iOS 14.5+ App Tracking Transparency restrictions.

Option 1: Adjust (native partner integration)

Gravity is a partner module inside Adjust, so there are no URL templates or macros to hand-assemble. You enable the integration and choose which events to share.

Share in-app events, not just installs. Gravity optimizes toward whatever you send it, so if all we see is installs, that’s all we can optimize for. Sending signup, purchase, and subscription events lets Gravity bid toward users who actually convert.

Before you start

Adjust access with permission to edit partner setups (Campaign Lab)
Your Gravity API key, from Settings → Organization in the Gravity dashboard
A live Gravity campaign with an ad group (you’ll set the Adjust link as its landing page in step 4)

Setup

Add Gravity as a partner

In Adjust, go to Campaign Lab → Partners → New partner and select Gravity. Paste your Gravity API key when prompted. Callbacks without a valid key are rejected with 401 and nothing is recorded.

Pick your app and enable the integration

Select the app you’re advertising and turn the Gravity integration on. Repeat for each app (iOS and Android are separate apps in Adjust).

Turn on the in-app events you want optimized

Under Data sharing, enable the in-app events Gravity should optimize toward, typically signup, purchase, and subscription, not just installs.Map each of your Adjust event tokens to the matching event, and make sure revenue is shared for purchase and subscription events so Gravity can optimize on value instead of raw counts.

Create the link and set it as your ad group landing page

Create the tracking link in Adjust, then paste that click URL as the landing page on your Gravity ad group. It goes at the ad group level, wherever you’d normally set the landing page. Ads have to point at the Adjust link, since that’s what lets Adjust see the click, carry Gravity’s click ID through the store, and fire the postback back to us.

Adjust event	Gravity event type	Why it matters
Install	`app_install`	Baseline: volume only, no quality signal
Session / re-engagement	`app_open`	Retention signal
Registration / signup	`complete_registration`	First real intent signal; best default for freemium apps
Purchase / in-app purchase	`in_app_purchase`	Optimizes toward revenue when `revenue` + `currency` are shared
Subscribe	`subscribe`	Best signal for subscription apps
Add to cart	`add_to_cart`	Mid-funnel signal
Lead	`lead`	For lead-gen apps

Any event you share that isn’t in this list is passed through as-is (lowercased), so custom events still land. They just won’t be normalized into one of the types above.

Verify

Install the app from a real Gravity ad click and confirm the conversion appears in the Gravity dashboard as attributed. To smoke-test the endpoint directly:

curl "https://conversions.trygravity.ai/mmp/postback/adjust\
?click_id=test-click-123\
&activity_kind=install\
&created_at=$(date +%s)\
&app_id=com.example.app\
&api_key=YOUR_API_KEY"

{
  "status": "ok",
  "conversion_id": "uuid",
  "attributed": false,
  "event_type": "app_install",
  "provider": "adjust"
}

attributed: false is expected for a fake click ID.

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized`	Missing or wrong API key	Copy the key from Settings → Organization and re-save it in the partner setup
Everything comes back unattributed	Gravity’s click ID isn’t reaching the postback	Check the click URL passes `grclid` through as `click_id` (Adjust’s `label` param works too)
Installs show up but nothing else	Only installs are enabled under Data sharing	Turn on the in-app events (signup, purchase, subscription) for the Gravity partner
Purchases attribute but revenue is `0`	`revenue`/`currency` aren’t shared	Enable revenue sharing for the event in Adjust’s data-sharing settings
`status: "duplicate"`	Same click ID + event type inside the dedup window	Expected for retried postbacks; no action needed

Option 2: Server-to-Server

Best when you control the app backend and can capture the click identifier from the ad click URL.

Step 1: Capture the click identifier on your landing page

When a user arrives from a Gravity ad, the URL includes a grclid parameter:

https://yourapp.com/download?grclid=abc-123

Capture and persist it server-side:

const params = new URLSearchParams(window.location.search);
const grclid = params.get('grclid');

// Store server-side (preferred) or in a first-party cookie
fetch('/api/store-attribution', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ grclid }),
});

Step 2: Pass the click identifier through your deep link

If you use a deep link provider (Branch, Firebase Dynamic Links, or a custom universal link), pass the grclid as a custom parameter so it survives the Web → App Store → App flow.

Step 3: Report the install

When the user opens your app for the first time, fire a conversion from your backend.

Python
Node.js
Swift
Kotlin

import requests
import hashlib
import time

API_KEY = "your-gravity-api-key"
GATEWAY_URL = "https://conversions.trygravity.ai/gateway/events"

def report_app_install(user, grclid):
    email_hash = hashlib.sha256(
        user["email"].strip().lower().encode()
    ).hexdigest() if user.get("email") else None

    payload = {
        "data": [{
            "event_name": "AppInstall",
            "event_time": int(time.time()),
            "event_id": f"install-{user['id']}-{int(time.time())}",
            "action_source": "app",
            "user_data": {
                "grclid": grclid,
                "em": [email_hash] if email_hash else None,
                "external_id": [str(user["id"])],
            },
            "custom_data": {
                "value": 0,
                "currency": "USD",
            }
        }]
    }

    return requests.post(
        GATEWAY_URL,
        json=payload,
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=10,
    ).json()

import crypto from 'crypto';

const API_KEY = 'your-gravity-api-key';
const GATEWAY_URL = 'https://conversions.trygravity.ai/gateway/events';

async function reportAppInstall(
  user: { id: string; email?: string },
  grclid: string,
) {
  const hashPii = (val: string) =>
    crypto.createHash('sha256')
      .update(val.trim().toLowerCase())
      .digest('hex');

  const payload = {
    data: [{
      event_name: 'AppInstall',
      event_time: Math.floor(Date.now() / 1000),
      event_id: `install-${user.id}-${Date.now()}`,
      action_source: 'app',
      user_data: {
        grclid,
        em: user.email ? [hashPii(user.email)] : undefined,
        external_id: [user.id],
      },
      custom_data: { value: 0, currency: 'USD' },
    }],
  };

  const resp = await fetch(GATEWAY_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  return resp.json();
}

import Foundation
import CryptoKit

struct GravityInstallReporter {
    static let apiKey = "your-gravity-api-key"
    static let gatewayURL = URL(
        string: "https://conversions.trygravity.ai/gateway/events"
    )!

    static func reportInstall(
        userId: String,
        email: String?,
        grclid: String
    ) {
        var userData: [String: Any] = [
            "grclid": grclid,
            "external_id": [userId],
        ]

        if let email {
            let normalized = email
                .lowercased()
                .trimmingCharacters(in: .whitespaces)
            let hash = SHA256.hash(data: Data(normalized.utf8))
            userData["em"] = [hash.map {
                String(format: "%02x", $0)
            }.joined()]
        }

        let event: [String: Any] = [
            "event_name": "AppInstall",
            "event_time": Int(Date().timeIntervalSince1970),
            "event_id": "install-\(userId)-\(Int(Date().timeIntervalSince1970))",
            "action_source": "app",
            "user_data": userData,
            "custom_data": ["value": 0, "currency": "USD"],
        ]

        let payload: [String: Any] = ["data": [event]]

        var request = URLRequest(url: gatewayURL)
        request.httpMethod = "POST"
        request.setValue(
            "Bearer \(apiKey)",
            forHTTPHeaderField: "Authorization"
        )
        request.setValue(
            "application/json",
            forHTTPHeaderField: "Content-Type"
        )
        request.httpBody = try? JSONSerialization.data(
            withJSONObject: payload
        )

        URLSession.shared.dataTask(with: request) { _, _, _ in }
            .resume()
    }
}

import java.net.HttpURLConnection
import java.net.URL
import java.security.MessageDigest

object GravityInstallReporter {
    private const val API_KEY = "your-gravity-api-key"
    private const val GATEWAY_URL =
        "https://conversions.trygravity.ai/gateway/events"

    fun reportInstall(
        userId: String,
        email: String? = null,
        grclid: String,
    ) {
        Thread {
            val emailHash = email?.let {
                sha256(it.trim().lowercase())
            }

            val userData = mutableMapOf<String, Any>(
                "grclid" to grclid,
                "external_id" to listOf(userId),
            )
            emailHash?.let { userData["em"] = listOf(it) }

            val event = mapOf(
                "event_name" to "AppInstall",
                "event_time" to (System.currentTimeMillis() / 1000),
                "event_id" to "install-$userId-${System.currentTimeMillis()}",
                "action_source" to "app",
                "user_data" to userData,
                "custom_data" to mapOf(
                    "value" to 0, "currency" to "USD"
                ),
            )

            val payload = """{"data":[${
                org.json.JSONObject(event)
            }]}"""

            val conn = URL(GATEWAY_URL).openConnection()
                as HttpURLConnection
            conn.requestMethod = "POST"
            conn.setRequestProperty(
                "Authorization", "Bearer $API_KEY"
            )
            conn.setRequestProperty(
                "Content-Type", "application/json"
            )
            conn.doOutput = true
            conn.outputStream.write(payload.toByteArray())
            conn.responseCode
            conn.disconnect()
        }.start()
    }

    private fun sha256(input: String): String {
        val bytes = MessageDigest.getInstance("SHA-256")
            .digest(input.toByteArray())
        return bytes.joinToString("") { "%02x".format(it) }
    }
}

Post-install events

Track in-app purchases and other downstream events with the same pattern:

payload = {
    "data": [{
        "event_name": "InAppPurchase",
        "event_time": int(time.time()),
        "event_id": f"purchase-{order_id}",
        "action_source": "app",
        "user_data": {
            "grclid": stored_grclid,
            "em": [email_hash],
            "external_id": [user_id],
        },
        "custom_data": {
            "value": 29.99,
            "currency": "USD",
            "order_id": order_id,
            "content_name": "Premium Subscription",
        }
    }]
}

App event types

Event Name	Internal Type	When to fire
`AppInstall`	`app_install`	First app open after install
`AppOpen`	`app_open`	Subsequent app opens (re-engagement)
`InAppPurchase`	`in_app_purchase`	In-app purchase completed
Any custom string	Lowercased	Custom app events

View-through attribution (no click)

If the user installs without clicking an ad (e.g., they saw the ad but went to the App Store directly), send the event without a grclid. Include the user’s email hash and Gravity will attempt to attribute the install to a recent ad impression.

payload = {
    "data": [{
        "event_name": "AppInstall",
        "event_time": int(time.time()),
        "event_id": f"install-{user_id}",
        "action_source": "app",
        "user_data": {
            "em": [email_hash],
            "client_ip_address": user_ip,
            "external_id": [user_id],
        },
        "custom_data": { "value": 0, "currency": "USD" }
    }]
}

Option 3: Other MMPs (postback)

For MMPs where Gravity isn’t a built-in partner module, configure a postback URL manually. On Adjust, use the native partner integration instead. The URL below is only a fallback if your Adjust account can’t see the Gravity partner.

Supported MMPs

MMP	Postback URL
AppsFlyer	`https://conversions.trygravity.ai/mmp/postback/appsflyer`
Adjust	`https://conversions.trygravity.ai/mmp/postback/adjust`
Kochava	`https://conversions.trygravity.ai/mmp/postback/kochava`
Branch	`https://conversions.trygravity.ai/mmp/postback/branch`
Singular	`https://conversions.trygravity.ai/mmp/postback/singular`
Other	`https://conversions.trygravity.ai/mmp/postback?provider=<name>`

Setup

Configure your click URL

In your MMP’s partner configuration for Gravity, ensure that the click identifier from Gravity’s ad URL is captured by the MMP as a custom parameter. Most MMPs call this clickid, click_id, or label.

Add the postback URL

In your MMP dashboard, add Gravity as a postback partner. Use the URL template for your MMP (see examples below).

Test the integration

Send a test postback to verify:

curl "https://conversions.trygravity.ai/mmp/postback/appsflyer\
?clickid=test-click-123\
&event_name=install\
&event_time=$(date +%s)\
&ip=203.0.113.50\
&app_id=com.example.app\
&api_key=YOUR_API_KEY"

Postback URL templates

AppsFlyer
Adjust
Kochava
Branch
Singular

https://conversions.trygravity.ai/mmp/postback/appsflyer
  ?clickid={clickid}
  &event_name={event_name}
  &event_time={event_time}
  &idfa={idfa}
  &ip={ip}
  &revenue={event_revenue}
  &currency={event_revenue_currency}
  &app_id={app_id}
  &country_code={country_code}
  &campaign={campaign_name}
  &api_key=YOUR_GRAVITY_API_KEY

https://conversions.trygravity.ai/mmp/postback/adjust
  ?click_id={click_id}
  &activity_kind={activity_kind}
  &created_at={created_at}
  &idfa={idfa}
  &ip_address={ip_address}
  &revenue={revenue}
  &currency={currency}
  &app_id={app_id}
  &country={country}
  &campaign_name={campaign_name}
  &api_key=YOUR_GRAVITY_API_KEY

https://conversions.trygravity.ai/mmp/postback/kochava
  ?click_id={click_id}
  &event_name={event_name}
  &event_timestamp={event_timestamp}
  &idfa={idfa}
  &device_ip={device_ip}
  &revenue={revenue}
  &currency={currency}
  &app_id={app_id}
  &country_code={country_code}
  &campaign_name={campaign_name}
  &api_key=YOUR_GRAVITY_API_KEY

https://conversions.trygravity.ai/mmp/postback/branch
  ?click_id={click_id}
  &event_name={event_name}
  &timestamp={timestamp}
  &ip={ip}
  &revenue={revenue}
  &revenue_currency={revenue_currency}
  &api_key=YOUR_GRAVITY_API_KEY

https://conversions.trygravity.ai/mmp/postback/singular
  ?click_id={click_id}
  &event_name={event_name}
  &timestamp={timestamp}
  &idfa={idfa}
  &ip={ip}
  &revenue={revenue}
  &currency={currency}
  &campaign_name={campaign_name}
  &api_key=YOUR_GRAVITY_API_KEY

MMP event mapping

The postback receiver normalizes common MMP event names:

MMP Event	Gravity Event Type
`install`, `attributed_install`, `first_open`	`app_install`
`session`, `re_engagement`, `app_open`	`app_open`
`purchase`, `in_app_purchase`, `af_purchase`	`in_app_purchase`
`registration`, `signup`	`complete_registration`
Custom events	Passed through as-is (lowercased)

Response format

Both paths return the same structure:

{
  "status": "ok",
  "conversion_id": "uuid",
  "attributed": true,
  "event_type": "app_install",
  "provider": "appsflyer"
}

Status	Meaning
`ok`	Processed and stored
`duplicate`	Already seen (deduplicated)
`test_ok`	Test mode: validated but not stored
`error`	Processing failed

FAQ

Do I need IDFA for attribution?

No. Gravity does not depend on IDFA for attribution. This works with iOS 14.5+ App Tracking Transparency restrictions. If the user consented to tracking and you have IDFA, you can include it for additional signal, but it’s not required.

What if the user doesn't click the ad?

Send the conversion without grclid but include the user’s email hash (em). Gravity will attempt to attribute the install to a recent ad impression.

Can I track post-install events?

Yes. Use InAppPurchase (or any custom event name) with action_source: "app". Include custom_data.value for revenue attribution. Use the same grclid from the original install to maintain the attribution chain.

Which option should I use?

On Adjust, use the native partner integration. It’s a few clicks and gives you event-level data sharing without URL templates. On another MMP, configure the postback URL. S2S gives you full control if you’d rather call the API from your backend with all available data. All three feed into the same conversion pipeline.

Pixel & web conversions

Track web conversions (purchases, signups, etc.).

Conversions API

Send web conversions from your backend.

Get started

Measure

Reference

App install tracking

Overview

Adjust

Other MMP postback

Server-to-Server

How attribution works

Option 1: Adjust (native partner integration)

Before you start

Setup

Verify

Troubleshooting

Option 2: Server-to-Server

Step 1: Capture the click identifier on your landing page

Step 2: Pass the click identifier through your deep link

Step 3: Report the install

Post-install events

App event types

View-through attribution (no click)

Option 3: Other MMPs (postback)

Supported MMPs

Setup

Postback URL templates

MMP event mapping

Response format

FAQ

Next

Pixel & web conversions

Conversions API

​Overview

Adjust

Other MMP postback

Server-to-Server

​How attribution works

​Option 1: Adjust (native partner integration)

​Before you start

​Setup

​What to share under Data sharing

​Verify

​Troubleshooting

​Option 2: Server-to-Server

​Step 1: Capture the click identifier on your landing page

​Step 2: Pass the click identifier through your deep link

​Step 3: Report the install

​Post-install events

​App event types

​View-through attribution (no click)

​Option 3: Other MMPs (postback)

​Supported MMPs

​Setup

​Postback URL templates

​MMP event mapping

​Response format

​FAQ

​Next

Pixel & web conversions

Conversions API

Overview

How attribution works

Option 1: Adjust (native partner integration)

Before you start

Setup

What to share under Data sharing

Verify

Troubleshooting

Option 2: Server-to-Server

Step 1: Capture the click identifier on your landing page

Step 2: Pass the click identifier through your deep link

Step 3: Report the install

Post-install events

App event types

View-through attribution (no click)

Option 3: Other MMPs (postback)

Supported MMPs

Setup

Postback URL templates

MMP event mapping

Response format

FAQ

Next