About video error reports
Equativ's video error reports are a powerful tool to troubleshoot problems in your video integrations or insertions. The reports allow you to track lost opportunities and understand the causes of poor delivery rates.
Video error code reports include the errors specified in the VAST standard as well as Equativ's own proprietary error types.
Equativ player / integration method support
The following table shows, which Equativ players/integration methods support video error reports:
Equativ player /
integration method | Support | Further documentation |
|---|
| Standalone VAST requests | supported if:
- the player supports the VAST error tracking specs (see chapter "2.3.6. Error Reporting" here)
- the player is able to replace the macro ec=[ERRORCODE] with the appropriate error code
- the official VAST 2.0/3.0/4.0 script templates are used in the insertions created in Equativ's system
|
|
| Video plugin | supported if official [VIDEO] VAST x - LINEAR creative template is used | Equativ Video plugin |
| Embedded ad manager (video plugin via VPAID) | supported if official [VIDEO] VAST x - LINEAR creative template is used | Embedded Ad Manager |
| In-stream SDK (mobile & OTT TV applications) | supported | In-stream SDK |
| Out-stream script templates | supported | Ad format specs |
| Server side bidding (SSB) | supported under the same conditions as Standalone VAST requests (see above) | Server side bidding |
| Server Side Ad insertions (SSAI) | supported under the same conditions as Standalone VAST requests (see above) | |
Creating video error reports
Video troubleshooting template in the Instant Report Builder
You can use the
Video troubleshooting template to find issues with Video auctions and deals. For example, your inventory participates in auctions but generates zero or very low number of impressions – with no errors reported. This could mean that the video player has failed to report errors, and with this template you can find the issues.
The template is preloaded with five metrics (Auctions, Impressions, Video Complete, Viewable Impressions, Video Error Count) and five dimensions (App/Site Name, Environment Type Name, Device Type Name, Insertion Id, Video Error Code Name).
To access it, go to the
Instant Report Builder and click
↓ Select template.
Select
Video troubleshooting.
The template will populate the metrics and dimensions in the report builder view:
Click Generate Report. In the next window, specify if you’d like a one-time or scheduled report, fill in the required fields, and click Confirm. For more information about the Instant Report Builder, including a video overview, see
this article.
A report will be generated and sent to the email address(es) you specified. The report will also be listed under the
Reports list tab.
Note: The report might take several minutes to generate. During this time, you will see a Rendering status.
When the report is ready, the
Status will change to
Download.
Click
Download to save the CSV file to your computer.
Video error reports in UI
New reporting tools: Instant Insights / Instant Report BuilderThis chapter describes the creation of video error reports in the
Big Data Report, which will be deprecated soon. Instead, you may want to use the new Video view in
Instant Insights and
Instant Report Builder to investigate video errors.
In the
Equativ Monetization Platform, go to
Reports >
Create a report.In the
Report columns section
:
- in the General settings section, select/fill the required fields as usual (type, format, period etc.)
- select your dimensions - e. g. Site, Page, Insertion, etc.
- in the Video section, select the Video error code dimension
- optionally, mouse over the Video error code button (see screenshot below) and add ID; this adds a column with the error ID, in addition to the error name
- switch to the Metrics section
In the
Metrics section
:
- under Delivery, select the metric Video errors
- under Delivery, select the metric Video ad calls; comparing this metric with the Video errors metric allows you to determine how many video ad requests were unsuccessful and resulted in an error
- under Delivery, unselect or ignore the metric Impressions; more details in the info box Video ad calls vs. Video errors below
- under Interactions, unselect or ignore the metric Clicks; more details in the info box Video ad calls vs. Video errors below
Video ad calls vs. Video errorsYou can compare the
Video ad calls metric with the
Video errors metric to get an idea of the error frequency. However, it would be wrong to use these two metrics to determine the actual error rate. The reason lies in the ad buffet feature supported by Equativ's In-stream video plugin/embedded ad manager solutions (available since VAST 3.0).
With the ad buffet feature, the player can request a pod size (number of video ads to be played in the ad pod, represented by the
Video ad call metric) and additional passback ads. In case of an error (represented by the
Video errors metric), the player can attempt to play another video ad from the ad buffet, until the number of requested ads (pod size) is played.
Due to this behavior, the number of errors can be much higher than expected, in fact even higher than the number of ads actually played. This example illustrates the behavior:
- the player requests 2 pre roll ads (pod size is 2; parameter: ps=2) and 4 passback ads (parameter: pb=4) from Equativ
- Equativ sends 6 video ads to the player
- ad #1 and #2 result in errors; ad #3 works and is played; ad #4 results in an error; ad #5 works and is played
In the video error report, this example will show up as 2 video ad calls (pod size is 2) and 3 video errors.
Keep this behavior in mind to avoid drawing the wrong conclusions, especially in case of reports covering a large scope (many sites/players with different pod sizes/passback settings). Try narrowing down your report to specific players/sites to get more relevant data.
Also, note that the metrics
Impressions and
Clicks are not meaningful in this context because impressions/clicks cannot even occur due to the errors themselves. For instance, if the player receives a video it cannot play, the video will not be played, which means that impressions/clicks will not occur.
Video error reports in API
The following table lists the dimension and metric names in the reporting API and the corresponding name in the Equativ Monetization Platform:
| API name | Name in UI |
|---|
| VideoErrorId | Video Error Code (ID) |
| VideoErrorName | Video Error Code (Name) |
| VideoCount (with id=10009) | Video errors |
Use cases
Use case #1 - Troubleshooting video integrations
This use case applies when you encounter problems with your new or modified video integration (e. g. Video plugin) on your website/app. For instance, you can determine if there are timeout issues and determine on which website or page they occur.
To verify if video errors exist:
- start creating your report as described in chapter "Video error reports in UI" above
- in the Report columns section, select the dimensions Site, Page and Format; this granular selection will allow you to precisely locate the origin of video errors
- switch to the Metrics section
- in the Metrics section, select the metric Video errors (i. e. the number of video error occurrences)
- optionally, add the metric Video ad calls; as explained in the info box Video ad calls vs. Video errors above, do not use the metrics Impressions or Clicks in this context
- Click on Generate the report
Now that you know the site/page/format the video errors originate from, you can dig deeper and see which video errors (error codes) occur.
Simply create the previous report but make the following changes:
- in the Report columns section, in the right column, filter the Site/Page/Format where your errors occur (see screenshot below);
- add the dimension Video error code to get the number of errors by error code (error type).
For a description of each error code, see chapter "List of error codes" below.
Use case #2 - Troubleshooting video insertions
This use case applies when you create, test or monitor your video insertions. For instance, you can identify a wrapper which does not return the expected VAST version.
In case of insertions with multiple creatives, you can also determine which individual creative leads to problems.
To verify if video errors exist:
- start creating your report as described in chapter "Video error reports in UI" above
- in the Report columns section, select the dimensions Insertion and (optionally) Creative
- switch to the Metrics section
- in the Metrics section, select the metric Video errors (i. e. the number of video error occurrences)
- optionally, add the metric Video ad calls; as explained in the info box Video ad calls vs. Video errors above, do not use the metrics Impressions or Clicks in this context
- Click on Generate the report
Now that you know the insertion/creative the video errors originate from, you can dig deeper and see which video errors (error codes) occur.
Simply create the previous report but make the following changes:
- in the Report columns section, in the right column, filter the Insertion/Creative where your errors occur (see screenshot below);
- add the dimension Video error code to get the number of errors by error code (error type).
For a description of each error code, see next chapter.
List of error codes
| Error Code | Error Name | Description |
|---|
| 100 | XML_PARSING_ERROR | XML Parsing error |
| 101 | SCHEMA_
VALIDATION_ERROR | VAST does not comply with VAST schema |
| 102 | RESPONSE_VERSION_
NOT_SUPPORTED | VAST version of response not supported |
| 200 | PLAYER_RECEIVED_AD_TYPE_
UNEXPECTED_OR_CANNOT_PLAY | Trafficking error; media player received an ad type that it was not expecting and/or cannot play |
| 201 | PLAYER_EXPECTING_
DIFFERENT_LINERARITY | Client-side component received a linear creative while expecting a non-linear creative and vice versa |
| 202 | PLAYER_EXPECTING_
DIFFERENT_DURATION | The client-side component cannot play the ad because it is longer than the allowed duration |
| 203 | PLAYER_EXPECTING_DIFFERENT_SIZE | The client-side component received an ad size it did not expect |
| 204 | REQUIRED_AD_CATEGORY_IS_MISSING | Ad category was required but not provided |
| 205 | INLINE_CATEGORY_VIOLATES_
WRAPPER_BLOCKED_AD_CATEGORIES | Inline Category violates Wrapper Blocked Ad Categories |
| 206 | AD_BREAK_SHORTENED | Ad Break shortened. Ad was not served. |
| 300 | GENERAL_WRAPPER_ERROR | General error related to the wrapper |
| 301 | VAST_URI_TIMEOUT | Timeout of VAST URI provided in wrapper element or in subsequent wrapper element (URI either unavailable or reached a timeout as defined by the media player) |
| 302 | WRAPPER_LIMIT_REACHED | Wrapper limit reached as defined by the media player; too many wrapper responses without any InLine response have been received |
| 303 | NO_VAST_RESPONSE | No VAST response after one or multiple wrappers |
| 304 | FETCH_TIMEOUT | InLine response returned ad unit that failed to result in ad display within defined time limit |
| 400 | GENERAL_LINEAR_ERROR | General Linear error; media player unable to display the linear ad |
| 401 | NO_MEDIA_FILE | File not found; unable to find linear/MediaFile from URI |
| 402 | MEDIA_FILE_TIMEOUT | Timeout of MediaFile URI |
| 403 | NO_MEDIA_FORMAT | Found no MediaFile supported by this media player, based on the attributes of the MediaFile element |
| 405 | MEDIA_FILE_DISPLAY_ISSUE | Problem displaying the MediaFile; media player found a MediaFile with supported type but could not display it; MediaFile may include: unsupported codecs, MIME type different from the MediaFile@type, unsupported delivery method, etc. |
| 406 | REQUIRED_MEZZANINE_IS_MISSING | Mezzanine was required but not provided; ad not served |
| 407 | MEZZANINE_FIRST_DOWNLOAD_
IN_PROGRESS | Mezzanine is in the process of being downloaded for the first time; download may take several hours; ad will not be served until mezzanine is downloaded and transcoded |
| 408 | CONDITIONAL_AD_REJECTED | Conditional ad rejected |
| 409 | INTERACTIVE_CREATIVE_
FILE_NOT_EXECUTED | Interactive unit in the InteractiveCreativeFile node was not executed |
| 410 | UNIVERSAL_AD_ID_REJECTED | Verification unit in the Verification node was not executed |
| 411 | MEDIA_FILE_UNSUITABLE | Mezzanine was provided as required, but file did not meet required specification; ad not served |
| 500 | GENERAL_NON_LINEAR_
ADS_ERROR | General error related to NonLinearAds |
| 501 | CREATIVE_DIMENSION_UNALIGNED_
TO_CREATIVE_DISPLAY_AREA | Unable to display NonLinearAd because creative dimensions do not align with creative display area (i.e. creative dimension too large) |
| 502 | FETCH_ERROR_NONLINEAR / NONLINEARADS_RESOURCE | Unable to fetch NonLinearAds/NonLinear resource. |
| 503 | NO_NONLINEAR_RESOURCE_
FORMAT | Could not find NonLinear resource with supported type |
| 600 | GENERAL_COMPANION_ADS_
ERROR | General CompanionAds error |
| 601 | CREATIVE_DIMENSION_DO_NOT_
FIT_CREATIVE_DISPLAY_AREA | Unable to display Companion because creative dimensions do not fit within Companion display area (i.e. no available space) |
| 602 | UNABLE_TO_DISPLAY_REQUIRED_
COMPANION_ADS_ERROR | Unable to display required Companion |
| 603 | FETCH_ERROR_COMPANION / COMPANIONADS_RESOURCE | Unable to fetch CompanionAds/Companion resource |
| 604 | NO_COMPANION_
RESOURCE_FORMAT | Could not find Companion resource with supported type |
| 900 | UNDEFINED_ERROR | Undefined error |
| 901 | VPAID_GENERAL_ERROR | General VPAID error |
| 902 | GENERAL_INTERACTIVE_
CREATIVE_FILE_ERROR | General Interactive Creative File error |
