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
Callget with kind: "inventory_source", the source’s id and any of
capabilities, creativeFormats and publisherProperties:
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:sourceIdandfilter.selectorTypeare required. A search without either is refused. TakeselectorTypefrom theselectorTypesthatcapabilitieslists.querynarrows the list by name.filter.parentIdlists the children of one selector.filter.mediaTypeisdisplayorvideo, andfilter.environmentTypeisBROWSERorVIDEO_PLAYER. Both are optional. Any other value is refused withVALIDATION_ERROR.include: ["adServerMetadata"]is for the Apostra app and gives an agent nothing to read. See Details for the Apostra app.limitis at most 100. When more rows match, the answer hasnextCursor. Send it back ascursorwith the samesourceIdand filters. If the ad server’s cursor is longer than 2048 characters, it is not returned: the answer hasnextCursorTooLong: trueandtruncated: trueinstead. Narrow the search withquery,filter.parentId,filter.mediaTypeorfilter.environmentType.- The kind is explicit-only. A search with no
kindnever reads selectors, andgetdoes not read a selector.
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 frominclude_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,
trueorfalse, is kept as sent. - The rule applies only to
ad_unitselectors of a product whoseinventory.execution.adapterisgoogle_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 inselectorOptionsAdded. - 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.
Related
- Create and manage seller products uses these values in
save_wholesale_product. - Sellers on the V3 tool surface lists every
getkind and include a seller account reads.