Stay organized with collections
Save and categorize content based on your preferences.
We recommend several best practices to ensure your app functions properly on
Android TV when using the IMA SDK for Android.
Get started by familiarizing yourself with
developing TV apps for Android.
Specifically, make sure your Activity is set up for TV as explained in the
start guide. You
also want to handle
TV navigation to
make sure users can navigate your app well on Android TV.
Handle skippable ads
The SDK optimizes skippable formats for TV-like devices, for example by
removing the ability to engage with a Learn More button. By default, the SDK
sets focus on the skip button when skipping is available so the ad can be
skipped on Android TV. Therefore, no extra work is necessary to support
skippable ads.
For more information on what ads are supported, check out the
compatibility matrix.
Handle VAST icon fallback images
The IMA SDK detects, renders and handles user's interaction with the VAST icon
fallback images. Your app should listen to the ICON_TAPPED and
ICON_FALLBACK_IMAGE_CLOSED events to handle ad playback for ads that use
'Why this ad' (WTA).
Add a boolean to track whether a VAST icon fallback image is showing. Then,
listen to the ICON_TAPPED and ICON_FALLBACK_IMAGE_CLOSED to handle ad
playback around the VAST icon fallback image. See the following code snippet for
an example of how this is handled in the
Advanced Example.
VideoPlayerController.java
// Copyright 2014 Google Inc. All Rights Reserved.packagecom.google.ads.interactivemedia.v3.samples.videoplayerapp;importandroid.app.UiModeManager;importandroid.content.Context;...// Tracks if the SDK is playing an ad, since the SDK might not necessarily use// the video player provided to play the video ad.privatebooleanisAdPlaying;// Tracks whether the SDK has a VAST icon fallback image showing.privatebooleanisConnectedTvFallbackImageShowing=false;// View that handles taps to toggle ad pause/resume during video playback.privateViewplayPauseToggle;// View that we can write log messages to, to display in the UI.privateLoggerlog;...adsManager.addAdEventListener(newAdEvent.AdEventListener(){/** Responds to AdEvents. */@OverridepublicvoidonAdEvent(AdEventadEvent){...caseCONTENT_RESUME_REQUESTED:// AdEventType.CONTENT_RESUME_REQUESTED is fired when the ad is// completed and you should start playing your content.resumeContent();break;caseICON_TAPPED:// The user has tapped a VAST icon fallback image. On Android// mobile apps, the SDK will navigate to the landing page. On// Connected TV devices, the SDK will present a modal dialog// containing the VAST icon fallback image.// Check if the app is running on a TV device.UiModeManageruiModeManager=(UiModeManager)getSystemService(UI_MODE_SERVICE);if(uiModeManager.getCurrentModeType()==Configuration.UI_MODE_TYPE_TELEVISION){isConnectedTvFallbackImageShowing=true;}// Focus the IMA WebView for easier access to ad UI elements.adsManager.focus();break;casePAUSED:if(isConnectedTvFallbackImageShowing){// Do not show the controls; continue to leave the controls in// the hands of the ads SDK.break;}isAdPlaying=false;videoPlayerWithAdPlayback.enableControls();break;caseICON_FALLBACK_IMAGE_CLOSED:// The user has closed the VAST icon fallback image. This may// be a good time to resume ad playback if the user is ready to// continue playing the ad. This event only fires for Connected// TV devices.isConnectedTvFallbackImageShowing=false;adsManager.resume();break;caseRESUMED:isAdPlaying=true;videoPlayerWithAdPlayback.disableControls();break;
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-14 UTC."],[[["\u003cp\u003eFor optimal app functionality on Android TV using the IMA SDK, ensure your Activity is set up for TV and handles TV navigation.\u003c/p\u003e\n"],["\u003cp\u003eThe IMA SDK automatically optimizes skippable ad formats for TV and sets focus on the skip button; no extra configuration is needed.\u003c/p\u003e\n"],["\u003cp\u003eWhen using VAST icon fallback images, implement event listeners for \u003ccode\u003eICON_TAPPED\u003c/code\u003e and \u003ccode\u003eICON_FALLBACK_IMAGE_CLOSED\u003c/code\u003e to manage ad playback and user interaction, especially on Android TV where modal dialogs are used.\u003c/p\u003e\n"],["\u003cp\u003eRefer to the provided code example in the Advanced Example to learn how to track VAST icon fallback image visibility and control ad playback accordingly in your app.\u003c/p\u003e\n"]]],[],null,["# Optimize for Android TV\n\nWe recommend several best practices to ensure your app functions properly on\nAndroid TV when using the IMA SDK for Android.\n\nGet started by familiarizing yourself with\n[developing TV apps for Android](//developer.android.com/training/tv/start/).\nSpecifically, make sure your Activity is set up for TV as explained in the\n[start guide](//developer.android.com/training/tv/start/start). You\nalso want to handle\n[TV navigation](//developer.android.com/training/tv/start/navigation) to\nmake sure users can navigate your app well on Android TV.\n\nHandle skippable ads\n--------------------\n\nThe SDK optimizes skippable formats for TV-like devices, for example by\nremoving the ability to engage with a **Learn More** button. By default, the SDK\nsets focus on the skip button when skipping is available so the ad can be\nskipped on Android TV. Therefore, no extra work is necessary to support\nskippable ads.\n\nYou can configure this by calling\n[`AdsRenderingSettings.setFocusSkipButtonWhenAvailable()`](/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdsRenderingSettings#setFocusSkipButtonWhenAvailable(boolean)).\n\nFor more information on what ads are supported, check out the\n[compatibility matrix](/interactive-media-ads/docs/sdks/android/compatibility).\n\nHandle VAST icon fallback images\n--------------------------------\n\nThe IMA SDK detects, renders and handles user's interaction with the VAST icon\nfallback images. Your app should listen to the `ICON_TAPPED` and\n`ICON_FALLBACK_IMAGE_CLOSED` events to handle ad playback for ads that use\n'Why this ad' (WTA).\n\nAdd a boolean to track whether a VAST icon fallback image is showing. Then,\nlisten to the `ICON_TAPPED` and `ICON_FALLBACK_IMAGE_CLOSED` to handle ad\nplayback around the VAST icon fallback image. See the following code snippet for\nan example of how this is handled in the\n[Advanced Example](//github.com/googleads/googleads-ima-android/tree/main/AdvancedExample).\n\n**VideoPlayerController.java** \n\n // Copyright 2014 Google Inc. All Rights Reserved.\n\n package com.google.ads.interactivemedia.v3.samples.videoplayerapp;\n\n import android.app.UiModeManager;\n import android.content.Context;\n\n ...\n\n // Tracks if the SDK is playing an ad, since the SDK might not necessarily use\n // the video player provided to play the video ad.\n private boolean isAdPlaying;\n\n // Tracks whether the SDK has a VAST icon fallback image showing.\n private boolean isConnectedTvFallbackImageShowing = false;\n\n // View that handles taps to toggle ad pause/resume during video playback.\n private View playPauseToggle;\n\n // View that we can write log messages to, to display in the UI.\n private Logger log;\n\n ...\n\n adsManager.addAdEventListener(\n new AdEvent.AdEventListener() {\n /** Responds to AdEvents. */\n @Override\n public void onAdEvent(AdEvent adEvent) {\n\n ...\n\n case CONTENT_RESUME_REQUESTED:\n // AdEventType.CONTENT_RESUME_REQUESTED is fired when the ad is\n // completed and you should start playing your content.\n resumeContent();\n break;\n case ICON_TAPPED:\n // The user has tapped a VAST icon fallback image. On Android\n // mobile apps, the SDK will navigate to the landing page. On\n // Connected TV devices, the SDK will present a modal dialog\n // containing the VAST icon fallback image.\n // Check if the app is running on a TV device.\n UiModeManager uiModeManager = (UiModeManager) getSystemService(UI_MODE_SERVICE);\n if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION) {\n isConnectedTvFallbackImageShowing = true;\n }\n // Focus the IMA WebView for easier access to ad UI elements.\n adsManager.focus();\n break;\n case PAUSED:\n if (isConnectedTvFallbackImageShowing) {\n // Do not show the controls; continue to leave the controls in\n // the hands of the ads SDK.\n break;\n }\n isAdPlaying = false;\n videoPlayerWithAdPlayback.enableControls();\n break;\n case ICON_FALLBACK_IMAGE_CLOSED:\n // The user has closed the VAST icon fallback image. This may\n // be a good time to resume ad playback if the user is ready to\n // continue playing the ad. This event only fires for Connected\n // TV devices.\n isConnectedTvFallbackImageShowing = false;\n adsManager.resume();\n break;\n case RESUMED:\n isAdPlaying = true;\n videoPlayerWithAdPlayback.disableControls();\n break;"]]