Skip to main content
This page defines the terms that the Gravity docs use. Other pages link to the definitions here.

Roles

AI platform. An app that shows Gravity ads next to a conversation with a model, for example a chat app, a coding assistant, or an AI search product. The API and the SDKs also call an AI platform a “publisher”. An AI platform gets a share of the revenue from the ads it shows. Advertiser. A company that runs ad campaigns on the Gravity network. An advertiser sets the budget, the ad content, and the targets, and pays for impressions.

Ad serving

Ad request. One call to POST /api/v1/ad. It sends the recent conversation messages, a session ID, and one or more placements. See Contextual ads. Contextual matching. Gravity selects ads mainly from the content of the current conversation. Campaign targeting, such as location and advertiser audiences, can also apply when the user’s consent allows it. The engine compares the recent messages with active campaigns, runs an auction, and writes ad text that fits the conversation. Auction. The step where the engine compares the campaigns that match a request and selects the ad to show. Relevancy. A number from 0.0 to 1.0 that sets the minimum match quality for an ad. A lower value returns more ads with weaker matches. The SDKs send 0.2 by default. No-fill. The result when no ad matches a request. The API returns HTTP 204 with an empty body, and the SDKs return an empty ads list. Test ad. An ad that the engine returns when the request has testAd: true. Test ads do not bill. The SDKs send test requests until you set production to true.

Placements

A placement is a named slot in your UI where an ad can show. Each ad request names one or more placements, and each impression belongs to one placement. Each placement in a request has two values:
  • placement: the slot type. The standard types are above_response, below_response, inline_response, left_response, right_response, search_result, top_page, bottom_page, left_page, right_page, and center_page.
  • placement_id: your stable ID for the slot. Each placement_id must be unique in one request.
Placements give you per-slot reports in the dashboard, and they let Gravity run tests on one slot at a time. Register each slot in your Gravity dashboard under AI platforms → Placements. Then send the slot’s placement_id in your ad request. The placement_id does not create a placement. If your account has registered placements, the engine can drop slots with an unregistered placement_id from the request. See the Placements guide.

Measurement and billing

Impression. One view of an ad. An impression counts when your app loads the ad’s impUrl at the time the ad becomes visible. The official SDK components do this for you. Click. A user tap on an ad. Always send the user to the ad’s clickUrl, not to url, so that Gravity can record the click. CPM. Cost per mille: the price of 1,000 impressions. Publishers are paid on CPM, and advertisers can buy on CPM.

Sessions

A session is one conversation. Send the same sessionId for all ad requests in one chat thread. Gravity uses the session for frequency limits, experiment groups, and reports.

Ad designs

Server-rendered design. A layout for a placement that Gravity sends with the ad in the renderer_spec field. The official SDK components draw it for you, so Gravity can change the design of a placement without a code change in your app. See Server-rendered ads. Experiment. A test that Gravity runs on ad designs or formats to find what works best for your traffic. The SDK components handle experiments with no code from you. See Experiments.

Pixels

The Gravity pixel is a small first-party script. It has two uses:

On an AI platform

You install it on your site or in your in-app browser. It links a click that opens in a WebView back to the impression that caused it.

On an advertiser landing page

The advertiser installs it on their site. It sends a conversion event when a user completes an action, for example a purchase or a signup.
Both pixels are first-party. They do not share data across unrelated sites.

Privacy

Consent. The optional consent object in an ad request carries the privacy choices of the user (GDPR, US privacy, and Global Privacy Control). When the user does not give consent, Gravity serves contextual ads only and does not process user identifiers. Optional hashed identifiers (email and phone) improve attribution. See Data quality for what to send and how to hash it.