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.
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
- A user clicks a Gravity ad. Gravity gives the click a unique click ID.
- The user goes to your website or to the app store page.
- The user installs and opens your app.
- Your backend or your MMP sends the install to Gravity with the click ID.
- Gravity attributes the install to the campaign and the ad.
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.
Set up the Adjust link
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.401 Unknown click_id. Gravity records nothing.
Build the link yourself
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:event_callback_ for each event token:
https://<yourapp>.go.link/...) needs the adj_ prefix on each parameter. Without the prefix, Adjust ignores the parameters:
{...} placeholders. Adjust fills them when it sends the callback:
{dcp_click_id}is the Gravity click ID. On each click, Gravity addsclick_idto the Adjust link, and alsolabel(adj_labelon ago.linklink), which{label}returns.labelis 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 genericevent.{dcp_oppref}returnsoppref, the click reference that the ad network passes through.opprefalone does not attribute the install in Gravity, so keep the other parameters in the callback.
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.- Follow the Adjust callback test steps. Add the advertising ID of your device to the final link.
- Click the link through a Gravity ad, so that
click_idis real. - Install and open the app.
- Do the in-app events.
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.Step 1: Capture the Gravity parameters on your landing page
When a user arrives from a Gravity ad, the URL has the Gravity parameters: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:
Step 2: Pass the Gravity parameters through your deep link
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 toPOST 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 withgrcpid, and to the ad withgradid. opprefis a click reference passed through from the ad network. Send it back unchanged.opprefalone does not attribute the install in Gravity: the event needs a Gravity identifier such asgrclidorgrcpid.- 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.
install.gravity holds the stored Gravity parameters.
Step 3: Report the install
- On the first open, create an install ID one time.
- Store the install ID with the time of the first open. Use the same values on retries.
- Send these values and the stored Gravity parameters (if you have them) from the app to your authenticated backend.
- On the backend, validate and store the install. Then send it to Gravity.
- Python
- Node.js
- Swift
- Kotlin
- Authenticate the user.
- Validate the consent and the stored install.
- Call the Python or Node.js sender above.
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 withoutgrclid. 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.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
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.- AppsFlyer
- Kochava
- Branch
- Singular
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
Do I need the IDFA for attribution?
Do I need the IDFA for attribution?
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.
What if the user does not click the ad?
What if the user does not click the ad?
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.Can I track events after the install?
Can I track events after the install?
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.Which option do I use?
Which option do I use?
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.