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

# Changelog

> What's new in the Gravity SDK and pixel — release notes for AI-platform publishers.

Release notes for the JavaScript SDK (`@gravity-ai/api` / `@gravity-ai/react`) and the Gravity pixel (`gr-pix.js`). Entries are publisher-facing — they describe behavior and integration changes, not internal refactors. Latest first.

<Note>
  Upgrading is always a drop-in replacement — `npm install @gravity-ai/api@latest` and redeploy. We don't ship breaking changes to the SDK surface on minor/patch bumps.
</Note>

<Update label="Image ads" description="October 2026 · @gravity-ai/react 1.3.0, @gravity-ai/ui 0.3.0, @gravity-ai/react-native 0.2.0">
  **Ads can now include product images.** When an ad has an image, the response includes `brandImage` and the SDK shows an image card: the photo on one side, the copy on the other. Ads without an image stay as the normal text card. Gravity picks the layout server-side, so there's nothing to configure.

  ```bash theme={null}
  npm install @gravity-ai/react@latest   # or @gravity-ai/ui@latest, @gravity-ai/react-native@latest
  ```

  Using the API directly? Read `brandImage` and design your own card. To get a test image ad on demand, send `"testAd": true, "alwaysReturn": true, "testAdFormat": "image"`.

  Related docs: [Image ads](/engine/contextual-ads#image-ads)
</Update>

<Update label="1.1.9" description="July 19, 2026 · @gravity-ai/react">
  **Banner variant no longer truncates.** The `banner` variant now lays the ad out over two lines — brand row on top, wrapped `adText` below — instead of crushing the title and hard-truncating the copy mid-word. `1.1.8` (July 16) was the first pass at this: it ellipsized the title and stopped the label/CTA from overlapping in narrow containers.

  Nothing to change in your code — upgrade and the banner just renders correctly at narrow widths.

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

  Related docs: [Show ads](/ai-platforms/show-ads)
</Update>

<Update label="0.1.0" description="July 6, 2026 · @gravity-ai/ui">
  **Server-delivered ad rendering.** New package: `@gravity-ai/ui` renders a `renderer_spec` — a declarative layout the engine sends with the ad — through a thin client runtime. Layout changes then ship from Gravity's side without you redeploying, which is what makes creative/format experiments possible on non-React and server-rendered surfaces.

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

  Optional: `@gravity-ai/react`'s `GravityAd` stays the simplest path if you're on React. Full guide: [Server-rendered ads](/sdks/server-rendered-ads).
</Update>

<Update label="1.1.8" description="May 1, 2026 · @gravity-ai/api">
  **New placement types.** `search_result`, `top_page`, `bottom_page`, `left_page`, `right_page`, and `center_page` are now part of the `Placement` type, so TypeScript stops rejecting them when you request page-level or search surfaces.

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

  Related docs: [Placements](/ai-platforms/placements)
</Update>

<Update label="1.1.7" description="April 22, 2026 · @gravity-ai/api">
  **Pixel and SDK now auto-wire end to end.** If both are loaded on the page, the SDK pulls four values off `window.gravityPixel` automatically on every `gravityContext()` call — no glue code.

  | Pixel method | Flows into | Why you care |
  | - | - | - |
  | `getVisitorId()` | `user.gruid` | Stable first-party visitor ID — used for attribution and higher-value auctions |
  | `getSessionId()` | Top-level `sessionId` | You can **drop your own `sessionId` parameter**; the pixel's 30-min rolling session ID is used unless you pass one explicitly |
  | `getClickId()` | `user.grclid` | Inbound Gravity click ID when a user arrives from a Gravity ad — surfaces in `engine_events.request_context.user.grclid` for attribution reporting |
  | `getGraid()` | `user.graid` | Inbound ad identifier, same attribution path |

  Caller-supplied values always win, so existing code that explicitly passes `sessionId` keeps working unchanged.

  **What to do**: upgrade to `1.1.7`, confirm the pixel is installed ([install guide](/ai-platforms/pixel)), optionally drop your own `sessionId` plumbing. If you're not running experiments yet, this is a good checkpoint to start — see [Experiments](/ai-platforms/experiments).

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

  Related docs: [Pixel](/ai-platforms/pixel) · [Request ads](/ai-platforms/request-ads) · [Experiments](/ai-platforms/experiments)
</Update>

<Update label="1.1.6" description="March 10, 2026 · @gravity-ai/api + @gravity-ai/react">
  **PII auto-hashing for attribution.** The SDK now hashes emails/phone numbers client-side (SHA-256, normalized) before they reach the wire, and the pixel's `gruid` is surfaced safely through the SDK so dashboards can attribute conversions without publishers having to think about privacy plumbing.

  No integration changes required — this shipped as internal hardening. Advertiser-side match rates go up, you don't have to do anything.
</Update>

<Update label="1.1.5" description="February 22, 2026 · @gravity-ai/api + @gravity-ai/react">
  **Ad composition experimentation framework.** The SDK and engine now support A/B testing different ad *compositions* (which props the server sends, which layout the client renders) on a per-request basis, controlled from the Gravity dashboard.

  If you want to run UI variants without shipping code — try different CTA copy, card vs. pill layouts, inline vs. below-response placements — this is the unlock. Start at [Experiments](/ai-platforms/experiments).
</Update>

<Update label="1.1.0 – 1.1.4" description="January 2026">
  Bucket of bug fixes and polish:

  * Fixed hardcoded `status: 200` in `gravityAds` success path
  * Fixed `setAd` hover cleanup and prop-spread order in `gravityContext`
  * Fixed Windows URL injection and a timeout `0` falsy-check bug
  * Swallowed `execFile` errors in `openUrl` to avoid crashing host apps
  * Deprecated the legacy `Client` + `AdParams` API in favor of `Gravity` + `gravityContext`

  If you're on `1.1.0`+ you've got these already. If you're still on `1.0.x`, upgrade when convenient — none of these are security-critical but the DX is materially better.
</Update>

<Update label="1.0.x (Jan 2026) and earlier" description="Pre-January 2026">
  Pre-`1.1.x` history is available as version tarballs on npm: [`@gravity-ai/api` versions](https://www.npmjs.com/package/@gravity-ai/api?activeTab=versions) · [`@gravity-ai/react` versions](https://www.npmjs.com/package/@gravity-ai/react?activeTab=versions). The short version: `0.0.x → 0.1.x → 1.0.0` covered the initial public API, ad card + impression logic, the publisher playground, and the first round of `@gravity-ai/react` templates. If you're still pinned anywhere in this range, upgrade straight to `latest` — the API surface is stable across the `1.x` line.
</Update>

## How versions ship

* **`@gravity-ai/api`** and **`@gravity-ai/react`** are versioned independently. Most publishers only need `@gravity-ai/api`; `@gravity-ai/react` is a thin wrapper with pre-built components.
* **`latest`** on npm always reflects the newest stable release. We do not ship breaking changes to published APIs on `1.x` minor/patch bumps.
* The **pixel** (`gr-pix.js`) is served from `https://code.trygravity.ai/gr-pix.js` and updates in place — you don't pin a version, you always get the current build. Changes are backwards-compatible.

## Questions or issues?

* **Integration help** — see [Integration guide](/ai-platforms/integration-guide) or email [support@trygravity.ai](mailto:support@trygravity.ai).
* **Experiment setup** — see [Experiments](/ai-platforms/experiments).
* **Going live checklist** — see [Going live](/ai-platforms/going-live).


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