How it works
- 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.
- 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.
- The SDK draws the unit. The ad comes back with a
unitobject. The SDK draws it with the layout that matches the container’s live width, and switches layout when the width crosses a breakpoint.
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 listsunits.v1in that placement’scapabilities. An SDK version that doesn’t sendunits.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.
impUrlandclickUrlwork 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/apiadds the capabilities to every placement ofgetAds(). In a browser it also sends the page’s font and theme.GravityAdfrom@gravity-ai/reactand@gravity-ai/uidraws theunitwith 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-accentand--gravity-radiusset its button color and corner radius.- When
GravityAdfrom@gravity-ai/uifetches the ad itself, it also sends the slot width.
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 callPOST /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 toplacement 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 aunit 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 oneunit_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 unknownevent, is dropped alone. Another value that isn’t valid is stored as empty. The request returns400only 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.