verve-metadata

verve-metadata is the JSON every Ad in a GET /v1alpha2/ads response carries in its Extension of that type, inside CDATA. Keys are the snake_case field names below. A key with no value is left out. Ignore keys you do not recognise: new ones can appear, and so can enum values.

Download the JSON Schema (draft 2020-12) to validate a payload in your own tests. The expires_at field uses the date-time format, so the validator must support formats. In ajv, add ajv-formats.

Field	Type	Description
request_id required	string	request_id groups the ads of one /ads response, for correlation and debugging. Always present.
campaign_id	string	campaign_id is the campaign of that flight, for attribution and debugging. Absent when the ad has none.
expires_at	stringformat: date-time	expires_at is when the ad stops being valid, as an RFC 3339 timestamp in UTC, to the whole second. Drop the ad at slot time once past it. An online response carries a much shorter horizon than an offline one.
flight_id	string	flight_id is the Verve flight behind the ad, for attribution. Absent when the ad comes from no Verve flight.
source	string	source is the kind of source that served the ad: Verve's own ad server, an SSP or a CMS. Known values:SOURCE_TYPE_AD_SERVERSOURCE_TYPE_SSPSOURCE_TYPE_CMS
source_id	string	source_id is the specific source the ad came from, such as one CMS, SSP or ad server. Offline, group stored ads by it to keep the player's source mix.
audience	object	audience is the flight's dynamic targeting, for offline matching against the player's detected shoppers, cart and weather. Absent for untargeted ads; an ad with no audience matches everyone.
Audience is the targeting of an ad. An ad matches when any one group matches. A group matches when all its conditions match. Field Type Description targeting_groups array of object targeting_groups are OR'd: the ad matches when any one group matches. TargetingGroup matches when all of its conditions match. Field Type Description conditions array of object conditions are AND'd. TargetingCondition is one criterion. Exactly one member is set. Field Type Description demographic object demographic matches when a detected shopper fits any listed profile. DemographicCondition targets shoppers by demographics detected via vision sensors. Only applies to devices equipped with vision sensors. Profiles are OR'd: the condition matches if any single profile matches the detected shopper. Field Type Description profiles array of object profiles are the slices to match; any one is enough. DemographicProfile is a single demographic slice. Unset fields match any value. Field Type Description age_range string age_range is the age bracket to match. Known values:AGE_RANGE_18_20AGE_RANGE_21_24AGE_RANGE_25_29AGE_RANGE_30_34AGE_RANGE_35_39AGE_RANGE_40_44AGE_RANGE_45_49AGE_RANGE_50_54AGE_RANGE_55_59AGE_RANGE_60_64AGE_RANGE_65_69AGE_RANGE_70_74AGE_RANGE_75_PLUS gender string gender is the gender to match. Known values:GENDER_FEMALEGENDER_MALEGENDER_OTHERGENDER_UNKNOWN group_size object group_size compares the number of people the vision sensor detects. CountComparison expresses a comparison against a numeric count value. An absent operator matches any count. Field Type Description operator string operator is the comparison to apply. Known values:COUNT_COMPARISON_OPERATOR_EQUALCOUNT_COMPARISON_OPERATOR_LESS_THANCOUNT_COMPARISON_OPERATOR_LESS_THAN_OR_EQUALCOUNT_COMPARISON_OPERATOR_GREATER_THANCOUNT_COMPARISON_OPERATOR_GREATER_THAN_OR_EQUAL value integer value is the number to compare against. device object device matches on the shopper's cart. DeviceCondition matches on the shopper's cart. Field Type Description basket object basket matches when the cart holds any listed sku or item. BasketFilter matches items currently in the shopper's active cart. skus and items are OR'd: a match on either satisfies the filter. Field Type Description items array of string items is an open list of product names or categories in the shopper's cart. skus array of string skus are the product SKUs to match. store object store matches on the store's current weather. StoreCondition matches on the store's current weather. Field Type Description weather_types array of string weather_types match when the current weather is any one of them. Known values:WEATHER_TYPE_SUNNYWEATHER_TYPE_CLOUDYWEATHER_TYPE_RAINYWEATHER_TYPE_SNOWWEATHER_TYPE_ABOVE_20_CELSIUSWEATHER_TYPE_BELOW_10_CELSIUS
frequency_caps	array of object	frequency_caps are the flight's per-player play limits, for the player to enforce offline. Every entry applies at once. Count plays per flight_id, never per ad. Absent for uncapped flights and on online responses.
FrequencyCap limits how often one player may show the flight in one window. Field Type Description limit integer limit is the most plays allowed within the window. window string window is the period the limit applies to, in UTC. FREQUENCY_CAP_WINDOW_MINUTE and FREQUENCY_CAP_WINDOW_THIRTY_MINUTES look back 60 seconds and 30 minutes from now. FREQUENCY_CAP_WINDOW_HOUR is the current clock hour, FREQUENCY_CAP_WINDOW_DAY the current calendar day, and FREQUENCY_CAP_WINDOW_WEEK the current ISO week, which starts on Monday. FREQUENCY_CAP_WINDOW_FLIGHT is the flight's whole lifespan. Known values:FREQUENCY_CAP_WINDOW_MINUTEFREQUENCY_CAP_WINDOW_THIRTY_MINUTESFREQUENCY_CAP_WINDOW_HOURFREQUENCY_CAP_WINDOW_DAYFREQUENCY_CAP_WINDOW_WEEKFREQUENCY_CAP_WINDOW_FLIGHT