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.
Roles
AI platform
An AI app that shows ads — chat UIs, coding assistants, search products, consumer AI. Earns revenue share on every ad served.
Advertiser
A brand running ad campaigns. Sets budgets, creative, and bidding. Pays for impressions.
Ad matching
Contextual — Ads are matched to the content of the conversation. The engine embeds recent messages, retrieves relevant campaigns, runs an auction, and generates creative tuned to the conversation.Billing
| Model | How it works |
|---|---|
| CPM | Cost per 1,000 impressions. Gravity’s public billing model. |
Pixels
The Gravity pixel is a lightweight first-party script with two install surfaces:On an AI platform
Installed on your site or inside your in-app browser. Links clicks that open inside a WebView back to the originating impression, so attribution survives the in-app → landing-page transition.
On an advertiser landing page
Installed on the advertiser’s site. Fires a conversion event when a user completes an action (purchase, signup). Powers conversion reporting.
Placements
A placement is a named slot in your UI where an ad can appear. Placements are a first-class concept in Gravity because they’re how we understand where ads are rendering, how they perform per-slot, and how we split traffic for testing.Why they matter
- Per-slot reporting. Dashboard shows impressions, CTR, and revenue per
placement_id. You learn which spots in your UI carry their weight and which don’t. - Scoped experiments. We can run experiments targeted to a specific placement — test a new treatment in your right-rail without touching your below-response slot.
- Auto-optimization. The engine learns which ad formats work best per placement over time and leans into the winners.
Standard placement types
Standard keys cover most UI layouts:above_response, below_response, inline_response, left_response, right_response, plus page-level options (search_result, top_page, bottom_page, left_page, right_page, center_page). Every ad request names its placements and an identifier for each slot. Every impression is attributed to one.
How to set them up
Create placement slots in your Gravity dashboard under AI platforms → Placements, or declare them inline in your ad request with a stableplacement_id per slot. Either way, the placement_id ties dashboard analytics back to the spot in your UI.
See the Placements guide for full details.
Variants
A variant is a specific visual treatment —card, minimal, inline, spotlight, pill, banner, hyperlink, etc. The SDK ships 20+ variants out of the box. The GravityAd React component picks one based on the variant prop; the engine can also assign one via an experiment.
Experiments
An experiment is a traffic split across multiple variants. The engine assigns each session deterministically; impressions are attributed to the variant automatically. Experiments are how Gravity finds what converts best for your traffic over time, without requiring you to change code. See Experiments.Sessions
A session is a conversation. ThesessionId you pass to gravityContext() groups related ad requests together for frequency capping, experiment bucketing, and reporting. Usually one chat thread = one session.
Data quality
The richer the signal you send with each ad request, the better Gravity can match, report, and attribute. Most AI platforms leave revenue on the table by sending the minimum. High-value signals, in order of impact:- Hashed email. If your app knows the user’s email, passing a SHA-256 hash on the ad request unlocks view-through attribution — we can tie a later purchase or signup on an advertiser’s site back to an impression that didn’t get clicked directly. This is typically the single biggest lever on reported revenue.
- Stable user identifier. Even without email, a consistent
userIdper user lets us dedupe requests, cap frequency intelligently, and build smarter matching over time. - Rich conversation context. Passing the recent messages (not just the latest one) gives the engine better signal for contextual matching.
- Device + locale. Auto-included when you use the SDK’s
gravityContext(), but worth confirming if you’re calling the API directly — country, device type, and timezone all feed into relevance.
Claim flow
When a platform provisions a Gravity account on behalf of its user (see:Partner API, currently not public), the end user claims their account by signing in and linking it to their Gravity profile. Claim unlocks dashboard access, payout configuration, and full control.