Skip to main content
Use @gravity-ai/api on your server to request ads, and @gravity-ai/react in your client to show them. For the terms on this page, see Core concepts.

Before you start

  • You have a Gravity API key. Get it from your dashboard under Settings → Platform Settings.
  • Your server runs Node.js (or another runtime with fetch), and your client uses React 17 or later.
  • You have a chat endpoint on your server that calls your model.

Install

  1. Install the packages:
  2. Set GRAVITY_API_KEY in your server environment.
Do not reference GRAVITY_API_KEY in client code. A bundler can put the value into your public JavaScript.

Step 1: Prepare the context in the client

In your client, call gravityContext() and send the result to your server with the messages:
gravityContext() collects the device data, the session, and the consent signal from the page. user.userId is required. In a browser with the Gravity pixel, sessionId is optional: the SDK uses the pixel session. Send the complete gravity_context object to your server.

Step 2: Request ads on the server

Start the ad request at the same time as your model call:
gravity.getAds() reads gravity_context from req.body, adds the end user’s IP address from the request headers, and sends the last two messages to Gravity. It never throws. On no-fill or on an error, ads is an empty array. The result is { ads, status, elapsed, requestBody, error }. status is the HTTP status from Gravity, or 0 for a network error or a missing API key.

Options

Pass these options to new Gravity(). You can also pass them as the fourth argument of getAds() for one call.

User tags and model usage

Add tags to the user when you prepare context:
Tags are optional. See Understand what your users earn you for the rules.
@gravity-ai/api doesn’t have a model usage option. To report model usage, send it in a direct HTTP request to the ad API: see Report model usage.

Step 3: Show the ad in React

Give the ad to GravityAd:
You see the ad under the response. GravityAd draws the placement design, shows a built-in card when no design is available, records the impression and the click, and shows the ad label. Show the slot only when ads has an ad. Keep one stable sessionId for each conversation.

Ad units

On placements where Gravity has turned on ad units, an SDK version that supports them works with no code change:
  • getAds() tells Gravity what GravityAd can draw: units.v1 and image on every placement, frame.gfb1 when enableFrames is on, action.prompt on a placement with supportsPromptAction: true, and connect.mcp on a placement with supportsMcpConnect: true. In a browser it also sends the page’s font and theme.
  • GravityAd draws the ad’s unit with the layout that fits its container’s live width, and re-flows when the width crosses a layout boundary. The unit takes the page’s light or dark surface, text color, and font. --gravity-accent and --gravity-radius set its button color and corner radius.
  • A rich_frame unit shows in the frame host, an action_card button runs onPrompt, and a connect_card button runs onConnect. A unit type or version that the SDK doesn’t know shows as a plain text card.
  • Impressions and clicks are tracked as for every other ad, and GravityAd sends the unit events for you. Ads without a unit show as before.

Send the slot from the browser

When getAds() runs on your server, Gravity doesn’t know the slot width and assumes a typical one. To fit the unit to the real slot, call getPlacementContext from @gravity-ai/react on the slot’s container in the client, send the result to your server, and spread it into the placement:
getPlacementContext returns the slot width (and its maximum height when the container sets one), the page’s font and theme, and the capabilities that GravityAd draws. The frames option defaults to true, to match enableFrames. It never throws. On the server it returns only capabilities.

Turn ad units off

Custom renderer

Use GravityAd if you can. If you draw ads with your own code, do these things:
  1. Send supportsSpec: false in the getAds() options.
  2. Load ad.impUrl once when the ad becomes visible.
  3. Open ad.clickUrl, not ad.url, when the user clicks the ad.
  4. Show a clear ad label.

Troubleshoot