@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
-
Install the packages:
-
Set
GRAVITY_API_KEYin your server environment.
Step 1: Prepare the context in the client
In your client, callgravityContext() 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 tonew Gravity(). You can also pass them as the fourth argument of getAds() for one call.
User tags and model usage
Addtags to the user when you prepare context:
@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 toGravityAd:
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 whatGravityAdcan draw:units.v1andimageon every placement,frame.gfb1whenenableFramesis on,action.prompton a placement withsupportsPromptAction: true, andconnect.mcpon a placement withsupportsMcpConnect: true. In a browser it also sends the page’s font and theme.GravityAddraws the ad’sunitwith 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-accentand--gravity-radiusset its button color and corner radius.- A
rich_frameunit shows in the frame host, anaction_cardbutton runsonPrompt, and aconnect_cardbutton runsonConnect. 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
GravityAdsends the unit events for you. Ads without aunitshow as before.
Send the slot from the browser
WhengetAds() 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
UseGravityAd if you can. If you draw ads with your own code, do these things:
- Send
supportsSpec: falsein thegetAds()options. - Load
ad.impUrlonce when the ad becomes visible. - Open
ad.clickUrl, notad.url, when the user clicks the ad. - Show a clear ad label.