Skip to main content
This guide shows you how to request a Gravity ad from your server and show it in your chat UI. An AI platform (also called a publisher) is a product that shows Gravity ads to its users. The guide uses the JavaScript SDK (@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

  1. Go to app.trygravity.com/platform/signup.
  2. Create an AI platform account for your product.
  3. Open Settings. Copy the key from the API Key card.
  4. Save the key as the GRAVITY_API_KEY environment variable on your server.
Keep the API key on your server. Do not put it in client code or in a public repository.

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 slug in the response is the placement_id that you send in ad requests:
A new placement serves ads after Gravity refreshes the placement cache, within 5 minutes.
Sending a placement_id in an ad request does not create a placement. Don’t send IDs from the examples on this site, such as YOUR_PLACEMENT_ID, and don’t reuse one placement_id for different surfaces. Gravity reports revenue, runs experiments, and sets ad formats for each placement. See Placements.

3. Install the SDK

4. Collect context on the client

Call gravityContext() 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.
Send gravity_context from the client to your server, and from your server to Gravity. If you do not, the ad request carries the IP address and User-Agent of your server, not of the end user. Gravity uses these values for fraud detection and for the Device and Geography reports. The SDK getAds() method reads gravity_context from the request body. It also adds the end user’s IP address from the request headers. See Device signals.

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 empty ads array.
Replace 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.
To verify the pixel, see Pixel. If your native app opens ad links in a WebView, also do the in-app browser install.

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:
You now serve real ads and earn revenue. Before you deploy, do the going live checklist.

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() and get_ads() never throw. A failure gives an empty ads array.
  • Impressions and clicks: GravityAd sends 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

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.
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 are in test mode. Set production: true in JavaScript or production=True in Python.
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.