Skip to main content
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.
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.
​
Lead-form ad units
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.
<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. The lower-level GravityLeadFormAd component is also exported for direct use.
npm install @gravity-ai/react@latest
Related docs: Lead-form ads · Show ads
​
1.1.7
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 methodFlows intoWhy you care
getVisitorId()user.gruidStable first-party visitor ID — used for attribution and higher-value auctions
getSessionId()Top-level sessionIdYou can drop your own sessionId parameter; the pixel’s 30-min rolling session ID is used unless you pass one explicitly
getClickId()user.grclidInbound Gravity click ID when a user arrives from a Gravity ad — surfaces in engine_events.request_context.user.grclid for attribution reporting
getGraid()user.graidInbound 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), optionally drop your own sessionId plumbing. If you’re not running experiments yet, this is a good checkpoint to start — see Experiments.
npm install @gravity-ai/api@1.1.7
Related docs: Pixel · Request ads · Experiments
​
1.1.6
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.
​
1.1.5
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.
​
1.1.0 – 1.1.4
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.
​
1.0.x (Jan 2026) and earlier
Pre-January 2026
Pre-1.1.x history is available as version tarballs on npm: @gravity-ai/api versions · @gravity-ai/react 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.

​
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?