> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript and React SDKs

> Render Gravity ads in React or request them from JavaScript and TypeScript.

## React SDK

```bash theme={null}
npm install @gravity-ai/react
```

Pass the ad returned by Gravity to `GravityAd`:

```tsx theme={null}
import { GravityAd } from '@gravity-ai/react';

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

`GravityAd` automatically handles the placement design, fallback, impression and click tracking, disclosure, and feedback controls.

Pass the API key used for the ad request to enable feedback submissions:

```tsx theme={null}
<GravityAd
  ad={ads[0]}
  sessionId={sessionId}
  apiKey={gravityApiKey}
/>
```

<Note>
  `apiKey` is visible in the browser and used for feedback submissions. Pass it down from your server
  with the ad response rather than referencing a server-only environment
  variable in client code — bundlers either drop the value or inline your
  server secret into the bundle.
</Note>

## JavaScript and TypeScript SDK

```bash theme={null}
npm install @gravity-ai/api
```

Set `GRAVITY_API_KEY` in your server environment.

### Prepare context

In your client application, prepare the session and user context:

```ts theme={null}
import { gravityContext } from '@gravity-ai/api';

const gravity_context = gravityContext({
  sessionId: chatSession.id,
  user: { userId: currentUser.id },
});

await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ messages, gravity_context }),
});
```

Forward the complete `gravity_context` to your server.

### Request ads

Request ads in parallel with your LLM call:

```ts theme={null}
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' },
  ]);

  const llmResponse = await callYourLLM(messages);
  const { ads } = await adPromise;

  res.json({ response: llmResponse, ads });
});
```

`gravity.getAds()` returns `{ ads: [] }` on no-fill or failure, so render the slot conditionally. Keep one stable `sessionId` per conversation.

| Option | Default | Description |
| - | - | - |
| `apiKey` | `GRAVITY_API_KEY` | Publisher API key. |
| `production` | `false` | Set `true` for live ads. |
| `timeoutMs` | `4000` | Request timeout in milliseconds. |
| `relevancy` | `0.2` | Minimum contextual relevance. |

## Custom rendering

Use `GravityAd` unless you need a fully custom renderer. Custom renderers must open `ad.clickUrl`, request `ad.impUrl` once when the ad becomes visible, and show a clear ad disclosure.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.