Skip to main content
Before you author a wholesale product on an ad-server source, you need to know what the source supports, which creative formats and publisher properties it can carry, and which ad units, placements or segments you can sell. V3 reads each of these without a tool of its own: three include values on get for the small facts of one source, and one search kind for the long, paged list of selectors. Every read on this page needs a source with a managed ad-server connection, such as Google Ad Manager or FreeWheel. Pass the source’s own sourceId, as search({ "kind": "inventory_source" }) returns it. You never pass an ad-server connection id. A read changes nothing. Browsing a selector does not create, import or reserve anything: it gives you the values a product’s inventory is written from.

Read the source’s capabilities, formats and properties

Call get with kind: "inventory_source", the source’s id and any of capabilities, creativeFormats and publisherProperties:
A get that names none of the three returns what it returned before. If the source has no managed ad-server connection, or the connection cannot answer, that include is left out of the result and listed in unavailableIncludes with its reason. The other includes you asked for are still returned. A source that is not yours is not found, as for any get.

capabilities

What the ad-server adapter declares. These are the adapter’s own facts, not AdCP’s, so the names are the adapter’s, in camelCase. What “not stated” looks like. adapter, selectionRequirements and overlaySupportCeiling are absent when the adapter did not state them, so you can tell “not stated” from “stated as empty”. The difference matters: a FreeWheel product needs at least one package, and that rule applies whenever the adapter states no selection requirements of its own, while a stated [] means the adapter really has none. selectorTypes, pricingModels, targetingDimensions and optimizationGoals are empty when the adapter does not state them, because nothing depends on the difference. If the adapter states a list of selection requirements and any entry in it cannot be read, Apostra does not serve a partial list or []. It leaves capabilities out of the result and lists it in unavailableIncludes with that reason. Treat the requirements as unknown until they can be read. overlaySupportCeiling uses AdCP’s own names and values, in snake_case. A dimension the adapter applies is true. geo_metros and geo_metros_exclude carry { "systems": [...] } with the adapter’s AdCP metro systems, such as nielsen_dma, and geo_postal_areas and geo_postal_areas_exclude carry AdCP’s country-keyed postal map, such as { "US": ["zip"] }. A metro or postal dimension whose systems the adapter does not state is left out, because true would promise every system. The place dimensions (geo_places and geo_places_exclude) are never carried: AdCP’s place declaration needs catalog versions that no adapter states. Send overlay_support on save_wholesale_product only within this ceiling.

creativeFormats

The creative formats the source can carry, as AdCP format declarations. A format is named by format_kind and params, and has no agent URL. The source’s older format list, which names formats by agent URL and id, is not served. To use a format in a product, send its format_option_id, format_kind and params back in formatOptions on save_wholesale_product, unchanged. Do not send display_name, dimensions, assetTypes or requirements: a save does not take them. An option whose params name a legacy agent URL or format id is not served, because that is the older identity this read does not carry. An option whose requirements name one is served without requirements and with requirementsOmitted: true: its canonical identity carries no agent URL, so nothing this read returns names one.

publisherProperties

The properties the source can sell, and the selectors the ad server has already decided are valid. The result has two lists, properties and selectors. A property uses AdCP’s Property names: publisher_domain, property_id, identifiers (a list of type and value) and tags. AdCP also requires property_type and name. The ad server does not always state them, so a property carries only what the source stated. The ad server’s display text for a property is label, kept beside the AdCP fields and read-only. It is not AdCP’s name. A selector uses AdCP’s PublisherPropertySelector: selection_type (all, by_id or by_tag), publisher_domain, property_ids and property_tags. It is the shape inventory.publisher_properties takes on save_wholesale_product, so send one back unchanged. Its label is the ad server’s own text and is read-only. Apostra returns these as stored and does not check them against the AdCP schema when you read them. The check happens when you save a product.

Browse the source’s selectors

Selectors are the ad units, placements, segments and other items the ad server declares. A list can run to thousands, so it is a search, not an include:
  • sourceId and filter.selectorType are required. A search without either is refused. Take selectorType from the selectorTypes that capabilities lists.
  • query narrows the list by name. filter.parentId lists the children of one selector.
  • filter.mediaType is display or video, and filter.environmentType is BROWSER or VIDEO_PLAYER. Both are optional. Any other value is refused with VALIDATION_ERROR.
  • include: ["adServerMetadata"] is for the Apostra app and gives an agent nothing to read. See Details for the Apostra app.
  • limit is at most 100. When more rows match, the answer has nextCursor. Send it back as cursor with the same sourceId and filters. If the ad server’s cursor is longer than 2048 characters, it is not returned: the answer has nextCursorTooLong: true and truncated: true instead. Narrow the search with query, filter.parentId, filter.mediaType or filter.environmentType.
  • The kind is explicit-only. A search with no kind never reads selectors, and get does not read a selector.
Each row has the ad server’s own facts: A row with no name is kept: name is null, and the text line shows the externalId in its place. No row is dropped for lacking a name. The page has one more field, adServerCount: the ad server’s own count for the search. It is present only when the ad server states a non-negative integer. It is the ad server’s number as stated, and it is not always an exact total across pages, because some ad servers fill it with the size of the page they just returned. Use nextCursor, not adServerCount, to know whether more rows exist.

Ad units with children

A Google Ad Manager ad unit reads its descendants from include_descendants in the selector’s options. When you save a product with save_wholesale_product and a Google Ad Manager ad_unit selector does not state include_descendants, Apostra reads that ad unit’s hasChildren from the ad server and sets include_descendants: true if it says the ad unit has children. Otherwise the option is left as you sent it.
  • A value you send, true or false, is kept as sent.
  • The rule applies only to ad_unit selectors of a product whose inventory.execution.adapter is google_ad_manager. Placements, other selector types and other adapters are never changed, and nothing is read for them.
  • If Apostra cannot tell (the ad server does not answer, the selector is not found, or the ad server states no hasChildren), the option is left unset.
  • A dry run (dryRun: true) shows what a save would add in selectorOptionsAdded.
  • Products you saved earlier are not changed. The rule applies when a save sends the selector.

Details for the Apostra app

include: ["adServerMetadata"] asks for the ad server’s own details for each row: ad sizes, ad unit ids, property, placement and mapping suggestions. The Apostra app’s Components and Inventory Selector widgets read them. They are served only in the result’s _meta, under adServerMetadata, and never in structuredContent or in the text, so an agent that asks gets nothing it can read. A search that does not ask carries none. The value is valid only for kind: "inventory_source_item". The entry is { rows, adServerMetadataTruncated? }. rows maps a row’s selectorType and externalId, joined by a colon, to an object with these keys, each present only when the ad server sent it: Only numbers, those status words and short plain tokens are served, never free text. A token is an id or a domain made of letters, digits and ., _, : or -: at most 64 characters for an id and 253 for a domain. A value that is not a token is left out and never cut, because a cut id is a different id. Names, paths, labels and the evidence text behind a mapping suggestion are not served. The entry is bounded. A row keeps at most 32 sizes, 64 ad unit ids and 16 candidate ids, and its object is kept to 1,024 characters of JSON by dropping keys from the end of the order above. Anything left out sets truncated: true inside that row’s object, which means the object is partial. This is not the row’s own truncated. The whole entry is kept to 32,768 characters: a row past that has no entry in rows, and the entry says adServerMetadataTruncated: true.