> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.ai/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="Lead-form ad units" description="May 2026 · @gravity-ai/react + @gravity-ai/api">
  **Capture leads inline.** Advertisers can now run **lead-form ad units** — the user fills in a short form (email, phone, a question or two) right in your chat UI instead of clicking through. `GravityAd` renders it automatically whenever the served ad carries a `leadForm` envelope; the engine stores the lead and fires a conversion so attribution and CPA billing just work.

  Two things to add to your render call so lead forms work: **`sessionId`** (must match the ad request) and **`apiKey`**. The same `GravityAd` keeps rendering normal click-through ads when there's no form, so this is a one-time, backwards-compatible change.

  ```tsx theme={null}
  <GravityAd ad={ads[0]} sessionId={sessionId} apiKey={process.env.GRAVITY_API_KEY} />
  ```

  Display modes (`inline`, `modal-center`, `modal-bottom-right`), identity pre-fill, and full styling hooks are covered in the new [Lead-form ads guide](/ai-platforms/lead-forms). The lower-level `GravityLeadFormAd` component is also exported for direct use.

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

  Related docs: [Lead-form ads](/ai-platforms/lead-forms) · [Show ads](/ai-platforms/show-ads)
</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).