@gravity-ai/api and @gravity-ai/react) and the Python SDK (gravity-sdk). To call the HTTP API directly, see the API reference. With the API, you must show the ad and send the tracking requests yourself.
Set up with a coding agent
Using Claude Code, Cursor, or Codex? Open your project in the agent and paste this prompt. The agent follows this guide, and you review each change.Before you start
- You have a web or mobile product with a chat or answer UI.
- You have a server that calls your LLM. The ad request goes from this server.
- For the JavaScript SDK, you have Node.js and npm. For the Python SDK, you have Python 3.10 or later.
1. Create your account
- Go to app.trygravity.com/platform/signup.
- Create an AI platform account for your product.
- Open Settings. Copy the key from the API Key card.
- Save the key as the
GRAVITY_API_KEYenvironment variable on your server.
2. Create a placement for each surface
A placement is one place in your UI where an ad shows, on one platform. Create one placement for each surface before you write code. For example, a product with a web app and an iOS app that both show an ad below the answer needs two placements:
Create each placement in one of these ways:
- In the dashboard, on the Placements page.
-
With the API. The
slugin the response is theplacement_idthat you send in ad requests:
3. Install the SDK
4. Collect context on the client
CallgravityContext() in your chat component. It returns a gravity_context object with the session ID, the user ID, and device signals. Device signals are data about the end user’s device, for example the User-Agent, the time zone, and the locale.
Send gravity_context to your server in the body of your chat request.
gravityContext() throws an error if user.userId is missing. It also throws an error if sessionId is missing and the Gravity pixel is not on the page. For signed-out users, create a stable anonymous install or device ID and keep it. Do not send a shared constant such as "anonymous", because Gravity leaves it out of per-user analytics.
5. Request ads on the server
Start the ad request at the same time as your LLM call. Do not wait for the ad before you stream the LLM response. The SDK never throws an error. If the request fails, the result has an emptyads array.
YOUR_PLACEMENT_ID with the slug of a placement that you created in step 2. Use the slug of the surface where this code shows the ad.
In test mode, the result is a test ad or an empty ads array. To always get a test ad in JavaScript, use new Gravity({ alwaysReturn: true }). Gravity ignores alwaysReturn in production.
6. Show the ad
GravityAd shows the ad design and the “Sponsored” label. It sends the impression when the ad is visible, and it sends clicks through the tracking URL. You see the ad below the response.
7. Install the pixel
The Gravity pixel (gr-pix.js) is a script for your website. AI platforms install the pixel for attribution and payouts. Without it, Gravity cannot connect ad results to visits and conversions.
Put this script in the <head> of every page. Replace YOUR_PIXEL_ID with your pixel ID. The dashboard shows the full snippet with your ID in Settings > Tracking.
8. Go live
By default,new Gravity() requests test ads. Test ads are not billed and do not earn revenue.
Before you serve real ads, Gravity must approve your platform. See Guidelines. After approval, set production mode:
Integration guide
The full process: placements, framework examples, and error handling.
Going live checklist
The checks to do before you set
production: true.What the SDK does for you
- Timeout: the request stops after 4 seconds in the JavaScript SDK (
timeoutMs) and after 3 seconds in the Python SDK (timeout). You can change these values. - No errors to catch:
getAds()andget_ads()never throw. A failure gives an emptyadsarray. - Impressions and clicks:
GravityAdsends them for you. - Experiments: Gravity can test ad designs on your traffic without code changes. See Experiments.
- Ad selection: Gravity selects the ad and writes the ad text. You do not select advertisers.
Troubleshoot
The ads array is empty
The ads array is empty
This is normal when no campaign matches the conversation. The engine returns
204 No Content, and the SDK gives { ads: [] }. Hide the ad slot. To get more ads, use a lower relevancy threshold. Also make sure that GRAVITY_API_KEY is set. Without a key, the SDK returns an empty array and does not send a request.Production requests return status 403
Production requests return status 403
Gravity did not approve your platform yet. The engine returns
403 with the error publisher_not_approved. Test ads continue to work. See Guidelines for the review steps.You see the same ad on every request
You see the same ad on every request
You are in test mode. Set
production: true in JavaScript or production=True in Python.The ad shows, but impressions do not count
The ad shows, but impressions do not count
GravityAd sends the impression when at least half of the ad is in the viewport. Make sure that the ad is visible on the screen. If you use your own component, you must send the impression yourself. Request ad.impUrl one time when the ad becomes visible, for example new Image().src = ad.impUrl.