production: true) tells the SDK to request real ads. In test mode, the SDK requests test ads, which are not billed.
Before you start
- Gravity approved your platform for real ads. See Guidelines. Until approval, a production ad request returns
403with the errorpublisher_not_approved. - Your integration works in test mode. See the Quickstart.
Pre-flight checklist
Do each of these checks in test mode, from start to end:1
The API key is on your server
Set
GRAVITY_API_KEY on your production server. The SDK reads it automatically. If you keep secrets in a different way, use new Gravity({ apiKey: '...' }) in JavaScript or Gravity(api_key=...) in Python.2
Ads show in each placement
For each
placement_id that you request, make sure that the ad shows in the correct position in the UI. To always get a test ad, use new Gravity({ alwaysReturn: true }) in JavaScript. Make sure that each surface has its own registered placement, and that every placement_id in your code is the slug of one of them (dashboard_list_placements or the Placements page lists them). No placement_id from the docs examples, such as YOUR_PLACEMENT_ID or main, may stay in the code. See Placements.3
Impressions fire when the ad is visible
Scroll the ad into view. The Network tab must show a request to
api.trygravity.ai/ack. GravityAd sends it automatically. If you use your own component, request ad.impUrl when the ad becomes visible, for example new Image().src = ad.impUrl.4
Clicks go through tracking
Click the ad. The first request must go to
api.trygravity.ai/track/click, and it must return a 302 redirect to the advertiser’s URL. Do not link to ad.url. Always use ad.clickUrl.5
The Gravity pixel is installed
Install the Gravity pixel on your site. AI platforms install the pixel for attribution and payouts. If your native app opens ad links in an in-app browser, also do the in-app browser install in your WebView.
6
Session IDs are stable
All the ad requests from one conversation must have the same
sessionId. Gravity uses it for frequency caps and experiment groups.7
Device signals get to Gravity
Make sure that each ad request body has a
device object with the end user’s ua and ip. Without them, fraud and bot detection and the Device and Geography reports do not work for that request. gravityContext() collects these values in the browser. Make sure that your server forwards them to the ad request. See Device signals.8
Error handling works
Block the network requests to Gravity. Your UI must continue to show, and your LLM stream must continue to work. No errors must get to the user.
Change to production mode
Request limits
A self-serve account can make 1,000 production requests per UTC day. Ad requests and Index searches count toward the same limit. The Index side is in Search errors. Test requests (testAd: true) don’t count, and accounts on a partner agreement have no daily limit.
When your account reaches the limit, the API returns 429 with a Retry-After header (the seconds until the reset) and this body:
reset_at, midnight UTC. Until then, the SDKs return no ads, and your chat keeps working. To ask about a partner agreement, email support@trygravity.com.
After you go live
1
Look at the dashboard
Open app.trygravity.com and select your AI platform account. Make sure that requests, impressions, clicks, and revenue show.
2
Monitor the fill rate
The fill rate is the number of ads served divided by the number of ads requested. A lower
relevancy threshold gives a higher fill rate. A higher threshold gives a lower fill rate. See Relevancy tradeoff.3
Monitor latency
The JavaScript SDK stops the ad request after 4 seconds (
timeoutMs). The Python SDK stops it after 3 seconds (timeout). If many requests stop at this limit, increase the value on the constructor. When an ad request stops, your LLM response shows with no ad for that turn.Roll back
Setproduction: false on the constructor, and deploy. The SDK then requests test ads, and you stop earning revenue. Nothing else changes.
Next steps
Payouts & analytics
How Gravity pays you and what the dashboard shows.
Experiments
How Gravity tests ad designs on your traffic.