1. Vistar Media
  2. Integrations
  3. Diagnostics

Integration health assessment guide

Linus Chan
Updated

You can reference this assessment guide when reviewing the performance of your integration. To learn how to view and export reports from the Network Health Overview and Insights tables, see Build a diagnostics report.

View the following sections for common questions and answers about the Diagnostics dashboard. 

Overall integration health review

Active versus inactive venues or networks

Values in the Network Health Overview or Insights reports

Overall network review

“What should I pay attention to while reviewing the overall health of my network?”

In reviewing your overall network health, pay close attention to the following information in the Network Health Overview table:

  • % of requesting venues (today)—100% of the venues in your network should be requesting.
    If not all of your venues are requesting, navigate to the Insights tab and follow the steps below to identify all the venues that are not requesting:
    1. Click Date Range, select Last 7 days, and click Apply.
    2. Click Network, select the relevant network or networks, and then click Apply.
    3. Click Group by, select Venue and Network, and then click Apply.
    4. Click Load Report.
    5. Click Export Report and flag all the venues that have no data in the Requested Spots column.

If it is known that the non-requesting venues are offline, there are a couple of steps you can take:

        • Offline venues that will later be reactivated—Follow the guidelines to manage your venues in bulk and update your venues with a future activation date. The activation date should align with when you expect the venues to be up and running again. Venues with a future activation date will no longer be available on the exchange or inventory until active again. This should be leveraged for long term down time (for example, more than 30 days).If your venues are just offline for a few days, this isn’t necessary.
        • Offline venues that are no longer part of your network—For venues that are now deprecated, follow the steps in manage your venues in bulk to delete them from your network.
        • Note: The % of requesting venues (today) column does not take into account of a venue’s operating hours, therefore, if a venue is closed on the present day, this venue will be counted as not requesting.
  • Avg. expiration rate (past day)—The expiration rate should be less than 10%.
  • Avg. spend rate (past day)—Your network should be playing over 90% of the ads that Vistar returns.
  • Expiration rate diff—This column compares your network’s expiration rate for the past day against the past month’s. The value in this diff column should not be greater than 10% (+10%). If the expirations on your network are related to technical issues rather than direct sell-outs, escalate this information to your technical team for resolution.
  • Spend Rate Diff—The value in this diff column should not indicate a drop of more than 10% (-10%). Where a greater than 10% drop in spend is noted in the table, escalate this to your development team for resolution. Drops in spend could adversely impact the performance of campaigns targeted to your network, and therefore result in lost revenue.

  • Average Display Time Latency (seconds)— This column flags two types of issues:

        1. Delays in playing ads leased by Vistar. These are represented as positive values.

        2. Cases where ads are reported to have played earlier than the requested time. These are represented as negative values.

As a general requirement, and to maintain a healthy integration with Vistar, venues must play ads within 15 minutes (900 seconds) of when they were requested. If the values in this column are outside of the +/- 15 minute bounds, follow the steps below to rectify:

        • If you have a native integration with Vistar’s ad server, contact your development team to ensure ads are played within 15 minutes of the display time provided in your ad requests.
        • If you are a media owner on Cortex, Ayuda, Broadsign or the Agent, create an Insights report with date range set to the last 7 days. Group the report by venue and filter on venues that whose display time latencies are outside of the +/-15 minute bounds.
            • An example of a problematic venue is one whose display time delta is - 2 hours (converts to -7200 seconds). This indicates that the venue is wrongfully displaying ads 2 hours earlier than the requested display time set in the ad request.
        • Contact support@vistarmedia.com with this list.
  • Average PoP Time Latency (seconds)— This column tracks latencies in reporting proofs of play to Vistar. You must notify Vistar after an ad is played by hitting the proof_of_play_url located in the ad response. When the URL is hit, the time is recorded in Vistar’s system as the reported display time.

As a general requirement, venues must hit proofs of play (PoPs) within 15 minutes of playing an ad. This 15 minute window is known as the lease window.

Vistar expires pops that you attempt to hit outside of the allowed lease window for your network. This is because pops sent earlier or later than the requested display time (passed in your ad requests) can impact campaign spend and ultimately, revenue.

        • Note: Negative values in the PoP Latency column are the indicator that your venues are reporting plays before the requested display time in their ad requests. Click here for a summary of what makes a strong integration.

To rectify pop latencies:

        • For media owners with a native integration to Vistar’s ad server, contact your development team with the request to narrow your pop reporting window to under 15 minutes.
        • For media owners on Cortex, Ayuda, Broadsign or the Agent, create an Insights report with date range set to the last 7 days. Group the report by venue and filter on those whose values in the pop latency column are outside of the +/-15 minute bounds.
            • An example of a problematic venue is one where the pop latency is -3600 seconds (pops sent 1 hour early) or a venue whose pop latency is 3600 seconds (pops sent 1 hours late). 
        • Contact support@vistarmedia.com with this list.

“What are some examples of reports can I generate to assess my integration at the venue or market-level?”

To review venue or market-level performance of your integration, you can run different types of weekly reports from the Insights table. For example:

  • A venue-level report to view and flag all venues with low spend rate (less than 90%) in the past week. To view this report, set the following filters and group bys:
    1. Click Date Range, select Last 7 days, and click Apply.
    2. Click Group by, select Venue, and then click Apply.
    3. Click Load Report.

  • A venue-level report to flag all venues that play ads or report playbacks outside of the acceptable time bounds. Ads must be played within 15 minutes (900 seconds) of being leased by Vistar and playbacks must be reported within 15 minutes of the ads getting played. Adhering to these requirements mitigates issues with campaign delivery, particularly for day-parted campaigns on the exchange or from direct buys. 

    To generate the report, set the following filters and group bys:

    1. Click Date Range, select Last 7 days, and click Apply.
    2. Click Group by, select Venue, and then click Apply.
    3. Click Load Report.
      In the average display time latency and average pop time latency columns, filter on all venues with values that are outside of the +/-15 minutes (900 seconds) bounds. As explained in the previous section, if you have a native integration with Vistar, escalate the flagged venues to your development team for resolution. If you are on the Agent, Cortex, Ayuda or Broadsign, send a list of the flagged venues to support@vistarmedia.com.
  • A state or DMA-level report to quickly catch any market-specific integration issues. If certain markets are under-performing, this type of report can help to determine whether integration problems are at the root of it. To view the report:
    1. Click Date Range, select Last 7 days, and click Apply.
    2. Click Group by, select DMA or State, and then click Apply.
    3. Click Load Report.

Indications of poor performance at the venue or market-level should be investigated by your technical team to ensure that any issues with your integration are quickly resolved.

"What standard diagnostics checks can I make following an update or fix to my integration?"

Vistar’s checklist for a healthy integration is outlined in Integration Tests.

To monitor that your integration meets the above requirements, we recommend that you generate a simple Insights report and select the Group by options Venue and Day for date ranges prior to the current day. This report shows you the performance of each test venue against the noted checklist (see Integration testing process for more information). Any venue that doesn’t meet our success criteria should be flagged for resolution.

Note: Following any fixes to your integration, you should pull the latest report to check that your improvements are reflected in the Insights report. For example:

  • You have an integration test running for a week.
  • During the testing process, you catch an issue with your integration. A fix for it is implemented on X date.
  • When checking the diagnostics dashboard to confirm the fix, pull your reports after the date the fix went out.

You should flag any venue that does not meet the conditions of the outlined checklist for resolution following the above check.

“How often is data in the diagnostics dashboard updated?”

Data in the diagnostics dashboard is refreshed every 30 minutes.

“How far back can I pull data from the Insights table?”

You can pull reports from as far back as April 11, 2019, which is when this data was first made available in the dashboard.

Active versus inactive venues or networks

“Are all my venues network requesting for ads from Vistar?”

  1. Check the Network Health overview table
  2. If less than 100% of your venues are requesting for ads, navigate to the Insights tab to generate a report of the inactive venues.
    1. Click Date Range, select Last 7 days, and click Apply.
    2. Click Network, select the relevant network or networks, and then click Apply.
    3. Click Group by, select Venue and Network, and then click Apply.
    4. Click Load Report.
    5. Click Export Report and flag all the venues that have no data in the Requested Spots column.

“What can I do about the inactive venues on my network?”

Inactive venues that will later be reinstated should have their activation dates updated. Follow the guidelines outlined in manage your venues in bulk to update your venues with a future activation date. The activation date should align with when you expect the venues to be up and running again. Venues with a future activation date will no longer be available on the exchange or inventory until active again.

Venues that are fully deprecated (no longer functional or live) should be deleted from your network.

See Manage venues in bulk to learn how to delete those venues.

“My network does not show up in the Network Health Overview table.”

Empty networks (networks without venues) and networks without requests do not show on the Network Health Overview table.

Users without access to a specific network will also not see that network’s information in the diagnostics dashboard.

“The number of requesting venues is greater than the total number of registered venues on my network.”

You may end up seeing one or both of the following instances in the Network Health Overview table:

  • The requesting venues (today) column has more venues than the total venue count column.
  • The value in the % of requesting venues (today) column is greater than 100%.

These cases can occur if:

  • There is no venue_id passed in your ad requests to Vistar.
  • The venue_ids passed in your ad requests do not match any of the venues in our system. The Diagnostics dashboard records data for all venues making valid requests, whether registered in the Vistar platform or not.

To remediate these issues follow up with your technical team to ensure that:

  • All venues making requests to Vistar’s ad server are registered on our platform. See Manage venues in bulk to register multiple venues.
  • Ad requests to Vistar contain the relevant venue IDs. See the Ad Serving API for details.

“The venue ID and venue name columns in my insights report show ‘None.’”

If you are seeing "none" listed as the venue ID and venue name in the reporting dashboard that means one of two things is occurring, as noted in the above FAQ.

    • There was no venue ID passed on the request.
    • The venue ID that was passed does not match any of the venues in the system.

When the vistar ad server receives a request that matches either of these two criteria it will still treat the request as valid and return an ad to be played, if available. Since there is no venue to reference from our platform when this occurs, the ad server will fall back to the network-level impressions per spot figure and the network floor CPM for exchange campaigns, or the CPM on the line item for direct campaigns. 

To identify the unregistered venues, navigate to the Insights tab of the diagnostics dashboard and from the export dropdown, select Export unregistered venues only. This report contains all actively requesting venues that were not registered at some point within the past 7 days. 

Values in the Network Health Overview or Insights reports

“The leased spots column shows a value of 0 for some or all venues in my network. What does that mean?”

When the leased spots column shows 0, a spend rate of 0% is expected. This scenario indicates that Vistar has no ads to return (lease) to your venue or set of venues at that point in time.

“What does the value ‘--’ in the spend rate or expiration rate columns mean?”

This value indicates that the results from a calculation are undefined. For example, when you divide 100 by 0, the result is not a real number. Similarly, 0 divided by 0 is an undefined value.

Example from the Insights report in diagnostics:

  • A venue has no leased spots and therefore no spent spots. In this case, the spend rate value for that venue will be undefined (“--”), because 0 divided by 0 is not a true number.

"Why does the spent spots column show a higher value than the leased spots column?"

The leased spots column tracks the number of ads that Vistar returns to your venues when requests are made, while the spent spots column indicates the total number of ads your venues end up playing.  

If you encounter a case where the spent spots for a given time frame (such as an hour or day) are greater than the total number of leased spots, that's an indication of latencies in how soon your ads are played. A healthy integration should serve ads as soon as Vistar's ad server leases them out to the requesting venues and report playbacks within 15 minutes of playing the ads.

The steps necessary to resolve this issue depend on your integration.

  • If you have a native integration with Vistar's ad server, follow up with the relevant contacts of your development team to investigate when ads are played, and when the relevant Proofs of Play (PoPs) are reported back to Vistar. As previously noted, we recommend that you send back PoPs within 15 minutes of playing the ads we serve to your screens. 
  • If you are a media owner on Broadsign, Ayuda, the agent or Cortex, contact support@vistarmedia.com and a member of our team will review your integration set up to determine next steps.
Was this article helpful?
0 out of 0 found this helpful

Articles in this section