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

# Core concepts

> The vocabulary used across the Gravity docs.

## Roles

<CardGroup cols={2}>
  <Card title="AI platform" icon="newspaper">
    An AI app that shows ads — chat UIs, coding assistants, search products, consumer AI. Earns revenue share on every ad served.
  </Card>

  <Card title="Advertiser" icon="bullhorn">
    A brand running ad campaigns. Sets budgets, creative, and bidding. Pays for impressions.
  </Card>
</CardGroup>

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

<CardGroup cols={2}>
  <Card title="On an AI platform" icon="mobile" href="/ai-platforms/pixel">
    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.
  </Card>

  <Card title="On an advertiser landing page" icon="cart-shopping" href="/advertisers/pixel">
    Installed on the advertiser's site. Fires a conversion event when a user completes an action (purchase, signup). Powers conversion reporting.
  </Card>
</CardGroup>

Both are first-party. They do not share data across unrelated sites.

## 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 stable `placement_id` per slot. Either way, the `placement_id` ties dashboard analytics back to the spot in your UI.

See the [Placements guide](/ai-platforms/placements) 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](/ai-platforms/experiments).

## Sessions

A **session** is a conversation. The `sessionId` 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 `userId` per 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.

Hashed email specifically is the difference between "we only count the direct clicks" and "we also count the users who saw the ad, remembered the brand, and came back later." Worth wiring in when you can.

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