AI platform quickstart

What you’re going to do

Create an AI platform account and grab your API key.
Install the SDK.
Fire ad requests from your server in parallel with your LLM call.
Render the ad in your chat UI.
Drop the web pixel on your site.
Flip to production when it looks right.

Copy the commands, change a couple of IDs, ship it.

Throughout this guide we use the SDK (@gravity-ai/api + @gravity-ai/react). If you’d rather hit the HTTP API directly, see the API Reference. Same engine, you just own the rendering and tracking.

1. Create your account

Sign up at app.trygravity.ai/publisher/signup.
Create an AI platform account for your app.
From your dashboard, copy the API key and the Pixel ID.

Save the API key as GRAVITY_API_KEY in your server environment.

2. Install the SDK

npm install @gravity-ai/api @gravity-ai/react

pip install gravity-sdk

3. Prepare context on the client

Call gravityContext() in your chat component so the server gets the session ID and device signals (the end user’s User-Agent, IP, etc.) alongside the messages.

import { gravityContext } from '@gravity-ai/api';

const gravity_context = gravityContext({
  sessionId: chatSession.id,      // your conversation ID
  user: { userId: currentUser.id } // your user ID
});
// gravity_context includes a `device` object: { ua, timezone, locale, ... }
// The server-side SDK adds the end-user IP from the request headers automatically.

fetch('/api/chat', {
  method: 'POST',
  body: JSON.stringify({ messages, gravity_context }),
});

Don’t skip this — and forward gravity_context all the way to the ad request. The device object’s ua and ip are required — they power fraud/bot detection plus the Device and Geography breakdowns in your dashboard, and requests missing them are rejected with HTTP 400. If your backend calls Gravity without forwarding the client’s device, the ad request carries your server’s UA/IP instead of the end user’s. The SDK’s getAds(req, …) reads gravity_context from the request body for you — just make sure your client actually posts it. See Device signals.

4. Fetch ads on the server

Fire the ad request in parallel with your LLM call. It never throws — failures return an empty array.

import { Gravity } from '@gravity-ai/api';

const gravity = new Gravity();  // reads GRAVITY_API_KEY from env

app.post('/api/chat', async (req, res) => {
  const { messages } = req.body;

  const adPromise = gravity.getAds(req, messages, [
    { placement: 'below_response', placement_id: 'main' },
  ]);

  // Stream your LLM response in parallel...
  for await (const token of streamYourLLM(messages)) {
    res.write(`data: ${JSON.stringify({ type: 'chunk', content: token })}\n\n`);
  }

  const { ads } = await adPromise;
  res.write(`data: ${JSON.stringify({ type: 'done', ads })}\n\n`);
  res.end();
});

import asyncio
from gravity_sdk import Gravity

gravity = Gravity()  # reads GRAVITY_API_KEY from env

@app.post("/api/chat")
async def chat(request: Request):
    body = await request.json()
    messages = body["messages"]

    ad_task = asyncio.create_task(
        gravity.get_ads(request, messages, [
            {"placement": "below_response", "placement_id": "main"}
        ])
    )

    async def event_stream():
        async for token in stream_your_llm(messages):
            yield f"data: {json.dumps({'type': 'chunk', 'content': token})}\n\n"
        ad_result = await ad_task
        ads = [a.to_dict() for a in ad_result.ads]
        yield f"data: {json.dumps({'type': 'done', 'ads': ads})}\n\n"

    return StreamingResponse(event_stream(), media_type="text/event-stream")

5. Render the ad

import { GravityAd } from '@gravity-ai/react';

function ChatResponse({ response, ads }) {
  return (
    <div>
      <p>{response}</p>
      {ads[0] && <GravityAd ad={ads[0]} />}
    </div>
  );
}

GravityAd automatically handles the placement design, impression tracking, click attribution, disclosure, and fallback.

6. Install the pixel (required)

The Gravity pixel is required for attribution and payouts. Without it, Gravity can’t measure visitor journeys or tie ad performance back to real outcomes. Drop this on every page:

<script>
  !function(w,d,t,u,n,a,m){w['GravityPixelObject']=n;w[n]=w[n]||function(){
  (w[n].q=w[n].q||[]).push(arguments)},w[n].l=1*new Date();a=d.createElement(t),
  m=d.getElementsByTagName(t)[0];a.async=1;a.src=u;m.parentNode.insertBefore(a,m)
  }(window,document,'script','https://code.trygravity.ai/gr-pix.js','gravity');
  gravity('init', 'YOUR_PIXEL_ID');
</script>

See the Pixel page for verification steps and the in-app browser install if your native app opens ad links in a WebView.

7. Verify, then go live

By default, new Gravity() returns test ads — no billing, safe to iterate. You’ll see the same test creative every time. When you’re ready for real traffic:

const gravity = new Gravity({ production: true });

gravity = Gravity(production=True)

That’s it. You’re now serving real ads and earning revenue.

Full integration guide

The long version: lifecycle, placements, error handling, framework-specific examples.

Going live checklist

Everything to verify before flipping production: true.

What you didn’t have to think about

Retries — the SDK handles transient failures silently.
Timeouts — 3 seconds by default. Configurable.
Impression / click tracking — fired by GravityAd. Attribution is automatic.
Experiments — Gravity can test designs without publisher code changes. See Experiments.
Ad quality — Gravity handles the creative; you never hand-pick advertisers.

Troubleshooting

Getting empty ad arrays in production

Expected when no campaign matches the conversation — the engine returns 204 No Content and the SDK resolves to { ads: [] }. Gracefully hide the ad slot. Lower the relevancy threshold to fill more aggressively if you want looser matches.

I'm seeing the same ad every request

You’re still on test mode. Pass production: true to the constructor or set production=True in Python.

Ads appear but impressions aren't counting

If you’re using GravityAd, it fires on visibility via IntersectionObserver — make sure the ad is actually rendering in the viewport. If you render ads with a custom component, you have to fire the impression pixel yourself: new Image().src = ad.impUrl when the ad becomes visible.

Get started

Integrate

Optimize

Reference

AI platform quickstart

What you’re going to do

1. Create your account

2. Install the SDK

3. Prepare context on the client

4. Fetch ads on the server

5. Render the ad

6. Install the pixel (required)

7. Verify, then go live

Full integration guide

Going live checklist

What you didn’t have to think about

Troubleshooting

​What you’re going to do

​1. Create your account

​2. Install the SDK

​3. Prepare context on the client

​4. Fetch ads on the server

​5. Render the ad

​6. Install the pixel (required)

​7. Verify, then go live

Full integration guide

Going live checklist

​What you didn’t have to think about

​Troubleshooting

What you’re going to do

1. Create your account

2. Install the SDK

3. Prepare context on the client

4. Fetch ads on the server

5. Render the ad

6. Install the pixel (required)

7. Verify, then go live

What you didn’t have to think about

Troubleshooting