impUrl: the client requests it when the ad becomes visible (an impression).clickUrl: the client opens it when the user clicks the ad.
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
impUrlandclickUrl. 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
Nginx
Next.js (middleware or API route)
Express
Python (FastAPI)
2. Rewrite the tracking URLs
After you callgravity.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 theonImpression and onClick props of GravityAd. They run in the browser:
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/clickreturns a302redirect 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 onindex.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. Thecodeis the click ID. - Return the 302 as it is:
/go/{code}returns a302to 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}returns200with a preview page and does not count a click. An unknown code returns404. - 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_emailin 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, andhashed_emailmakes this match reliable.
Next steps
Show ads
How the SDK tracks impressions and clicks.
Payouts
How your tracked impressions become revenue.