Skip to main content
A placement is a named slot in your UI where an ad can show. This page tells you how to select placement types, register placements, and send them in ad requests. Placements control three things that have a large effect on your revenue:
  1. Fill: how often a campaign is available for the slot.
  2. Match quality: how related the ad is to the conversation.
  3. 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, a below_response slot and a right_response sidebar 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_chars in the request).

Placement types

Each placement in a request has a placement 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: A new 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.
Register a placement before you send it. When your account has one or more placements, the engine keeps only your active placements in each request. It accepts the slug or the UUID of the placement. If a request has registered and unregistered placement_id values, the engine removes the unregistered ones. Those slots get no ad, and the response shows no error.There are two exceptions, for backward compatibility. If your account has no placements, the engine does not filter. If no placement_id in the request is registered, the engine serves the request with all its placements.
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:
Use a stable string that identifies the slot in your UI, for example '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:
  1. The units field of the request, when you send it. It replaces the units of every placement in the request.
  2. 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.
  3. text, which is always in the set.
Gravity then serves a unit from that set that the request and the ad can show. When they can’t show it (no frame support, no brand image, too few product cards), Gravity falls back to another unit in the set, and at the end to text. A placement with no units chosen (Not configured in the dashboard) keeps serving as before: Gravity’s settings for your account select the format. A placement that has units chosen but not Custom design gets no server-rendered design. This includes the design of the placement, the default design of Gravity, and designs from experiments.

Override the units for one request

Send units 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:
Gravity ignores unit IDs that it doesn’t know, and it always adds 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 returns 204 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:
These items change the fill rate (the part of requests that get an ad):
  • How related your content is to the active campaigns.
  • The relevancy threshold that you set. See Relevancy tradeoff.
  • The advertiser budget that is available at that time.
To get more ads, set a lower relevancy threshold on the Gravity constructor. But closer matches usually convert better.

Next steps

Experiments

How Gravity runs experiments on your placements.