Core concepts

​

Roles

​

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

​

Pixels

The Gravity pixel is a lightweight first-party script with two install surfaces: 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, then send each slot’s stable placement_id in your ad request. The placement_id correlates a request slot to a registered placement and ties dashboard analytics back to the spot in your UI — it doesn’t create the placement, and unregistered ids are filtered out of the auction. See the Placements guide for full details.

​

Ad designs

Gravity manages each placement’s design. Official SDK components apply the design and tracking automatically.

​

Experiments

Gravity can test placement designs without publisher code changes. See 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.