Integration guide

This is the long version of the Quickstart. If you just want the 5-minute happy path, start there. This guide covers everything around the edges: the full lifecycle from first line of code to recurring payouts.

Lifecycle overview

Design

Decide where ads go in your UI, which placements you need, and whether you’re using the SDK or calling the API directly.

Integrate

Install the SDK. Wire gravityContext() on the client, gravity.getAds() on the server, GravityAd (or your own renderer) in the UI.

Test

Keep production: false. Verify placements render, impressions fire on visibility, clicks route through clickUrl.

Install the pixel

Drop the Gravity pixel onto your site. One <script> tag — mints a visitor ID the SDK automatically forwards on every ad request, which tightens targeting and attribution. If you also open ad links inside a native in-app browser, add the in-app browser install on top.

Go live

Flip production: true. Watch the going-live checklist.

Optimize

Let experiments test ad designs against your real traffic with no integration changes.

Get paid

Monitor payouts in the dashboard. Revenue accrues per impression.

Pick placements

A placement is where an ad sits relative to your UI. Every ad request declares one or more. Common options:

Placement	When to use
`below_response`	Under the assistant’s message. Most common in chat UIs.
`above_response`	Pinned header above the response. Use sparingly.
`inline_response`	Inside the response stream (markdown).
`left_response` / `right_response`	Sidebar next to the response.
`search_result`	Within a search result list.
`top_page` / `bottom_page`	Static, page-level placement.

Each placement has a placement_id you pick — anything identifying the slot ("main", "mobile-footer", etc.). Keep them stable across requests; you’ll see per-slot metrics in the dashboard. You can request up to 10 placements per call and the engine returns an ad per slot (or null per slot with no fill).

Choose: SDK or API

Both hit the same engine. The SDK is a thin wrapper that handles context preparation, impression tracking, retry, and experiments. The API is what the SDK calls under the hood. Use the SDK when:

You’re on Node, TypeScript, Python, or React
You want a pre-built, server-managed ad component
You want managed experiments without integration changes
You want impression tracking to “just work”

Use the API directly when:

You’re on an unusual language / runtime
You render ads in a heavily custom way that can’t use GravityAd
You’re prototyping or building a CLI / non-UI surface

You’re not locked in either way. The API is fully supported and never going away.

Typical integration shapes

Next.js / App Router

// app/api/chat/route.ts
import { Gravity } from '@gravity-ai/api';

const gravity = new Gravity({ production: process.env.NODE_ENV === 'production' });

export async function POST(req: Request) {
  const { messages } = await req.json();

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

  const stream = new ReadableStream({
    async start(controller) {
      for await (const chunk of callLLM(messages)) {
        controller.enqueue(`data: ${JSON.stringify({ type: 'chunk', content: chunk })}\n\n`);
      }
      const { ads } = await adPromise;
      controller.enqueue(`data: ${JSON.stringify({ type: 'done', ads })}\n\n`);
      controller.close();
    },
  });

  return new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } });
}

Express

import { Gravity } from '@gravity-ai/api';
const gravity = new Gravity({ production: true });

app.post('/api/chat', async (req, res) => {
  const { messages } = req.body;
  const adPromise = gravity.getAds(req, messages, [{ placement: 'below_response', placement_id: 'main' }]);
  // ... stream LLM, await adPromise, append ads
});

FastAPI / Python

import asyncio
from gravity_sdk import Gravity

gravity = Gravity(production=True)

@app.post("/api/chat")
async def chat(request: Request):
    body = await request.json()
    ad_task = asyncio.create_task(
        gravity.get_ads(request, body["messages"], [
            {"placement": "below_response", "placement_id": "main"}
        ])
    )
    # ... stream LLM, await ad_task, append ads

Error handling

The SDK never throws. Failure modes:

Situation	Result
Network error / timeout	`{ ads: [] }` (JS) / `AdResult(ads=[])` (Python)
204 No Content (no match)	`{ ads: [] }`
Invalid API key	`{ ads: [] }` + warn in logs
Downstream engine error	`{ ads: [] }` + warn

Your UI should always be safe to render with an empty ads array. Never block your LLM response on the ad fetch.

Going live checklist

See Going live. Short version: flip production: true, verify impressions land, confirm clicks route through clickUrl, watch the dashboard.

What’s next

Request ads

Server-side patterns in depth.

Show ads

Render ads with the official SDK component.

Pixel

Drop gr-pix.js on your site — SDK auto-picks up the visitor ID for better attribution. Optional WebView install for native apps.

Experiments

How the engine auto-optimizes creative mix for your traffic.

Get started

Integrate

Optimize

Reference

Integration guide

Lifecycle overview

Pick placements

Choose: SDK or API

Typical integration shapes

Next.js / App Router

Express

FastAPI / Python

Error handling

Going live checklist

What’s next

Request ads

Show ads

Pixel

Experiments

​Lifecycle overview

​Pick placements

​Choose: SDK or API

​Typical integration shapes

​Next.js / App Router

​Express

​FastAPI / Python

​Error handling

​Going live checklist

​What’s next

Request ads

Show ads

Pixel

Experiments

Lifecycle overview

Pick placements

Choose: SDK or API

Typical integration shapes

Next.js / App Router

Express

FastAPI / Python

Error handling

Going live checklist

What’s next