Ads Session Feed: Schema and Column Dictionary

This page is the canonical column dictionary for the Conviva Connect Ads Session Feed schema: every delivered field, its type, its mode, and what it means. For the metric definitions and SQL built on these fields, see Ad Session Summary. If you are migrating an existing legacy Ads SSD pipeline, see Legacy vs Connect.

Primary key and session identity

Each row is one ad session. The primary key for processing ad sessions is AdSessionID plus StartTimeMs. Because the Ads feed is hourly only, a session that spans an hour boundary appears once per active hour with the same key, so this pair is also the deduplication key. Keep the row with the greatest dt. See Build your first pipeline, step 4.

ContentSessionID is the ConvivaSessionID of the video session the ad played inside. Use it to join to the Video Session Feed. Both identifiers are five colon-separated integers: the first four are the Conviva Client ID, which is shared between the video session and every ad session inside it, and the fifth is the session number.

Field naming

Field names are delivered in PascalCase, for example AdSessionID and StartTimeMs. The names in the dictionary below match the delivered file exactly, including three quirks that read as typos:

• AdCeativeName is spelled without the second r. That is the real delivered column name. Do not correct it in your schema definition or the column will not bind.

• DeviceManufacture is the delivered name, not DeviceManufacturer.

• Identifier casing is split and cannot be normalized. AdID, AdCreativeID, AdBreakID, AdSessionID, ContentSessionID, DeviceID, and AdvertiserID end in ID. SegmentId, FirstAdId, FirstCreativeId, DecisionResourceId, and ViewerId end in Id. pCoreCDN and isLive are the only two fields that start with a lowercase letter.

Nulls and sentinel values

Conviva Connect represents absence consistently, so write your filters to match:

• An absent scalar is a real NULL. Connect does not emit sentinel strings such as NA, N/A, or UNKNOWN in place of a missing value, which legacy Ads SSD did. Test with WHERE col IS NOT NULL.

• An absent list is an empty array, never NULL. All seven list columns behave this way. Test with WHERE cardinality(col) > 0. An IS NOT NULL test passes every row.

• A few numeric fields still use a documented negative code rather than NULL, because the code carries meaning. StartupTime uses -1 for an unsuccessful play and -3 when the client never reported enough to determine the start, and ContentLength and PlayingTime use -1 when unavailable. Those are called out per field below.

Columns are selectable per account, so your delivered file may be a subset of the dictionary below. A column that is present but null in every row usually reflects what your ad stack passes through rather than a gap in the feed. Confirm your configured column list with your Conviva Representative.

Sample delivered file

Below is an anonymized sample of a delivered hourly Connect Ads file: the header plus three rows, exactly as the columns arrive. Scroll the table horizontally to see all 88 columns. The values are synthetic (test-network IP addresses and placeholder names), but the column order, casing, and formatting match a real delivered file. Download the full sample hourly Ads Connect file to open it in a spreadsheet or feed it through your pipeline.

The first two rows are the same ad session, 1000000001:1000000002:1000000003:1000000004:4487054, delivered in two consecutive hourly files. The 07:00 row shows it mid-flight (EndedStatus 0, PlayingTime 12000); the 08:00 row shows it finished (EndedStatus 1, PlayingTime 30000). Summing PlayingTime across both rows gives 42 seconds for a 30-second ad. That is the double count deduplication removes. The third row is a separate session that failed to start: StartupTime is -1, StartupError is true, and the error appears in both ErrorList and VideoStartFailureErrorsTech.

Field dictionary

Session identity and lifecycle

Each row is one ad session. The primary key is AdSessionID plus StartTimeMs; that same pair is the deduplication key for the hourly feed. ContentSessionID is the join key back to the Video Session Feed.

Ad metadata

Ad-level descriptive fields sourced from the VAST response and your ad manager. Which of these arrive populated depends on what your ad serving stack passes through, so treat an all-null column as a configuration question rather than a feed defect.

Advertiser and ad serving

Who bought the ad and which stack delivered it.

Content context

The content session the ad played inside.

Experience metrics

The quality-of-experience measures for the ad session. All durations are milliseconds.

Errors and failures

Failure flags and the error lists behind them. The list columns arrive as a real array in Parquet and Avro, and as a single &-separated string in CSV.

Device and player

Device and playback-stack attributes, resolved by Conviva from the sensor's device signals.

Network and geography

Network path and viewer location, derived from the IP address Conviva observes.

Conviva Precision decision fields

Populated only for accounts running Conviva Precision. On every other account these five columns are present in the schema and null in every row.

Custom session tags

Your own player metadata, carried through as key-value pairs.