Ad Inspector

We provide near real-time data on the ads requested for your content. Analyze this information to gain insights into ad insertions, such as:

Verifying ad requests and responses.
Checking for errors and discovering their root cause.
Performing end-to-end auditing of a single playback session.

Ad Jobs

Ad insertion data is collated and presented as an ad job. The scope of an ad job varies by content type.

Live Stream: The system generates an ad job whenever playback encounters an upcoming ad break.
VOD: The system generates a single ad job upon initiating playback. This ad job contains data for all of the asset's ad breaks.

An ad job describes:

The set of ads that were requested.
The ad decision server's response for each of those ads.
The tracking data provided to the ad decision server.

As illustrated above, each ad job consists of the following components:

Ads: Each ad listed under the job corresponds to a single ad during an ad break. Data shows whether the ad was selected for use during the ad break, the position in the ad break the ad was inserted into, and the status of the ad asset.
Transactions: A transaction describes an ad request and the response provided by an ad decision server.
- Request: An ad request is generated for the initial request to the ad decision server and for each wrapper spawned from it. The following information is captured for each ad request: raw URL, macros, HTTP headers, and processing information.
- Response: For each ad request, we provide the raw XML from the ad decision server and a summary of the response, including errors. If the ad request resulted in VMAP and VAST wrappers and a creative, that information is also included in the raw XML response.
- An error during an ad request may prevent an ad response from being provided.
Beacons: A beacon consists of the tracking data reported by our system to the ad decision server.

Data Retention

The retention policy for ad insertion data is 7 days.

Basic Usage

Find and review ad jobs through the Ad Inspector page.

Locate Live Channel ID

From the CMS, select the Live Channels tab.
Select the desired live channel. Basic options and live channel information appear on the Details tab.
Find the live channel's system-defined ID under the GUID label.

Find a Live Event ID

Navigate to the Live Events page (Events > Live Events).
Select the desired live event.
Verify that the Details tab is selected.
Find the live event's system-defined ID under the GUID label.

Locate an Asset ID

Navigate to the CMS library by selecting the Content tab.
Select the desired asset.
The asset ID is listed under the GUID label.

Find Playback Session ID

Implement the Preplay API within your custom player to retrieve the playback session ID.

Alternatively, inspect your playback URL to find your playback session.

Search Settings

Use the following settings to search for ad job data:

Setting	Description
Ad server query params	For certain ad providers, such as GAM and Invidi, you can filter for specific ad server query parameters. For example, for GAM requests, you can query for ad jobs with `ppid=123` in the primary ad server request.
Ad Playback Type	Filters ad job data by whether the ad was requested as part of a live stream or VOD.
From To	Filters ad job data by the time period during which the ad was requested.
Channel/Live Event ID	Filters ad job data by the live channel or live event during which it was requested. Identify a live channel or live event by its system-defined ID. Find a live channel ID or a live event ID.
Asset ID	Filters ad job data by the VOD asset during which it was requested. Identify an asset by its system-defined ID. Find an asset ID.
Session ID	Filters ad job data by the playback session for which it was requested. Identify your playback session by its system-defined ID. Find a playback session ID.
Status	Filters ad job data by status.
Debug Name	Filters ad job data by tagged playback session(s). Tag a playback session by passing the `ad._debug` parameter in the playback URL.
Transactions	Determines whether transactions are included in the search results.
Beacons	Determines whether beacons are included in the search results.

Search for Ad Job Data

Navigate to the Ad Inspector page (Ads > Ad Inspector).
From the Ad Playback Type option, select whether to return ad job data for a live stream or VOD content.
Define the time period for which ad job data will be returned.
- Select the From option and choose a start date and time.
- Select the To option and choose an end date and time. Ad job data is available a few minutes after the ad request is sent to the ad decision server.
- For your convenience, date and time are displayed in your local time zone. However, this does not indicate the time zone of the playback session for which ad insertion data is being reported.
Optional: Define other ad job filters.
Select Fetch Ad Data.

Refine Search Results

Refine your results by modifying the desired ad job search option(s) from the Query pane and then selecting Update Query.

To perform a new search instead, select New Ad Query.

Filter Search Results by Ad Job Status

Filter your results by status by selecting the filter icon and then clearing the statuses that should be excluded from the search results.

Ad Job Data

Search results consist of a list of ad jobs that meet the specified search criteria. The following information is reported for each ad job:

Name	Description
Status	Indicates the ad job's status. The available statuses are described below. Completed: Indicates that an ad job's initial transactions with the ad decision server were completed in a timely manner. This state may include ad jobs with a failed wrapper transaction. Failed: Indicates that an ad job's initial transactions either did not complete on time or resulted in empty or malformed responses. View the failure reason by hovering over this label. Pending: Indicates that work on an ad job has not been started. Due to the speed at which ad jobs are processed, this state should happen infrequently. Additionally, an ad job that does report this state should quickly transition to a different state. Processing: Indicates that an ad job contains at least one transaction that is still being processed. For example, this state may indicate that the system is still fetching ads from the ad decision server and creating the ad payload. Due to the speed at which ad jobs are processed, this state should happen infrequently. Additionally, an ad job that does report this state should quickly transition to a different state.
Date Created	Indicates the date and time at which the ad job was initiated. For your convenience, date and time are displayed in your local time zone. However, this does not indicate the time zone of the playback session for which ad insertion data is being reported.
Channel/Event	Identifies a live channel or a live event by its name.
Session ID	Identifies a playback session by its system-defined ID.
T#	Indicates the number of transactions associated with the ad job.
B#	Indicates the number of beacons associated with the ad job.
F#	Indicates the number of failed transactions within an ad job. A transaction is considered a failure when it either does not complete on time or results in an empty or malformed response.

Select an ad job to view its transactions and beacons.

Transactions

View an ad job's transactions by selecting an ad job from the Ad Inspector Query Results page. The following information is reported for each transaction:

Name	Description
Status	Indicates the ad job's status. The available statuses are described below. Completed: Indicates that an ad job's initial transactions with the ad decision server were completed in a timely manner. This state may include ad jobs with a failed wrapper transaction. Failed: Indicates that an ad job's initial transactions either did not complete on time or resulted in empty or malformed responses. View the failure reason by hovering over this label. Pending: Indicates that work on an ad job has not been started. Due to the speed at which ad jobs are processed, this state should happen infrequently. Additionally, an ad job that does report this state should quickly transition to a different state. Processing: Indicates that an ad job contains at least one transaction that is still being processed. For example, this state may indicate that the system is still fetching ads from the ad decision server and creating the ad payload. Due to the speed at which ad jobs are processed, this state should happen infrequently. Additionally, an ad job that does report this state should quickly transition to a different state.
Date Created	Indicates the date and time at which the ad job was initiated. For your convenience, date and time are displayed in your local time zone. However, this does not indicate the time zone of the playback session for which ad insertion data is being reported.
Type	Indicates the transaction type: the primary ad request (labeled "Primary" in purple), a wrapper spawned from the primary transaction (labeled "Primary Wrapper"), or a wrapper spawned from another wrapper transaction (labeled "Wrapper"). Primary: The primary ad request. Primary Wrapper: A wrapper spawned from the primary transaction. Wrapper: A wrapper spawned from another wrapper transaction.
Total Elapsed Time	Indicates the total time to complete the transaction.
Transaction ID	Identifies the transaction by its system-defined ID.
Initial Ad ID	Displays the ad ID found in the initial/primary response.
Wrapper Chains	Indicates the number and status of wrapper chains spawned from this transaction. Each wrapper chain starts with a primary transaction followed by one or more wrapper transactions. Green indicates all wrapper chains ended with a successful response containing ads. Yellow indicates a mix of successes and failures. Red indicates all wrapper chains ended with a failed response. Wrapper chains can be collapsed or expanded with the caret buttons on the left, or with the Expand All / Collapse All buttons.
Wrapper Depth	Indicates the position of this wrapper in the chain with the number of parent transactions of this request. 0 is the primary ad request, 1 is for Primary Wrappers, 2 is the third transaction in the wrapper chain, and so on.

Select a transaction to view the ad request and the raw XML response from the ad decision server.

Sort the table to quickly find transactions with similar attributes (e.g., status, wrappers, and creatives).

Transaction Details

View a transaction's request and response by selecting it from the Transactions tab of the Job Details page.

The Request tab describes either the initial request to an ad decision server or a wrapper.
The Response tab provides the raw XML response from an ad decision server and summary information.

Request

The Request tab describes either the initial request to an ad decision server or a wrapper. This tab reports the following information:

Name	Description
Request URL	Typically indicates the request URL. The request URL's query string parameters are reported directly below this URL. Google Ad Manager and VOD Playback: If the ad.output parameter was set to a VAST format (i.e., `xml__vast3` or `xml_vast2`) for a VOD playback session, then this field returns a VMAP template instead of a URL for the initial ad request. However, our service populates this field with a request URL for subsequent wrapper requests.
Request Headers	Contains a list of request headers and their values. Google Ad Manager and VOD Playback: If the ad.output parameter was set to a VAST format (i.e., `xml__vast3` or `xml_vast2`) for a VOD playback session, then this section will not be populated for the initial ad request. However, our service populates this section for subsequent wrapper requests.
Date Created	Identifies the date and time at which the ad request was submitted.
Date Updated	Deprecated.
Total Time	Identifies the total time, in seconds, to submit the ad request and receive a response from the ad decision server.
Connection Time	Identifies the time, in seconds, to establish a connection to the ad decision server.
Header Request Time	Identifies the time, in seconds, after establishing a connection to send the ad request and download response headers.
Body Download Time	Identifies the time, in seconds, to download the response body.
Failure Reason	Identifies the reason the transaction failed. This field reports None for pending or successful ad requests.
Pod Location	Reserved for future use.
Redirects	Identifies the number of HTTP redirects (e.g., 302 Found) generated as a result of this ad request. Example: A request for `http://example.com` may redirect to `https://www.example.com`.

Response

The Response tab describes the response from an ad decision server. This tab reports the following information:

Name	Description
Raw Response	Contains the raw response provided by the ad decision server.
Date Created	Identifies the date and time at which the ad request was submitted.
Date Updated	Reserved for future use.
Ads	Identifies the number of ad creatives provided by the ad decision server as a result of this transaction.
Beacons	Identifies the number of beacons sent to the ad decision server.
In Wrapper	Indicates whether this response is due to a wrapper.
Depth	Identifies the number of times an ad decision server forwarded this ad request to another server.
ID	Indicates the system-defined ID assigned to the response.
Failure Reason	Identifies the reason the transaction failed. This field reports None for pending or successful ad requests.
Errors	Indicates any errors that occurred when processing the response.
Warnings	Indicates any warnings that occurred.

View the list of ads returned by this ad job here. The following information is reported for each ad:

Name	Description
Selected?	True/False indicating whether this ad was selected for insertion into the ad break.
Break #	Which ad break the ad belongs to, 0-indexed.
Ad #	Position of the ad within the ad break, 0-indexed. For example, a break # of 0 and an Ad # of 2 indicates the ad was the third ad inserted into the first break.
Initial Ad ID	ID of this ad as found in the initial/primary ad response (the top-level parent in the case of wrappers). Otherwise, this is often the same as the Ad ID.
Ad ID	ID of this ad as found in the ad response.
Creative ID	ID of the ad asset/creative, as found in the ad response.
Duration	Duration of the ad asset, in seconds.
Fallback?	True/False indicating whether this ad was a fallback ad. Fallback ads are used as backups when other ads are unusable.
Asset Status	Displays the status of the ad asset in the Uplynk system. Selecting the button plays the ad if its status is 'OK'.

Beacons

View an ad job's beacons by selecting an ad job from the Ad Inspector Query Results page and then selecting the Beacons tab. The following information is reported for each beacon:

Name	Description
Delivered	Indicates whether the current beacon was successfully delivered to an ad decision server. Valid values are: - success: The ad decision server received the beacon. - pending: Our system has not yet sent the beacon to the ad decision server. - error: Our system experienced a communication error upon sending the beacon to the ad decision server. For example, an error occurs when the ad decision server does not return a `2xx` response or it takes too long to respond.
Date Created	Indicates the date and time at which the beacon was sent to the ad decision server. For your convenience, date and time are displayed in your local time zone. However, this does not indicate the time zone of the playback session for which ad insertion data is being reported.
Name	Indicates the name assigned to the beacon.
Beacon URL	Indicates the URL to which beacon data was sent.
Type	Indicates the type of ad event that triggered the beacon. Valid values are: - IMPRESSION: Indicates that a creative was rendered. - ERROR: Indicates that an error occurred. - CLICK: Indicates that the viewer clicked on a creative.
Code	Indicates the beacon's HTTP status code (e.g., 200).
Browser	Indicates the client's behavior when a viewer clicks on an ad. Valid values are: - Hide: Indicates that the ad will continue to play. - Replace: Indicates that the client should open the link associated with the ad and switch focus to that content. This field is only relevant for client-side beacons.

Sort the table to quickly find beacons with similar attributes (e.g., delivery status or HTTP status code).

Troubleshoot Ad Jobs

Troubleshoot ad jobs that contain completed transactions with warnings, failed transactions, or both.

You can audit your own playback session to correlate the playback experience to ad insertion data.

An ad job is considered successfully completed when the initial transactions to the ad decision server are completed in a timely manner. However, a successful ad job may contain transactions with warnings or failures.

Troubleshoot an Ad Job

Select the desired ad job.
Select the desired transaction.
From the Request tab, review the URL, query string parameters, and headers for the request submitted to the ad decision server.
From the right-hand pane, review the Failure Reason field.
Select the Response tab.
From the right-hand pane, review the following fields:
- Failure Reason: Indicates the reason that a transaction failed.
- Errors: Indicates any errors that occurred when processing the response.
- Warnings: Indicates any warnings that occurred.
Use the information uncovered in the previous step to perform additional investigation into the failure, error, or warning.

View the transaction in JSON format by selecting Export Transaction JSON. The raw_response JSON field contains the raw data for the response in XML format.

Warnings

A warning indicates that the request to the ad decision server was incomplete or improperly formed. For example, a warning is generated when the request contains missing parameters or values.

A warning triangle icon appears next to both of the following:

Ad jobs that contain at least one transaction with a warning.
The transaction to which the warning applies.

View the warning by hovering over it as illustrated below.

In the above illustration, the ad job contains a warning indicating that a transaction contains 4 empty impressions. Inspecting the transaction's raw response reveals that it does contain 4 empty impressions. Reviewing the <Error> tag indicates that an error also occurred. Although the ad decision server returned 4 empty impressions and an error, an ad was still served to the viewer.

			<Impression id=\"3rdparty\"/>
			<Impression id=\"3rdparty\"/>
			<Impression id=\"3rdparty\"/>
		<Impression id=\"3rdparty\"/>

Failure

A failed transaction indicates that an ad impression was not delivered either because the transaction did not complete on time or it resulted in an empty or malformed response. View the failure reason by hovering over the transaction's status.

Ad Request Failure Reasons

Failures can occur at various stages of processing an ad request. Uplynk categorizes failure reasons into failure types based on these stages.

The failure types are:

Request
Response
Parsing
Processing

In certain cases, the "Error" section of the job or transaction details includes additional information about an ad failure that can be sent to Uplynk Support to help troubleshoot an inquiry about a failed job or transaction.

Request

An error occurred while establishing an HTTP connection to the ad server and downloading the ad response. To troubleshoot request failures, contact the ad server. The ad server may have some data, or it may not have any data. The Ad Analytics reports can be used to gather data on how frequently these errors occur.

Request Errors

Failure	Description
connection error	An error occurred establishing the connection with the ad server. This typically means the ad server was unreachable.
connection timeout	The ad server did not respond quickly enough to the connection attempt. Standard timeout is limited to 1 second.
download error	There was an error attempting to download the prepared ad response from the ad server.
download timeout	The ad server took too long to send the next packet while downloading the ad response. Standard timeout is limited to 1 second.
invalid URL	The URL used to make the request was not valid. This typically happens because a wrapper URL contains a bad URL.
non 200	The ad server responded with an error code. Usually either a 4xx or 5xx HTTP status code.
read timeout	The ad server took too long to respond back while preparing the ad response. Standard timeout is limited to 1 second.
SSL error	There was a problem with the ad server's security certificate.

Response

A high-level check of the response contents ensuring they are in a valid format. For these failures, the ad server should be notified.

Response Errors

Failure	Description
empty response	The ad response is an empty string with no content.
invalid XML	The XML of the ad response was malformed.
response too big	The ad response was too big. Ad responses are limited to 1 MB to ensure processing ad jobs are not blocked by an enormous ad response.

Parsing

Reading and parsing the response to extract the ad information.

For the no ad break, no ads returned, and no media file errors, the ad server did not provide the needed information. Contact the ad server to determine why the responses did not include that data. Parse errors can occur for a variety of reasons. Contact support with any questions and include any additional information provided in the "Errors" section.

Parsing Errors

Failure	Description
no ad break	The VMAP ad response did not contain any ad breaks.
no ads returned	The ad response did not contain any ads.
no media file	The ad response contained ads, but none of the ads contained media files.
parse error	Something in the ad response caused parsing to fail.

Processing

After parsing, additional actions are taken to ensure the ads are prepared for stitching. This also covers any issues before or between the other stages.

Processing Errors

Failure	Description
process timeout	The allotted time for completing the ad job expired before being able to finish processing the ad request.

Audit a Playback Session

Verify that ads are being served properly or troubleshoot ad delivery by auditing a playback session. If you audit your own playback session, you can view the ads that were served and then review the corresponding ad jobs triggered by those ads.

Audit Your Own Playback Session

From within your web browser, open developer tools (e.g., Chrome offers DevTools).
View your own network traffic by selecting the Network tab.
Start video playback of the desired live stream or VOD.
From within the Network tab of your web browser's developer tools, select a playback request.
Copy your playback session ID from the pbs query string parameter.
Navigate to the Ad Inspector via Services > Ad Server Debug.
Paste your playback session ID within the Session ID option.
Select Fetch Ad Data.

Ad job data is provided in near real-time. If the desired results are not returned, try again after a minute or two.
Review ad job data.

Retrieve the latest ad job data by performing the following steps:
- Update the To option to the current time.
- Select Update Query.