- Fill: how often a campaign is available for the slot.
- Match quality: how related the ad is to the conversation.
- User experience: how the ad looks and feels in your product.
Why placements are important
- Results for each slot. The dashboard shows impressions, CTR, and revenue for each
placement_id. For example, abelow_responseslot and aright_responsesidebar can earn very different amounts. You can see which slots in your UI earn the most. - Experiments for one slot. Gravity can run experiments on one placement only. For example, Gravity can test a new design in your sidebar and not change your main slot.
- Settings for each slot. Each slot can have its own settings, for example a maximum ad text length (
max_ad_text_charsin the request).
Placement types
Each placement in a request has aplacement type. The type tells Gravity where the slot is in your UI.
Register placements
Create one placement for each surface where your product shows ads. A surface is one place in the UI on one platform. The web chat, the iOS app, the Android app, and a CLI are different surfaces, even when the ad sits below the answer in each of them. Give each one its own placement, so you can see the results of each surface and Gravity can set the format for it. Register each slot before you send it in an ad request. You can register a placement in these ways:- In the dashboard, on the Placements page.
- With the API:
POST /publisher-dashboard/placements. Theslugin the response is theplacement_idto send. - With the dashboard MCP server:
dashboard_create_placement.dashboard_list_placementslists the placements that you already have.
placement_id in an ad request does not create a placement. Don’t send the IDs from the examples on this site, such as YOUR_PLACEMENT_ID or main. Send only the slugs of placements that you created.
A new placement can take some minutes to become active, because Gravity refreshes the placement cache every 5 minutes.
placement_id: your slot name
Each placement needs a placement_id that identifies one slot:
'chat-main', 'mobile-footer', or 'search-result-3'. Each placement_id must be unique in one request. Register it in the dashboard, and then use the same value each time. The dashboard reports revenue and CTR for each placement_id.
Ad units
Each placement has a set of ad units: the formats that Gravity can serve in that slot. You set the units for each placement in the dashboard. On the Placements page, open the placement, and in Ad units, select Choose ad units. The library shows a preview of each unit. The units that are on show as chips under the placement name.
Only web clients can show rich frames and carousels. The iOS, Android, and Python SDKs don’t send
supportsFrames, so they never get these units. React Native can’t show them either, but its server requests use @gravity-ai/api, which sends supportsFrames: true by default: set enableFrames: false for those requests. See Ad formats.
Gravity applies ad unit settings only where it has turned them on. Where it hasn’t, you can still save units in the dashboard, but Gravity’s settings for your account select the format, and the request
units field has no effect. To ask about ad units for your account, email support@trygravity.com.How Gravity selects the unit
For each request, Gravity finds the set of allowed units:- The
unitsfield of the request, when you send it. It replaces the units of every placement in the request. - If the request has no
units, the units that are on for the placements in the request. When a request has more than one placement, Gravity combines their units. Custom design is the exception: it applies to each placement separately. text, which is always in the set.
Override the units for one request
Sendunits when one integration draws ads differently from the placement settings. For example, a client that has no frame support can ask for text and server-rendered designs only:
text. It accepts image_left and image_right as other names for image_side. The official SDKs have no units option, so send it in the body of an HTTP request. See units.
Up to 10 placements in one request
You can request ads for 1 to 10 placements in one call. All the placements use the same auction, so you can request all the slots on a page in one call.No ad is normal
When no campaign matches a slot, that slot gets no ad. When no slot gets an ad, the engine returns204 No Content and the SDK gives an empty ads array. Find the ad for each slot by its placement_id, and show a slot only when it has an ad:
- How related your content is to the active campaigns.
- The
relevancythreshold that you set. See Relevancy tradeoff. - The advertiser budget that is available at that time.
relevancy threshold on the Gravity constructor. But closer matches usually convert better.
Next steps
Experiments
How Gravity runs experiments on your placements.