Skip to main content
An ad unit is an ad that Gravity describes as data and the SDK draws in your page: a brand card, a link preview, a product rail, and so on. The SDK tells Gravity how much space the slot has and what the page looks like, and Gravity picks the unit type and layout that fit that space. No iframe and no server HTML are involved, except for rich frame units. For the terms on this page, see Core concepts.

How it works

  1. The SDK describes the slot. With each ad request, the SDK sends the slot’s width, the page’s font and its average character width, the page’s light or dark theme, and the unit capabilities the client can draw. You don’t write code for this.
  2. Gravity fits a unit. Gravity tries the unit types the placement allows, in order, and picks the first one whose layout fits the slot width and maximum height. It sizes generated ad copy for that layout, so the text fits the lines it gets. Copy that the advertiser wrote is served as written.
  3. The SDK draws the unit. The ad comes back with a unit object. The SDK draws it with the layout that matches the container’s live width, and switches layout when the width crosses a breakpoint.
When no unit type fits, the ad is served as a text unit, the plain text card. Fit never causes a no-ad. Link cards (the card, post, and unfurl designs) are drawn by the SDK as the link_preview type instead of in an iframe.

Availability

  • Gravity turns ad units on for each placement. They are off by default, and there’s no dashboard setting for them. To turn them on for a placement, email support@trygravity.com.
  • The client must send units.v1. A placement gets a unit only when ad units are on for it and the request lists units.v1 in that placement’s capabilities. An SDK version that doesn’t send units.v1, or a direct API client that doesn’t list it, keeps getting the ads it gets today.
  • Nothing else changes. Pricing, bidding, billing, and tracking are the same. impUrl and clickUrl work as before, and the impression is still the billing event.

With the JavaScript and React SDKs

On an SDK version that supports ad units, you change nothing beyond upgrading:
  • @gravity-ai/api adds the capabilities to every placement of getAds(). In a browser it also sends the page’s font and theme.
  • GravityAd from @gravity-ai/react and @gravity-ai/ui draws the unit with the layout that fits its container, and re-flows when the width changes. The unit takes the page’s light or dark surface, text color, and font. --gravity-accent and --gravity-radius set its button color and corner radius.
  • When GravityAd from @gravity-ai/ui fetches the ad itself, it also sends the slot width.
If you request ads on your server, Gravity doesn’t know the slot width and assumes a typical one: 300 px for left_response, right_response, left_page, and right_page, and 640 px for the other placements. The SDK still draws the layout for the real width. To send the real values, see Send the slot from the browser. For the opt-outs, see Ad units in the JavaScript SDK guide.

With the HTTP API

If you call POST /api/v1/ad yourself, add the fields below to each placement. All of them are optional. When you draw ads with your own code and don’t draw units, don’t send units.v1, and you keep getting the ad fields you use today.

Request fields

These fields go on each placement object, next to placement and placement_id. The engine reads them leniently: a value that isn’t valid is dropped, never rejected with a 422. An object with no valid value is treated as missing.

Capabilities

List only what your client can actually draw. Gravity serves a unit type only when the client lists every capability that the type needs. The text unit needs nothing, and every other type falls back to it.

The unit object

On a placement with ad units on, each ad gets a unit object. The response doesn’t include fields that have no value. Every field that an ad has today is still on the ad: adText, title, brandName, cta, clickUrl, impUrl, render, and the others. A client that doesn’t know the unit type or version, or ignores unit, draws the plain text card from those fields. Use clickUrl for links and load impUrl when the ad becomes visible, as for every other ad.

Render key

rk is an opaque string. Pass it through unchanged and don’t parse it: Gravity can change its contents at any time. impUrl and clickUrl already carry it, so impressions and clicks need no extra work. Use it only in unit events.

Unit events

If you draw units with your own code, report each one you draw so that Gravity can see which layouts render well. Send one unit_rendered event when you draw a unit, or one unit_failed event when you can’t. The SDKs do this for you. Send a POST to the ad’s unit.eventsUrl with Content-Type: text/plain, so a browser can send it without a CORS preflight (fetch with keepalive, or navigator.sendBeacon). The body is JSON:
now is your client clock in milliseconds when you send the request. Gravity uses it to correct each event’s ts for clock skew. Without now, Gravity records the time it received the event, so always send it. A bare array of events is also accepted. Limits and responses:
  • Send at most 50 events in one request, and keep the body under 16 KB, as the SDKs do. A body over 32 KB returns 413.
  • Gravity keeps at most 20 events for each impression. When every impression in the request is over that limit, the request returns 429.
  • An event with a missing or changed rk, or an unknown event, is dropped alone. Another value that isn’t valid is stored as empty. The request returns 400 only when no event in it is valid, the body isn’t JSON, or it has more than 50 events.
  • A request with at least one valid event returns 204.