Skip to main content
This page gives the checks to do before you serve real ads, and the steps after you go live. Production mode (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 403 with the error publisher_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 you registered each placement. 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. The pixel is required 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

This is the only code change. In production mode, the engine returns real ads from real campaigns. Impressions and clicks count toward your revenue, and the data shows in your dashboard.

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:
The limit resets at 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

Set production: 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.