Before you start
- You have a Gravity AI platform account and an API key. See Quickstart, step 1.
- Your server calls your LLM and can send a second request at the same time.
Process overview
1
Design
Decide where ads go in your UI. Create one placement for each surface (for example web chat and iOS chat) in the dashboard or with the API. Decide if you use the SDK or the HTTP API.
2
Integrate
Install the SDK. Call
gravityContext() on the client and gravity.getAds() on the server. Show the ad with GravityAd or with your own component.3
Test
Keep production mode off. Make sure that each placement shows an ad, that impressions fire when the ad is visible, and that clicks go through
clickUrl.4
Install the pixel
Put the Gravity pixel on your site. The pixel creates a visitor ID, and the SDK sends this ID with each ad request. If your app opens ad links in a native in-app browser, also do the in-app browser install.
5
Go live
Get approval from Gravity, then set
production: true. Do the going live checklist.6
Optimize
Gravity can run experiments on ad designs with your real traffic. You do not change your code.
7
Get paid
Connect your payout account and monitor your payouts in the dashboard.
Select placements
A placement is the position of an ad in your UI. Each ad request declares one or more placements. These are the common types:
Each placement also has a
placement_id: the slug of a placement that you created, for example "web-chat-below-answer" or "ios-chat-below-answer". Create one placement for each surface before you send it. A new placement_id in a request does not create a placement. Keep the names stable, because the dashboard reports results for each slot. See Placements.
You can request 1 to 10 placements in one call.
Select the SDK or the API
The SDK and the API use the same ad engine. The SDK calls the API for you. It also collects the context, sends the end user’s IP address, and handles timeouts and errors. Use the SDK when:- You use Node.js, TypeScript, Python, or React.
- You want a ready ad component that Gravity can update from the server.
- You want Gravity experiments with no code changes.
- You want impressions and clicks to be tracked for you.
- You use a language or runtime that has no Gravity SDK.
- You show ads with your own components and cannot use
GravityAd. - You build a CLI or another surface with no web UI.
Direct API integrations require a signed agreement with Gravity. Send an email to support@trygravity.com to request access.
Framework examples
Next.js (App Router)
In a Next.js route handler,req is a Web Request. The SDK cannot read its body or headers directly. Parse the body first, then give the SDK an object with body and headers.
Express
FastAPI (Python)
Error handling
The SDK never throws an error. This table shows the result for each failure:
Make sure that your UI works with an empty
ads array. Do not make your LLM response wait for the ad request.
Go live
See Going live. In short: get approval, setproduction: true, make sure that impressions arrive, make sure that clicks go through clickUrl, and monitor the dashboard.
Next steps
Request ads
The request fields, device signals, and tuning options.
Show ads
Show ads with the React component or your own component.
Pixel
Put
gr-pix.js on your site. The SDK sends the visitor ID for better attribution.Experiments
How Gravity tests ad designs on your traffic.