> ## 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.

# Ad units

> Data-drawn ad units: the SDK describes the slot, Gravity fits a unit to it, and the SDK draws it.

An ad unit is an ad that Gravity describes as data and the SDK draws in your page: a brand card, a link preview, a product rail, and so on. The SDK tells Gravity how much space the slot has and what the page looks like, and Gravity picks the unit type and layout that fit that space. No iframe and no server HTML are involved, except for rich frame units. For the terms on this page, see [Core concepts](https://docs.trygravity.com/introduction/concepts.md).

## How it works

1. **The SDK describes the slot.** With each ad request, the SDK sends the slot's width, the page's font and its average character width, the page's light or dark theme, and the unit capabilities the client can draw. You don't write code for this.
2. **Gravity fits a unit.** Gravity tries the unit types the placement allows, in order, and picks the first one whose layout fits the slot width and maximum height. It sizes generated ad copy for that layout, so the text fits the lines it gets. Copy that the advertiser wrote is served as written.
3. **The SDK draws the unit.** The ad comes back with a [`unit`](#the-unit-object) object. The SDK draws it with the layout that matches the container's live width, and switches layout when the width crosses a breakpoint.

When no unit type fits, the ad is served as a `text` unit, the plain text card. Fit never causes a no-ad. Link cards (the card, post, and unfurl designs) are drawn by the SDK as the `link_preview` type instead of in an iframe.

## Availability

* **Gravity turns ad units on for each placement.** They are off by default, and there's no dashboard setting for them. To turn them on for a placement, email [support@trygravity.com](mailto:support@trygravity.com).
* **The client must send `units.v1`.** A placement gets a unit only when ad units are on for it and the request lists `units.v1` in that placement's [`capabilities`](#request-fields). An SDK version that doesn't send `units.v1`, or a direct API client that doesn't list it, keeps getting the ads it gets today.
* **Nothing else changes.** Pricing, bidding, billing, and tracking are the same. `impUrl` and `clickUrl` work as before, and the impression is still the billing event.

## With the JavaScript and React SDKs

On an SDK version that supports ad units, you change nothing beyond upgrading:

* `@gravity-ai/api` adds the [capabilities](#capabilities) to every placement of `getAds()`. In a browser it also sends the page's font and theme.
* `GravityAd` from `@gravity-ai/react` and `@gravity-ai/ui` draws the `unit` with the layout that fits its container, and re-flows when the width changes. 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.
* When `GravityAd` from `@gravity-ai/ui` fetches the ad itself, it also sends the slot width.

If you request ads on your server, Gravity doesn't know the slot width and assumes a typical one: 300 px for `left_response`, `right_response`, `left_page`, and `right_page`, and 640 px for the other placements. The SDK still draws the layout for the real width. To send the real values, see [Send the slot from the browser](https://docs.trygravity.com/sdks/javascript.md#send-the-slot-from-the-browser).

For the opt-outs, see [Ad units](https://docs.trygravity.com/sdks/javascript.md#ad-units) in the JavaScript SDK guide.

## With the HTTP API

If you call `POST /api/v1/ad` yourself, add the fields below to each placement. All of them are optional. When you draw ads with your own code and don't draw units, don't send `units.v1`, and you keep getting the ad fields you use today.

### Request fields

These fields go on each placement object, next to `placement` and `placement_id`. The engine reads them leniently: a value that isn't valid is dropped, never rejected with a `422`. An object with no valid value is treated as missing.

| Field | Type | Accepted values | When missing |
| - | - | - | - |
| `slot` | `object` | `{ width, height, maxHeight }`, in CSS pixels. Each value is a number above 0 and at most 10000, and is rounded down to an integer. The smaller of `height` and `maxHeight` is the height that a unit must fit in. | Width: 300 for `left_response`, `right_response`, `left_page`, and `right_page`, and 640 for the other placements. Height: no limit. |
| `text` | `object` | `{ fontFamily, avgCharEm: { regular, bold } }`. `fontFamily` is a string of up to 200 characters, without control characters or any of `<>{};\`. `avgCharEm` is the average character width of the font in em, from 0.2 to 1.5, for regular and bold text. | The font comes from `theme.fontFamily`. The character width comes from a table of common fonts (for example Inter, Roboto, Arial, Helvetica, system-ui, Segoe UI, Georgia), else 0.55. |
| `theme` | `object` | `{ scheme, background, foreground, accent, radius, fontFamily }`. `scheme` is `"light"` or `"dark"`. Colors are hex: `#RGB`, `#RGBA`, `#RRGGBB`, or `#RRGGBBAA`. `radius` is a number from 0 to 64. `fontFamily` follows the rules of `text.fontFamily`. | No host theme. |
| `capabilities` | `string[]` | What your client can draw. See [Capabilities](#capabilities). Unknown strings are dropped. | No capabilities. The placement doesn't get a unit. |

```json theme={null}
{
  "placement": "below_response",
  "placement_id": "main",
  "slot": { "width": 640, "maxHeight": 420 },
  "text": { "fontFamily": "Inter", "avgCharEm": { "regular": 0.52, "bold": 0.55 } },
  "theme": { "scheme": "dark", "background": "#111111", "foreground": "#EDEDED", "accent": "#7C5CFF", "radius": 12, "fontFamily": "Inter" },
  "capabilities": ["units.v1", "image"]
}
```

### Capabilities

List only what your client can actually draw. Gravity serves a unit type only when the client lists every capability that the type needs.

| Capability | Meaning | Unit types that need it |
| - | - | - |
| `units.v1` | The client draws data-drawn units. Without it, the placement gets no unit. | `brand_card`, `link_preview`, `product_rail`, `action_card`, `connect_card`, `media_card`, `storefront`, `discover`, `configurator` |
| `image` | The client draws images in units. Without it, units come without images. | None. It turns on images. |
| `blocks.banner` | The client draws a branded hero as a short banner strip. Without it, Gravity sizes that hero at its full height. | None. It changes how a hero is sized. |
| `frame.gfb1` | The client hosts Gravity frames (GFB-1) in a sandboxed iframe. | `rich_frame` |
| `action.prompt` | The client can insert a prompt into its composer. See [Action ads](https://docs.trygravity.com/ai-platforms/action-ads.md). | `action_card` |
| `connect.mcp` | The client can connect an MCP server when the user clicks. | `connect_card` |

The `text` unit needs nothing, and every other type falls back to it.

### The unit object

On a placement with ad units on, each ad gets a `unit` object. The response doesn't include fields that have no value.

| Field | Type | Description |
| - | - | - |
| `type` | `string` | The unit type: `text`, `brand_card`, `link_preview`, `product_rail`, `action_card`, `connect_card`, `media_card`, `storefront`, `discover`, `configurator`, or `rich_frame`. |
| `version` | `number` | The version of the unit type. |
| `layout` | `string` | The ID of the layout that Gravity fitted to the slot width it knew. Not present for `rich_frame`. |
| `layouts` | `object[]` | Every layout of this type, each for a width range: `id`, `minWidth`, `maxWidth` (no upper limit when missing), `arrangement`, `image`, `text`, `padding`, `gap`, `cta`. Draw the one whose range holds the container's live width, so it can differ from `layout` after a resize. Empty for `rich_frame`. |
| `slots` | `string[]` | The parts of the unit to draw, in order, for example `["brand", "image", "headline", "body", "cta"]`. |
| `image` | `boolean` | `true` when Gravity intends the unit to show its image. |
| `theme` | `object` | The unit's look. `surface: "host"` means it uses your page's colors and font. `surface: "brand"` means it uses the advertiser's colors, fonts, and logo from this object. |
| `content` | `object` | The copy and assets: `headline`, `body`, `cta`, `brand`, `logo`, `favicon`, `image`, `imageBg` (a background color for the image), and `domain`. A `product_rail` adds `items` (`title`, `price`, `image`, `clickUrl`), an `action_card` adds `action`, a `connect_card` adds `connect`, and a `rich_frame` adds `frame` (`url`, `sizes`). Some designs also carry `blocks`: data for the parts drawn inside the unit, keyed by block name. |
| `compositionId` | `string` | The ID of the unit's design. |
| `experimentId` | `string` | The ID of the unit experiment, when one is running on the placement. |
| `variantId` | `string` | The experiment arm, as `<experimentId>:<armId>`. |
| `rk` | `string` | The [render key](#render-key). |
| `eventsUrl` | `string` | Where to send [unit events](#unit-events). |

Every field that an ad has today is still on the ad: `adText`, `title`, `brandName`, `cta`, `clickUrl`, `impUrl`, `render`, and the others. A client that doesn't know the unit type or version, or ignores `unit`, draws the plain text card from those fields. Use `clickUrl` for links and load `impUrl` when the ad becomes visible, as for every other ad.

### Render key

`rk` is an opaque string. Pass it through unchanged and don't parse it: Gravity can change its contents at any time. `impUrl` and `clickUrl` already carry it, so impressions and clicks need no extra work. Use it only in [unit events](#unit-events).

### Unit events

If you draw units with your own code, report each one you draw so that Gravity can see which layouts render well. Send one `unit_rendered` event when you draw a unit, or one `unit_failed` event when you can't. The SDKs do this for you.

Send a `POST` to the ad's `unit.eventsUrl` with `Content-Type: text/plain`, so a browser can send it without a CORS preflight (`fetch` with `keepalive`, or `navigator.sendBeacon`). The body is JSON:

```json theme={null}
{
  "now": 1762992000500,
  "events": [
    {
      "rk": "<unit.rk>",
      "event": "unit_rendered",
      "ts": 1762992000120,
      "width": 412,
      "height": 236,
      "layout": "standard",
      "image_drawn": true,
      "text_overflow": false,
      "fallback": false
    }
  ]
}
```

`now` is your client clock in milliseconds when you send the request. Gravity uses it to correct each event's `ts` for clock skew. Without `now`, Gravity records the time it received the event, so always send it. A bare array of events is also accepted.

| Field | Type | Description |
| - | - | - |
| `rk` | `string` | Required. The ad's `unit.rk`, unchanged. |
| `event` | `string` | Required. `"unit_rendered"` or `"unit_failed"`. |
| `ts` | `number` | The time of the event, in milliseconds since the Unix epoch. |
| `width` | `number` | The width you drew the unit at, in pixels. |
| `height` | `number` | The height you drew the unit at, in pixels. |
| `layout` | `string` | The `id` of the layout you drew. |
| `image_drawn` | `boolean` | `true` when you drew the image. |
| `text_overflow` | `boolean` | `true` when the text didn't fit its lines. |
| `fallback` | `boolean` | `true` when you drew the plain text card instead of the unit. |
| `reason` | `string` | Why the unit failed or fell back, for example `unsupported_type`. 1 to 64 characters from `A-Z`, `a-z`, `0-9`, and `_ . : -`. |

Limits and responses:

* Send at most 50 events in one request, and keep the body under 16 KB, as the SDKs do. A body over 32 KB returns `413`.
* Gravity keeps at most 20 events for each impression. When every impression in the request is over that limit, the request returns `429`.
* An event with a missing or changed `rk`, or an unknown `event`, is dropped alone. Another value that isn't valid is stored as empty. The request returns `400` only when no event in it is valid, the body isn't JSON, or it has more than 50 events.
* A request with at least one valid event returns `204`.


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