Skip to main content

Troubleshooting Guide

info

This comprehensive guide covers common implementation issues, testing procedures, and solutions for the Teads SDK on Android. Follow this guide before contacting your Teads representative.

warning

Before jumping into possible issues and solutions, always ensure you're using the latest SDK version and following the implementation guidelines.

Prerequisites & Setup​

info

Before troubleshooting: Ensure you've completed all prerequisites and setup requirements. See the Prerequisites & Setup Checklist for a complete list of mandatory requirements.

Quick Checklist:

  • Using latest SDK version
  • Ads are fully visible and clickable
  • Brand safety configured
  • App-ads.txt implemented
  • Privacy compliance enabled
  • Integration validated with Validation Tool

Validation Tool​

info

Validation Tool: Use the dedicated Validation Tool page for complete validation instructions, error explanations, and troubleshooting guidance.

Quick Reference:

  • Enable validation mode in your ad settings
  • Run validation for each ad slot
  • Check all validation criteria are met
  • Remove validation mode before production

Test PIDs​

info

Complete Test Configuration: For comprehensive test PIDs and configurations for all placement types (Media, Media Native, Feed, Recommendations), see the dedicated Test PIDs and Configurations page.

warning

Please make sure these PIDs are not used in your production environment.

If no ad is served, please refer to the Common Issues & Solutions section.

Test Specific Creatives​

info

You may need to use specific ads during integration and/or troubleshooting iterations. For that you can use a debugging proxy app, such as Charles or Proxyman. You will then be able to map the Teads ad response in order to serve the creative of your choice.

Getting Started​

  • Download Charles or Proxyman or the debugging proxy app of your preference
  • Ensure to set up your computer, your app project and your testing device according to the docs that your debugging proxy app provides, for instance Charles docs, Proxyman docs
  • Use the "map local" feature from your debugging proxy app in order to map the Teads ad response to a local one, according to the instructions below
info

The instructions below work for Direct and Mediation integrations.

⚠️ Please keep in mind that the ad will start only if visibility conditions are met, see Common Issues & Solutions.

Test a Specific Media Creative​

  1. Download the file inread_mock_response.json
  2. Edit the file by replacing the value from the field content with your VAST url, as below. It should be something similar to https://s8t.teads.tv/vast/6753877076839177
{
  "ads": [
    {
      "type": "VastUrl",
      "content": "YOUR_VAST_URL_HERE"
    }
  ]
}
  1. Map the url https://r.teads.tv/rich/* to the local inread_mock_response.json file you just edited
  2. Navigate to the screen which requests the Teads ad

Test a Media Creative Using Available Samples​

  1. Select one of the available samples from the table below and then download its mock file
  2. Map the url https://r.teads.tv/rich/* to the local mock file you just downloaded
  3. Navigate to the screen which requests the Teads ad
Creative TypeMock file
Videoinread_video_mock_response.json
Imageinread_image_mock_response.json
Scrollerinread_scroller_mock_response.json
Sliderinread_slider_mock_response.json
Carouselinread_carousel_mock_response.json

Test a Specific Media Native Creative​

  1. Download the file native_mock_response.json
  2. Edit the file by replacing the value from the field content with your JSON, as below. Ensure that it follows the standard
{
  "ads": [
    {
      "type": "NativeJson",
      "content": "YOUR_NATIVE_JSON_HERE"
    }
  ]
}
  1. Map the url https://r.teads.tv/rich/* to the local native_mock_response.json file you just edited
  2. Navigate to the screen which requests the Teads ad

Test a Media Native Creative Using Available Samples​

  1. Select one of the available samples from the table below and then download its mock file
  2. Map the url https://r.teads.tv/rich/* to the local mock file you just downloaded
  3. Navigate to the screen which requests the Teads ad
Creative TypeMock file
Videonative_video_mock_response.json
Imagenative_image_mock_response.json

Test Feed Placements​

For testing Feed placements with specific content:

  1. Map API responses: Use your debugging proxy to map and copy responses filtering the URL https://mv.outbrain.com/Multivac/api/get?url=*
  2. Test different configurations: Use various test scenarios to verify different content types
  3. Verify content recommendations: Ensure recommendations are properly displayed and clickable

Test Recommendations API​

For testing the Recommendations API:

  1. Map recommendations endpoints: Use your debugging proxy to intercept API calls filtering the URL https://mv.outbrain.com/utils/get?widgetJSId=*
  2. Test different configurations: Use various test scenarios to verify different recommendation types
  3. Verify custom UI rendering: Test your custom recommendation card implementations
  4. Check viewability tracking: Ensure proper viewability events are fired

Common Issues & Solutions​

Table of Contents​

We're continuously enhancing and adding new features to improve your experience. Stay updated with the latest developments and version changes:

We also provide sample apps for your convenience:

Viewability Issues​

Feed recommendations: viewability is reported when ≥50% of a recommendation is on screen for ≥1 second. Any overlay (even transparent) above the ad/recommendation may prevent viewability.

Video ads: the player follows IAB Open Measurement (OMSDK) rules; obstructions and undersized slots can block start/visibility.

If you see "ad visible = false" or the ad doesn't start/click:

  • Remove overlays above the ad view (toolbars, transparent blockers)
  • Ensure size is sensible (avoid tiny heights).

Test PID Issues​

You are testing one of the Test PIDs but no ad is delivered​

If our server did not reply with an ad (error not-filled) while using a Test PID, please contact your local manager to ensure:

  • Your IP is not flagged as suspicious and is exclude listed due to too many testings and clicks. Please try with a different network connection (switch IP)
  • The country you're testing from is open to Teads delivery

Ad Display Issues​

You received an ad from our server, but you can't click on it or the video doesn't start​

  • Make sure the ad is visible. If you have a transparent overlay above your ad view, such as any other sort of view, our visibility algorithm will consider the ad view as hidden. In this case, you can find the incriminated ad view in your logs and the percentage of its visibility by filtering the logs by adCore.notifyAssetsDisplayChanged.

    Note that TeadsSDK is OM IAB certified, meaning creatives are evaluated by IAB Open Measurement third-party viewability logic, and both TeadsSDK and OMSDK rely on the same logic: any obstruction above the ad view is considered as an ad not visible. This certification is very important for our advertisers.

  • The ad slot is not big enough. An ad will be considered big enough and thus allowed to start only if it satisfies the following two conditions:

    • Both width and height are strictly greater than 150px
    • Width x height is strictly greater than 10,000px

  • If you have a transparent overlay covering all or almost all the screen, such as for displaying a button constantly: consider reducing the overlay to the minimum size, in this case, to the size of the button itself

Creative Issues​

The ad starts but looks cropped​

Some creatives, such as third-party VPAIDs coming from Open Exchange, may need a resize after loading.

These asynchronous resize requests need to be caught by the Teads SDK in order to adapt the ad slot to the right ratio (especially for mediation integration where ad slot sizes are usually fixed).

You'll find in each integration article an "ad resizing" section.

Please ensure this part is implemented so that the Teads SDK ad slot will fit any creative ratio.

You'll find in the Test PIDs section a list of PIDs serving different-sized creatives to let you test the resize implementation.

Production Issues​

Test PIDs are delivering ads but the production PIDs are not (provided by the account manager)​

  • Production PIDs may not always respond with an ad 100% of the time
  • Fill rate can be impacted by several factors (advertising demand, geolocation, article content, user consent, scroll rate, etc.)
  • However, if you want to maximize the chances of getting an ad (fill rate), please ensure:
    • The production PID is not flagged as "Test"
    • Good scroll rate (set the ad slot not at the bottom nor at the top of the article)
    • Good visibility (no element overlaying the ad slot)
    • Brand Safety (mandatory)
    • Privacy & consent management (EU/US mandatory)
    • App-ads.txt (mandatory)

Still Stuck?​

If the issue isn't covered here, please:

  1. Run a Validation Tool session and keep the session URL
  2. Capture device logs filtered by the SDK tag(s)
  3. Document the issue with steps to reproduce
  4. Share both with your Teads contact along with:
    • Device information (model, Android version)
    • App version and build number
    • Placement ID(s) being tested
    • Screenshots or screen recordings if applicable

Contact Information​