Integration troubleshooting guide

Check your Bulk Register CSV file and verify the following:

1. There are no duplicate values in the following columns:
   1. device_uid
   2. device_name
2. The values in the device_name column do not already exist in your Fleet account.
3. The network_name exists in your Fleet account.
4. All required columns are filled out (see Edit devices in bulk).
5. There are no special characters in the CSV file. This can occur automatically if you copied and pasted information directly from an external source.
6. You are using the original formatting in the CSV file:
   1. Values in the original CSV file are strings. When these fields are copied and pasted into a new workbook, the formatting can be removed and they are no longer strings.
   2. Make sure to paste with the Keep Source Formatting option when you copy from the original CSV file and paste information into a new workbook.

Check your Bulk Edit CSV file and verify the following:

1. There are no duplicate values in the device_name column.
2. All required columns are filled out (see Edit devices in bulk).
3. There are no special characters in the CSV file. This can occur automatically if you copied and pasted information directly from an external source.
4. You are using the original formatting in the CSV file:
   1. Values in the original CSV file are strings. When these fields are copied and pasted into a new workbook, the formatting can be removed and they are no longer strings.
   2. Make sure to paste with the “Keep Source Formatting” option when you copy from the original CSV file and paste information into a new workbook.

1. Verify that Vistar Media Ads application parameters are correct:
   • View Manage network and device parameters to find your device’s parameters and confirm that the parameters and values are correct.
2. Ensure that your ad platform setup is correct:
3. Verify that you have line items set up in the ad platform and that they are targeting your venue. See the following documentation for more information:
   1. Create line items
   2. Add targeting to line items
4. If there are any creatives targeting your venue, verify that the creatives are returning to your device based on what is configured in Fleet for Vistar Media Ads application parameters.
5. Ensure that Vistar is leasing ads to your device:
   • See the Diagnostics dashboard to learn more about leased ads.

Verify that Vistar Media Ads application parameters are correct:

• View Manage network and device parameters to find your device’s parameters and confirm that the parameters and values are correct.

Verify that Vistar Media Ads application parameters are correct:

• View Manage network and device parameters to find your device’s parameters and confirm that the parameters and values are correct.

Advanced troubleshooting

For Ayuda or Broadsign integrations, complete the following troubleshooting steps (in addition to the previous steps listed):

1. Confirm that you received the correct asset (Ayuda) or Web Redirect URL (Broadsign) from Vistar.
2. Verify that you scheduled the asset properly:
   • Ayuda Administrator—See Step 2.
   • Broadsign Administrator—See Step 4.
3. Confirm that you added the asset (Ayuda) or Web Redirect URL (Broadsign) to a campaign:
   • Ayuda Administrator—See Step 2.
   • Broadsign Administrator—See Step 4.
4. Confirm that you configured Ayuda Administrator or Broadsign Administrator correctly:
   • Ayuda Administrator—See Step 3.
   • Broadsign Administrator—See Step 3.
5. Verify that you gave Vistar the correct ID:
   • Ayuda—Face ID. You can verify that you gave Vistar the correct Face ID by looking in the player’s formal_location.xml file or by sending Vistar this file.
   • Broadsign—Player ID.
6. Confirm if you have firewall and cloud extender settings enabled. If you do, request one-time exceptions or enable port forwarding for the following:
   1. Outbound ad request ports (for both the old asset and the latest asset)
      1. Port 443
      2. Over https
   2. Domains (the domains the outbound connection hits)
      1. Old asset
         • *.vistarmedia.com (covers vistar.url parameter values, transcodes-cdn.vistarmedia.com, assets-cdn.vistarmedia.com)
      2. Latest asset
         • *.cortexpowered.com (covers stem2.cortexpowered.com, fleet.cortexpowered.com)
         • *.vistarmedia.com (covers vistar.url parameter values, transcodes-cdn.vistarmedia.com, assets-cdn.vistarmedia.com)
           
           Note: For both the old asset and the latest asset, you should not whitelist inbound communication. Your devices should be able to reach out to the internet but not vice versa.

The device may have poor internet connectivity.

1. Confirm if your device’s location has previously had issues with making ad requests.
2. Verify that your device has enough bandwidth to make ad requests consistently. This is the internet connection bandwidth (upload and download speeds).
3. Confirm if you can hit one of the following URLs, depending on the environment your device is in, on the device in a browser or command line to see if you get a response in a reasonable amount of time:
   • Staging environment - https://sandbox-api.vistarmedia.com/api/v1/get_ad/json
   • Production environment - https://api.vistarmedia.com/api/v1/get_ad/json

1. Confirm if this issue is happening on one device, some devices with similar characteristics, or all devices.
2. Confirm if there were any recent changes made by your team that could have triggered this behavior.
3. View Manage network and device parameters to find your device’s parameters and confirm that the parameters and values are correct.
   • Specifically, verify that the vistar.static_duration and vistar.required_completion parameters and their values are set and correct.
4. Check your device’s internet connectivity by checking the connection speed of the device (upload and download speeds).
5. Confirm that your device has the correct time:
   • If your device’s time is incorrect, PoPs could not be hit because there is a discrepancy between the device’s time and the ad server's time. This means that a PoP could be sent before the ad is actually played or way after the ad is played (according to the time that is being sent by the device).
6. Verify that the latitude and longitude set for your device in the ad platform are correct and valid.
7. Confirm if you have firewall and cloud extender settings enabled. If you do, request one-time exceptions or enable port forwarding for the following:
   1. Outbound ad request ports (for both the old asset and the latest asset)
      1. Port 443
      2. Over https
   2. Domains (the domains the outbound connection hits)
      1. Old asset
         • *.vistarmedia.com (covers vistar.url parameter values, transcodes-cdn.vistarmedia.com, assets-cdn.vistarmedia.com)
      2. Latest asset
         • *.cortexpowered.com (covers stem2.cortexpowered.com, fleet.cortexpowered.com)
         • *.vistarmedia.com (covers vistar.url parameter values, transcodes-cdn.vistarmedia.com, assets-cdn.vistarmedia.com)
           
           Note: For both the old asset and the latest asset, you should not whitelist inbound communication. Your devices should be able to reach out to the internet but not vice versa.

Advanced troubleshooting

For agent integrations, complete the following troubleshooting steps (in addition to the previous steps listed):

• Make sure you are Indicating Start of Ad Play and Sending Proof of Plays to the agent

1. Confirm if this issue is happening on one device, some devices with similar characteristics, or all devices.
2. Confirm if there were any recent changes made by your team that could have triggered this behavior.
3. Confirm if your device’s location has previously had issues with hitting PoPs.
4. View Manage network and device parameters to find your device’s parameters and confirm that the parameters and values are correct.
   • Specifically, verify that the vistar.static_duration and vistar.required_completion parameters and their values are set and correct.
5. Verify that your device has enough bandwidth to hit PoPs consistently. This is the Internet connection bandwidth (upload and download speeds).

Advanced troubleshooting

For Ayuda or Broadsign integrations, complete the following troubleshooting steps (in addition to the previous steps listed):

1. Confirm the spot duration set on your venues in Vistar.
2. Confirm the spot duration set for the Vistar spot in your CMS matches the spot duration set in Vistar.
   • If the spot duration between your venues in Vistar do not match the configuration of the Vistar campaign in your CMS, this can cause many venues to fail to hit the PoP, see a black screen, or end the spot too early.

For agent integrations, complete the following troubleshooting steps (in addition to the previous steps listed):

1. Check the ad_client section of Internal State for your device in Fleet. If there is more than one entry, the client (where ads are being displayed on the device) is making ad requests, but is not sending PoPs or expires for the ad.
2. View Manage network and device parameters to find your device’s parameters and confirm that the parameters and values are correct.
   • Specifically, verify that the vistar.required_completion parameter is set up and correct.

1. Confirm the internet connectivity of your device.
   • An error during creative rendering can cause a failure in fetching the creative from the ad server.
2. Confirm that the expected creatives are cached on the device.
   • An error during creative rendering can cause a failure in caching the creative.

Advanced troubleshooting

For player integrations, complete the following troubleshooting steps (in addition to the previous steps listed):

1. Verify if the vistar.always_expire parameter is set to True for your device.

For Ayuda HTML5 integrations, the asset could be looking in a different file path for the creatives than where the creatives are actually stored:

1. Verify that the Forward & Store configuration in Ayuda is correct (see Step 4).
2. Confirm with Vistar that your file path configuration for your creatives is correct.

This can occur because, at the time, the agent integration was not fully built. You may be seeing ads displayed on your screen and proof of plays (PoPs) being hit according to ad platform reporting, but in Fleet, your device has no record of these events.

This is because you are sending PoPs directly to the ad server and not to the agent. Overall, you completed the "Making Ad Requests" and "Receiving Ad Responses" part of the integration but not the "Indicating Start of Ad Play," "Sending Proof of Plays," or "Sending Expires" parts of the integration, as outlined in the agent integration documentation.

Advanced Troubleshooting

1. Verify that the agent is receiving records of ad display:
   1. Confirm that ads are being displayed in the Display Status section of a device’s Overview page.
   2. Confirm that content-rendered Events are showing up in the Events tab on your device’s Overview page.
   3. Confirm that you see the following entry in the local_server section of the Internal State of your device:
      • "/ads/start": {
      • "avg_latency": "x",
      • "statuses": {
      • "<status code>": <number of entries for the status code>
2. Verify that the agent is receiving records of PoPs.
   1. Confirm that you see the following entry in the local_server section of the Internal State of your device:
      • "/ads/confirm": {
      • "avg_latency": "x",
      • "statuses": {
      • "<status code>": <number of entries for the status code>

Note: Remote upgrades for Player versions below v2.12.9 is not supported. 

1. Wait for the upgrade to synchronize to your device.
   • Depending on the amount of devices you are upgrading at one time and amount of bandwidth available to them, this process could take some time. The Cortex player upgrade process occurs in two steps:
     1. When a Player upgrade is requested in Fleet, a record is created in our database.
     2. Then, the request is sent to the device.
2. Check the device’s internet connectivity:
   • Check the connection speed of the device (upload and download speeds).
3. Confirm the location’s bandwidth limit:
   • Confirm the device location’s bandwidth limit per month to ensure that there is enough bandwidth for the upgrade.

Check the device’s internet connectivity by viewing the Wi-Fi icon in the top right corner.

• A green icon indicates that the Wi-Fi is working as expected. You should only see this screen for a few seconds.
• A red icon indicates no or poor internet connectivity. The Cortex player will be unable to start up until that is resolved.

If the device has an internet connection but Cortex is showing a red icon, please doublecheck any firewall issues that could be blocking Cortex. Also make sure that the device's clock is configured to the correct timezone. 

This message can appear if you upgraded your players by manually copying over the latest player software.

1. Stop running your players.
2. Delete the following:
   • %localappdata%/CortexPlayer
   • %localappdata%/cortex-player
   • %localappdata%/nwjs
3. Restart your players.

1. Verify that there is content in the Fallback Loop.
   • This issue can occur if there is no fallback content and there’s an issue with the content in the Main Loop.
2. Verify that any creatives (content and ads) that have run on the device appear in the cache section of the device’s Internal State.
   • There is a list of creatives that played on your device in the Events tab (see View events in Fleet). These events are listed as content-rendered in the Information Events.
3. Verify that the creatives are not corrupted.
   • This issue can occur if there is something wrong with the file (a corrupted creative) and therefore cannot be rendered.
4. Verify that there is no operating system (OS) or hardware problem.
   • If you are seeing a black screen with video ads or video content, it may be an OS or hardware issue.

Advanced troubleshooting

You may be using the incorrect browser implementation in Ayuda Administrator or Broadsign Administrator. You must use Chromium as the browser to display content from the exchange.

For Ayuda or Broadsign integrations, complete the following troubleshooting steps (in addition to the previous steps listed):

1. Confirm that you configured Ayuda Administrator or Broadsign Administrator correctly:
   • Ayuda Administrator–See Step 3.
   • Broadsign Administrator—See Step 3.

2. Confirm the spot duration set on your venues in Vistar.

3. Confirm the spot duration set for the Vistar spot in your CMS matches the spot duration set in Vistar.

   • If the spot duration between your venues in Vistar do not match the configuration of the Vistar campaign in your CMS, this can cause many venues to fail to hit the PoP, see a black screen, or end the spot too early.

For Broadsign, test your Vistar-provided Web Redirect URL in your Chrome browser to see if it returns an ad.

Verify that the player health endpoint can be resolved. The player exposes a local server hosted at http://localhost:8000. This is used to confirm the player's health by the Watchdog. The localhost of a device is usually configured as:

127.0.0.1 localhost

On Windows, the hosts file is located in:

• C:\Windows\System32\drivers\etc\hosts

On Linux, the hosts file is located in:

• /etc/hosts/

If this server is not reachable, Watchdog may restart the player process repeatedly.

1. Confirm if you are able to load the operating system (OS) of your device.
   • If yes, complete Step 2 of this section.
   • If no, this is a hardware issue. See the following to confirm the hardware issue:
     • You may have received a “bad batch” of devices from your hardware manufacturer. A “bad batch” of devices exhibits behavior that is isolated to only those devices and not to all of your devices. The following are characteristics that a “bad batch” of devices may have in common:
       • Shipped from the hardware manufacturer around the same time.
       • Same model, build, version number, image, and so on.
       • Went down within days of one another (for example, dropping off incrementally).
       • Additional indicators:
         • OS does not run normally.
         • OS tries to start up and fails. You will know that the device is unable to load its OS if you start the device and it does not boot as expected. Not booting as expected means:
           • Device cannot get to the home screen (if the OS has a GUI).
           • Device cannot open up a terminal (if the OS does not have a GUI).
           • Device displays a disk failure message on-screen.
     • If this is occurring with your device, it is recommended to reach out to your hardware manufacturer.
2. Identify when the most recent player upgrade was completed.
   • This confirms if the issue coincides with a recent player upgrade.
3. Confirm whether or not your devices are able to connect to Cortex’s backend. To do so, complete the following:
   • Enter https://sstem2.cortexpowered.com/ into a Chrome browser on your device.
     • If you receive a 400 - Bad Request error, this shows that you can connect to Cortex.
     • If you do not receive an error, you could be experiencing network connection issues. For example, a firewall could be blocking Cortex from running if your device has internet connection but shows that it is Offline in Fleet.
4. Contact support@vistarmedia.com if the previous steps did not resolve the issue. Include the following log information in your request.
   • For Windows:
     1. Enter File Explorer in the Task Bar search field.
     2. Select File Explorer.
     3. Select View in the top-left corner of the window that opens.
     4. Select Hidden items in the Show/hide section.
     5. Navigate to Windows (C:) > Users > select the folder for the user of the computer > AppData > Roaming. The Cortex folder appears.
     6. Right-click the Cortex folder and hover your cursor over Send to.
     7. Select Compressed (zipped) folder.
     8. Attach the zip file to the Zendesk ticket.

Check your device’s rotation settings in Fleet, see Rotate the image on your screen.

Advanced troubleshooting

You may have rotated the creative returned by Vistar before putting it into Broadsign. For Broadsign integrations, complete the following troubleshooting steps (in addition to the previous steps listed):
Verify if you have implemented rotation settings in your CMS (see The Column Selector Menu section in Broadsign’s Display Types documentation).

The following common issues can cause your device to display black screens, depending on the integration type. It is recommended to check your player’s device logs for any messages related to the issues outlined below. Depending on your integration, see Ayuda or Broadsign sections below.

Ayuda

• A firewall issue—Confirm if you have firewall and cloud extender settings enabled. If you do, request one-time exceptions or enable port forwarding for the following:
  • Outbound ad request ports (for both the old asset and the latest asset)
    • Port 443
    • Over https
  • Domains (the domains the outbound connection hits)
    • Old asset
      • *.vistarmedia.com (covers vistar.url parameter values, transcodes-cdn.vistarmedia.com, assets-cdn.vistarmedia.com)
    • Latest asset
      • *.cortexpowered.com (covers stem2.cortexpowered.com, fleet.cortexpowered.com)
      • *.vistarmedia.com (covers vistar.url parameter values, transcodes-cdn.vistarmedia.com, assets-cdn.vistarmedia.com)
        
        Note: For both the old asset and the latest asset, you should not whitelist inbound communication. Your devices should be able to reach out to the internet but not vice versa.
• A hardware issue—Black screens caused by a hardware issue generally reveal themselves when video content tries to play. To confirm if it is a hardware issue, disable videos on the device and see if you still are seeing black screens.
• A one-off issue—Check to see what is reported in the logs or any specific console messages.

Broadsign

• A firewall issue—Player logs may show 2xx status codes. Confirm if you have firewall and cloud extender settings enabled. If you do, request one-time exceptions or enable port forwarding for the following:
  • Outbound ad request ports
    • Port 443
    • Over https
  • Domains (the domains the outbound connection hits)
    • *.cortexpowered.com (covers stem2.cortexpowered.com, fleet.cortexpowered.com)
    • *.vistarmedia.com (covers vistar.url parameter values, transcodes-cdn.vistarmedia.com, assets-cdn.vistarmedia.com)
      
      Note: You should not whitelist inbound communication. Your devices should be able to reach out to the internet but not vice versa.
• An issue with skipping—Player logs may show 4xx status codes. You should not see a black screen because your player should skip the Vistar spot. If that is not the case, provide Vistar with your player’s logs.
• An issue with Vistar—Player logs may show 5xx status codes. If this is the case, provide Vistar with your player logs.
• A hardware issue—Confirm if your devices have hardware specifications that differ from your properly-functioning devices. Some differing characteristics can be hardware configurations or drivers and operating system specifications.

Your Ayuda or Broadsign player may not be able to handle content in certain sequences. For example, the sequence of flash content in one spot and Vistar’s Broadsign Web Redirect URL in the next spot may not allow the Vistar spot to be played every time it is hit.

For Ayuda or Broadsign integrations, complete the following troubleshooting steps:

• Change the problematic spot (that is played before the Vistar spot) to an image or video to see if the Vistar spot begins to play normally.

Your Ayuda Player may not be configured to handle Vistar’s HTML5 asset / bundle.

• Confirm that that there is enough memory for your Ayuda player to use when running Vistar’s HTML5 asset / bundle.

Advanced troubleshooting

For agent integrations, complete the following troubleshooting steps (in addition to the previous steps listed):

• Confirm that you do not have any administrative privileges or device configurations that are blocking the agent from running on your device.
• Confirm that your device does not have scheduled tasks or scripts that are blocking the agent from running. Note that the order of the scheduled tasks and scripts is important because it can prevent the agent from running.

You may be seeing a video-player-crashed Event in Fleet.

1. Check that the video file that is not playing / crashing is not corrupt by downloading and playing the video file to see if you encounter any issues.
2. Check that the video file is cached on the device. You can do so as outlined in Device caching behavior.
3. Check the Data Rate of the video file. As an example, a Data Rate of 15 Mbit/s is considered high. Reduce the Data Rate of your video file. We cannot recommend any Data Rate specifically since it depends on the hardware you are using.

There may be a permissions issue on your device. It is not expected behavior for you to be prompted to approve or deny the downloading of creatives. Creatives should automatically be downloaded as content and ads are cached in the background.

Check that the Cortex player or agent has permissions to download creatives to your device.

1. Check the device’s caching behavior.
   
   A device downloading creatives in real time for every ad request / ad response cycle will contribute to increased data consumption.
   
   
   • Verify that all creatives (content and ads) that have run on the device and all creatives targeting the device have been cached by checking the cache section of the device’s Internal State.
2. Collect data usage stats.
   1. Send Vistar an Internet Service Provider (ISP) report for the devices experiencing high data consumption. This report should contain daily and hourly breakdowns of data usage numbers per domain name and IP address.
   2. Upgrade the devices experiencing high data consumption to the latest version of the Cortex player or agent, as these versions include improvements that will reduce data usage. Your devices must be online in order to pick up a player or agent version after an upgrade has been initiated.
   3. Measure data usage on your devices and send this data usage report to Vistar.
3. Whitelist Cortex domains.
   • Cortex domains are .cortexpowered.com and .vistarmedia.com. Note that there are various names those domains can start with, but that the ending will always be consistent.

This is normal. Each Cortex player process that you see represents a Cortex application that is being used. Some of these applications are visible to you in Fleet (Web Page app, Vistar Media Ads app, and so on) and some are not.

All of the running processes are needed for the player to run properly, so none of the processes should be killed. As an example, when you use Google Chrome and you have 10 tabs open, there would be 10 separate Google Chrome processes running to represent that.