Skip to main content
This guide gives the full process to add Gravity ads to your AI product. For the short version, see the Quickstart.

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.
Use the API when:
  • 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, set production: 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.