Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trygravity.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Flip the switch

const gravity = new Gravity({ production: true });
That’s the only code change. Once production: true is set, the engine returns real ads matched to real campaigns, impressions and clicks count toward your revenue, and everything flows through to your dashboard.

​
Pre-flight checklist

Before flipping, verify each of these end-to-end in test mode:
1

API key in your server env

GRAVITY_API_KEY set on your production host. The SDK picks it up automatically. new Gravity({ apiKey: '...' }) also works if you manage secrets differently.
2

Ads render in every placement

For each placement_id you request, confirm the ad shows up in the right spot in the UI. Test modes return a placeholder ad so you should always see something.
3

Impressions fire on visibility

Scroll the ad into view. Network tab should show a request to api.trygravity.ai/ack. Using GravityAd? That’s automatic via IntersectionObserver. Using a custom renderer? Fire new Image().src = ad.impUrl on visibility yourself.
4

Clicks route through tracking

Click the ad. The request should go to api.trygravity.ai/track/click first and 302 to the advertiser’s URL. Never link ad.url directly — always ad.clickUrl.
5

Gravity pixel installed (required)

Install the Gravity pixel on your site. This is required for attribution and payouts. If you have a native app with an in-app browser, also run the in-app browser install inside your WebView.
6

Session IDs are stable

Every ad request from the same conversation should carry the same sessionId. This powers frequency capping and experiment bucketing.
7

Error handling tested

Stop the Gravity API network. Your UI should still render. LLM stream should still work. No exceptions leak.

​
After you flip

1

Check the dashboard

app.trygravity.ai → your AI platform account. Requests, impressions, clicks, and revenue all update in near-real-time.
2

Watch fill rate

Fill rate = served / requested ads. New AI platforms often see lower fill rates for the first week as campaigns learn your audience. Raising the relevancy threshold or restricting placements can push fill up or down deliberately.
3

Monitor latency

The SDK’s ad request has a 3s default timeout. If your p99 hits that, you can bump the timeout via timeoutMs on the constructor — but typically a 3s ad timeout just means your LLM streams without the ad that cycle, which is the graceful-degradation behavior you want.

​
Rollback

Flip production: false on the constructor and deploy. You’ll immediately go back to test ads and stop accruing revenue. Nothing else changes.

​
What’s next

Payouts & analytics

How money moves and what the dashboard tracks.

Experiments

Let the engine optimize your creative mix automatically.