Skip to main content
This page tells you how to send Gravity impression and click tracking through your own domain. A tracking proxy is a route on your server that receives the tracking requests, logs them, and forwards them to Gravity. When Gravity serves an ad, the response has two tracking URLs:
  • impUrl: the client requests it when the ad becomes visible (an impression).
  • clickUrl: the client opens it when the user clicks the ad.
By default, these URLs use api.trygravity.ai. With a tracking proxy, they use your domain. Advertisers use the same pattern for first-party conversion tracking.

Why use a tracking proxy

  • First-party data: impressions and clicks come to your domain. You can log them in your analytics, data warehouse, or billing system.
  • Verification: you can compare your impression and click counts with the counts that Gravity reports.
  • Latency data: you can monitor the tracking requests from your own infrastructure.
  • No SDK changes: the SDK requests the URL that is in impUrl and clickUrl. You change these URLs on your server before you send the ad to your client.

How it works

1

Set up a reverse proxy

Add a route on your server (for example /gravity/) that forwards requests to api.trygravity.com.
2

Rewrite the tracking URLs

On your server, after you call gravity.getAds(), replace the Gravity domain in impUrl and clickUrl with your proxy URL.
3

Log the events

Your proxy receives each impression and click request. Log the data that you need, then forward the request to Gravity.

1. Set up the reverse proxy

Do not cache tracking responses, and do not follow the click redirect on your server. Each request must go to Gravity, and the 302 must go back to the browser. See Rules for the proxy.

Nginx

Next.js (middleware or API route)

Express

Python (FastAPI)

2. Rewrite the tracking URLs

After you call gravity.getAds() on your server, replace the Gravity domain in each ad with your proxy URL. Then send the changed ads to the client.

Node / TypeScript

Python

get_ads() returns an AdResult. Its ads items are frozen dataclasses, so make changed copies with dataclasses.replace().
The ?p= token in each URL is encrypted, and you cannot change it. You change only the domain at the start of the URL. Billing and attribution at Gravity continue to work.

3. Log impressions and clicks

Your proxy receives each tracking request. This table shows what each path tells you: The ?p= query parameter is an encrypted payload. It contains the click ID, the campaign ID, the publisher ID, the ad ID, and the price. You cannot decrypt it, because Gravity encrypts it with its own key. But you can count requests, log timestamps, and connect the requests to your session and user data from the request headers.

Example: structured logs

Alternative: client-side callbacks

If you do not need a full proxy, use the onImpression and onClick props of GravityAd. They run in the browser:
Callbacks are easier to add, but they run in the browser. A proxy gives you data on your server, and it works with all ways to show ads, not only the React SDK.

Rules for the proxy

  • Forward X-Forwarded-For. Gravity uses the end user’s IP address for location and fraud detection. Without it, all impressions seem to come from the IP address of your server.
  • Forward User-Agent. Gravity uses it to find the device type and to filter bots.
  • Do not cache. Each impression and click request must go to Gravity. Gravity removes duplicate impressions, but a cached response does not reach Gravity, and Gravity does not record the billing event.
  • Do not follow click redirects. /track/click returns a 302 redirect to the advertiser’s landing page. Your proxy must return this redirect to the browser.

Index

Gravity Index sponsored picks use a different click endpoint. Each recommendation has a short link on index.trygravity.com. You can use the same proxy pattern, with these differences:
  • Proxy target: https://index.trygravity.com/go/{code}. Forward the path as it is. The code is the click ID.
  • Return the 302 as it is: /go/{code} returns a 302 to the provider’s landing page, with the click IDs (grclid, grcpid, grpuid, gradid, grsig) and any campaign UTM parameters in the URL. Return this redirect to the user’s browser. Do not follow it on your server. If your server follows it, the click comes from your server’s IP address, and the user does not take the click IDs to the provider.
  • Link previews get a page, not a redirect: when a link-preview bot (for example Slackbot or iMessage) opens a product link, /go/{code} returns 200 with a preview page and does not count a click. An unknown code returns 404.
  • Only the first click on a link counts: a second click on the same link also redirects, but Gravity does not count it again.
  • Attribution needs a conversion at a CPA provider: a click alone does not earn money. Gravity records a payout when the user converts (for example, signs up) at a provider with an active CPA campaign. A click to a provider without a CPA campaign is only a redirect.
  • Send hashed_email in searches: when you have the user’s email, send its SHA-256 hash (of the normalized email) in the search request. Gravity connects conversions to the search that gave the click, and hashed_email makes this match reliable.

Next steps

Show ads

How the SDK tracks impressions and clicks.

Payouts

How your tracked impressions become revenue.