Skip to main content
Use this page to attribute app installs and in-app events to the Gravity ad that drove them.

Choose an integration path

Adjust

Gravity is a dynamic network partner in Adjust. Gravity adds its callbacks to your Adjust tracker link.

Other MMP postback

AppsFlyer, Kochava, Branch, or Singular. You set a postback URL in the MMP. You write no code.

Server-to-server

Your backend sends the install to the Gravity Conversions API. You control the data and the time.
All three paths write to the same conversion pipeline. Gravity supports click-through and view-through attribution. An MMP (mobile measurement partner) is a service that measures app installs, for example Adjust or AppsFlyer. The Tracking CLI can prepare the app setup. Run gravity-tracking setup app --json in your app project. Choose your backend or the MMP that you use. You configure the provider settings in the dashboard of that provider.

How attribution works

  1. A user clicks a Gravity ad. Gravity gives the click a unique click ID.
  2. The user goes to your website or to the app store page.
  3. The user installs and opens your app.
  4. Your backend or your MMP sends the install to Gravity with the click ID.
  5. Gravity attributes the install to the campaign and the ad.
Gravity also attributes the install with the campaign ID (grcpid) and the ad ID (gradid) from the click URL, so send every Gravity parameter with the install, not only the click ID.
Click ID attribution does not need the IDFA. Obey your consent rules and the platform rules when you collect or share other identity signals.

Gravity click parameters

When a user clicks a Gravity ad, the landing page URL has the Gravity click parameters (grclid, grsig, grcpid, grpuid, gradid). Some clicks also carry graid, and some ad networks also pass oppref. Capture every parameter, store it, and send all of them with each conversion. oppref alone does not attribute a conversion in Gravity. Send it together with a Gravity identifier such as grclid or grcpid.

Option 1: Adjust

Gravity is a dynamic network partner in Adjust. The Gravity callbacks are parameters on the tracker link. Adjust sends each callback when the install or the event occurs.
  • Adjust has no Data Sharing screen for Gravity.
  • Adjust does not ask you for a Gravity API key.
  • The callbacks do not contain a key. Gravity accepts a callback because its click ID is a click ID that Gravity issued.
Send the in-app event that is the result of your campaign, and also send installs. Each in-app event needs its own callback on the link (see step 3).

Before you start

  • Access to Campaign Lab in Adjust.
  • The Adjust event token for each in-app event that Gravity must receive. Find the tokens in Adjust, in App → Events.
  • A live Gravity campaign with an ad group. In step 4, you set the final link as its landing page.
1

Create the tracker link in Adjust

In Campaign Lab, create a link for the Gravity network on your app. iOS and Android are different apps, so make one link for each. Copy the full click URL. It starts with https://app.adjust.com/... or https://<yourapp>.go.link/.... Do not use the App Store URL.
2

Send Gravity the link and your event tokens

Send the tracker links to your Gravity contact. Include the event token for each in-app event (for example trial, signup, or purchase). Gravity adds its callbacks and sends you the final link. To do this yourself, see Build the link yourself.
3

Examine the final link

The final link has one install_callback= parameter. It also has one event_callback_<event_token>= parameter for each in-app event. On a go.link branded link, the names are adj_install_callback= and adj_event_callback_<event_token>=. Each callback is a URL-encoded copy of the Gravity postback URL. It contains no API key.
4

Set the link as your ad group landing page

In Gravity, paste the final link as the landing page of your ad group. On each click, Gravity adds its click ID to the link as click_id (and label), together with the Gravity parameters, and oppref when the ad network passes one. Adjust stores the click ID and sends it back in the callbacks. Gravity then attributes the install and the events to the ad.
If a callback has a click ID that Gravity does not know, the response is 401 Unknown click_id. Gravity records nothing. Add these parameters to your Adjust tracker link. Each callback value is the full Gravity URL, URL-encoded one time. This is the Gravity callback. It is the same for installs and for events:
Do not put your Gravity API key in the callback. The tracker link is public, because it is in each ad click. Anyone can read it.
This is a tracker link with the callbacks. Add one event_callback_ for each event token:
A branded or universal link (https://<yourapp>.go.link/...) needs the adj_ prefix on each parameter. Without the prefix, Adjust ignores the parameters:
Do not change the {...} placeholders. Adjust fills them when it sends the callback:
  • {dcp_click_id} is the Gravity click ID. On each click, Gravity adds click_id to the Adjust link, and also label (adj_label on a go.link link), which {label} returns. label is Adjust’s own link parameter, so it uses Adjust’s {label} placeholder instead of a {dcp_...} one.
  • {dcp_grcpid}, {dcp_grpuid}, {dcp_gradid}, and {dcp_grsig} return the Gravity parameters that Gravity adds to the Adjust link on each click. Adjust returns a link parameter named <name> as {dcp_<name>} (Adjust dynamic callback parameters).
  • {event_name} tells Gravity which in-app event occurred. Without it, each in-app event arrives as a generic event.
  • {dcp_oppref} returns oppref, the click reference that the ad network passes through. oppref alone does not attribute the install in Gravity, so keep the other parameters in the callback.
To see how Gravity names each Adjust event, see MMP event names.

Verify the Adjust setup

Install the app from a real Gravity ad click. Then make sure that the conversion shows in the Gravity dashboard as attributed.
  1. Follow the Adjust callback test steps. Add the advertising ID of your device to the final link.
  2. Click the link through a Gravity ad, so that click_id is real.
  3. Install and open the app.
  4. Do the in-app events.
The manual call below records a real conversion with no attribution. Use a test account. Do not put its API key on the public tracker link.
The response is:
attributed: false is correct for a fake click ID. Without api_key, the same fake click ID returns 401 Unknown click_id.

Troubleshoot Adjust


Option 2: Server-to-server

Use this path when you control the app backend and can get the Gravity parameters from the ad click URL.
Keep your Gravity API key in the GRAVITY_API_KEY environment variable on your backend. Do not put it in the app binary. A website-only pixel setup does not track native app events.

Step 1: Capture the Gravity parameters on your landing page

When a user arrives from a Gravity ad, the URL has the Gravity parameters:
Read every Gravity parameter in the URL (grclid, grcpid, grpuid, gradid, grsig, graid, and oppref) and store all of them on your server. Don’t store only grclid. To see what each parameter is, read Gravity click parameters:
Use your deep link or deferred deep link setup to carry all the stored Gravity parameters into the app. A plain App Store link does not keep website parameters.

What identifies the click

Send the install to POST https://api.trygravity.com/gateway/events from your backend, with your Gravity API key. The click is identified by the Gravity parameters in the user_data field of the event. Send every parameter that you stored, exactly as it arrived: grclid, grsig, grcpid, grpuid, gradid, graid, and oppref.
  • Gravity attributes the install to the click with grclid, to the campaign with grcpid, and to the ad with gradid.
  • oppref is a click reference passed through from the ad network. Send it back unchanged. oppref alone does not attribute the install in Gravity: the event needs a Gravity identifier such as grclid or grcpid.
  • A native app has no getCAPIData(). That function is part of the website pixel. Carry the stored parameters into the app (Step 2), send them to your backend, and send them from the backend.
The request body looks like this:
The backend examples in Step 3 send this body. install.gravity holds the stored Gravity parameters.

Step 3: Report the install

  1. On the first open, create an install ID one time.
  2. Store the install ID with the time of the first open. Use the same values on retries.
  3. Send these values and the stored Gravity parameters (if you have them) from the app to your authenticated backend.
  4. On the backend, validate and store the install. Then send it to Gravity.
The Swift and Kotlin examples send the install to your backend, with the session token of your app user. Your backend route must:
  1. Authenticate the user.
  2. Validate the consent and the stored install.
  3. Call the Python or Node.js sender above.
Run the Kotlin request off the UI thread. first_opened_at is in Unix seconds, not milliseconds. The response from Gravity is HTTP 200 with "status": "accepted" for the event. See Response format.

Post-install events

Send in-app purchases and other events after the install with the same request format. Every event must carry all the stored Gravity parameters, the same ones that you sent with the install:

App event types

For all request fields, see Server-side conversions.

View-through attribution (no click)

Some users see the ad but do not click it. They go to the app store directly. For these users, send the event without grclid. Include the hash of the user’s email. Gravity can then try to match the install to an earlier ad view.

Option 3: Other MMPs (postback)

For an MMP other than Adjust, set a postback URL in the dashboard of the MMP. For Adjust, the callbacks go on the tracker link. See Option 1.
Keep API keys in the server postback settings of the MMP. Do not put them in your app binary or in public links.

Supported MMPs

The postback accepts GET with query parameters and POST with a JSON body. Authenticate with an X-API-Key or Authorization: Bearer header when your MMP lets you set postback headers. Most MMP postback templates can’t send headers, so the templates below put the key in api_key=YOUR_GRAVITY_API_KEY. That URL, with the key, is stored by your MMP and written to request logs, so treat the postback configuration as a secret. Only the Adjust postback can authenticate with a Gravity click ID and no key. Use that when you can.

Set up the postback

1

Configure your click URL

In the Gravity partner settings of your MMP, make sure that the MMP stores the click ID from the Gravity ad URL as a custom parameter. Most MMPs name it clickid, click_id, or label. On AppsFlyer, add clickid={grclid} to the attribution link that you set as your landing page. Gravity replaces {grclid} with the click ID on each click, and AppsFlyer returns it in the (clickid) macro. On Adjust, Gravity adds the click ID for you (see Option 1).
2

Add the postback URL

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

Test the integration

This test records a real conversion. MMP postbacks have no test mode. A fake click ID cannot verify ad attribution.
Send a test postback:
The response has "status": "ok". Then look for the event in Events Manager.

Postback URL templates

Each template uses only the macros in the MMP’s own postback documentation. The parameter names are the names Gravity reads. For Adjust, use the callback in Option 1.
Only the Adjust callback returns oppref and the Gravity parameters. The AppsFlyer template returns the click ID in (clickid). The Kochava, Branch, and Singular templates have no macro that returns the Gravity click ID, so Gravity records those installs without attribution. To attribute installs from these MMPs and send oppref, report the install server-to-server with the stored parameters (see What identifies the click). oppref alone does not attribute a conversion in Gravity. The postback needs a Gravity identifier such as grclid or grcpid.
AppsFlyer macros use parentheses. Source: AppsFlyer postback macros.

MMP event names

The postback receiver changes common MMP event names to Gravity event types. This applies to Adjust and to the other MMPs: For Adjust, Gravity reads event_name first. If event_name is empty, Gravity uses activity_kind (for example install). A custom event such as trial_started keeps its name. It does not change to one of the types above. If you optimize for revenue, send revenue and currency with each purchase.

Response format

Server-to-server (CAPI)

A request to /gateway/events returns an acknowledgement:
accepted means that Gravity will process the event in the background. The response does not confirm storage or attribution. Look in Events Manager to make sure that the event arrived. To validate a payload and record no conversion, use CAPI test mode.

MMP postbacks

An MMP postback returns:

FAQ

No. Gravity attribution does not depend on the IDFA, so it works with the App Tracking Transparency rules of iOS 14.5 and later. If the user gave App Tracking Transparency consent and you have the IDFA, you can send it as an additional signal.
Send the conversion without grclid. Include the hash of the user’s email (em). Gravity can then try to match the install to an earlier ad view.
Yes. Send InAppPurchase (or a custom event name) with action_source: "app". Include custom_data.value for revenue attribution. Send all the stored Gravity parameters that you sent with the install, on every event.
On Adjust, send Gravity your tracker link and event tokens. Then set the returned link as your ad group landing page. On another MMP, set the postback URL in the MMP dashboard. Use server-to-server if you want to send all the data from your backend. All three paths go into the same conversion pipeline.

Next

Pixel and web conversions

Track web conversions, for example purchases and signups.

Conversions API

Send web conversions from your backend.