Skip to main content

Installation

Installation Methods​

Using Gradle/Maven​

  1. Add the Teads repository to your project/build.gradle:
  2. Add the Teads SDK dependency to your app/build.gradle:
  3. Sync your project

project/build.gradle

repositories {
    maven { url  "https://teads.jfrog.io/artifactory/SDKAndroid-maven-prod" }
    maven {
        // Mandatory for Huawei device compatibility
        url  "https://developer.huawei.com/repo/"
    }
}

app/build.gradle

dependencies {
    implementation("tv.teads.sdk.android:sdk:6.2.0@aar") {
        transitive = true
    }
}

Huawei Device Compatibility​

For Huawei devices, the Huawei repository is mandatory and included in the configuration above.

Sample Application​

The official Teads SDK sample application demonstrates best practices and integration examples.

GitHub Repository: TeadsSDK-android

SDK Initialization​

Initialize the Teads SDK as early as possible in your app's lifecycle:

import tv.teads.sdk.TeadsSDK

// Initialize the SDK with your partner key
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        TeadsSDK.configure(applicationContext, "YOUR_PARTNER_KEY")

       // Enable test mode for development
       if (BuildConfig.DEBUG) {
          TeadsSDK.testMode = true
          TeadsSDK.testLocation = "us" // Optional: Test specific geolocations
       }
    }
}
info

Important: Calling the method the TeadsSDK.configure with your YOUR_PARTNER_KEY is mandatory when using the Feed or Recommendations placements. Otherwise, you can skip this part.

Implementation Samples​

For complete working examples and sample applications, refer to our public GitHub repositories:

These repositories contain:

  • Full working applications demonstrating all placement types
  • Best practices and common integration patterns

Settings​

Find the full settings list for each placement in the Settings Configuration.

Event Handling​

Comprehensive Event Handling​

class ComprehensiveEventHandler : TeadsAdPlacementEventsDelegate {

   override fun onPlacementEvent(
      placement: TeadsAdPlacement<*, *>,
      event: TeadsAdPlacementEventName,
      data: Map<String, Any>?
   ) {
      Log.d("TeadsSDK", "Event: $event from $placement with data $data")

      when (event) {
         TeadsAdPlacementEventName.LOADED -> {
            // Placement is requested to load the ad
            Log.d("TeadsSDK", "Content fully loaded")
         }
          
         TeadsAdPlacementEventName.READY -> {
            // Ad is loaded and ready to display
            Log.d("TeadsSDK", "Ad is ready to be displayed")
         }

         TeadsAdPlacementEventName.RENDERED -> {
            // Ad has been rendered on screen
            Log.d("TeadsSDK", "Ad has been rendered")
         }

         // Interstitial events
         TeadsAdPlacementEventName.WILL_PRESENT -> {
            // Fired right before the fullscreen interstitial is presented
            Log.d("TeadsSDK", "Interstitial will present")
         }

         TeadsAdPlacementEventName.PRESENTED -> {
            // Fired when the fullscreen interstitial has been presented
            Log.d("TeadsSDK", "Interstitial presented")
         }

         TeadsAdPlacementEventName.WILL_DISMISS -> {
            // Fired right before the fullscreen interstitial is dismissed
            Log.d("TeadsSDK", "Interstitial will dismiss")
         }

         TeadsAdPlacementEventName.DISMISSED -> {
            // Fired when the fullscreen interstitial has been dismissed by the user
            Log.d("TeadsSDK", "Interstitial dismissed")
         }

         TeadsAdPlacementEventName.VIEWED -> {
            // Ad has met IAB viewability standards
            Log.d("TeadsSDK", "Ad has met viewability criteria")
         }

         TeadsAdPlacementEventName.CLICKED -> {
            // User clicked on the ad
            // SDK handles URL opening automatically
            Log.d("TeadsSDK", "User clicked on ad")
         }

         TeadsAdPlacementEventName.CLICKED_ORGANIC -> {
            // User clicked on organic content (Feed placement)
            val url = data?.get("url") as? String
            Log.d("TeadsSDK", "User clicked on organic content: $url")
            url?.let {
               // Open in browser or in-app browser
               val intent = Intent(Intent.ACTION_VIEW, Uri.parse(it))
               startActivity(intent)
            }
         }

         TeadsAdPlacementEventName.FAILED -> {
            // Ad failed to load
            // Show fallback content or hide ad container
            val reason = data?.get("reason") as? String
            Log.e("TeadsSDK", "Ad failed to load: $reason")
         }

         TeadsAdPlacementEventName.PLAY -> {
            // Video started playing
            Log.d("TeadsSDK", "Video started playing")
         }

         TeadsAdPlacementEventName.PAUSE -> {
            // Video paused
            Log.d("TeadsSDK", "Video paused")
         }

         TeadsAdPlacementEventName.COMPLETE -> {
            // Video completed
            Log.d("TeadsSDK", "Video completed")
         }

         TeadsAdPlacementEventName.START_PLAY_AUDIO -> {
            // Ad started playing audio
            Log.d("TeadsSDK", "Ad started playing audio")
         }

         TeadsAdPlacementEventName.STOP_PLAY_AUDIO -> {
            // Ad stopped playing audio
            Log.d("TeadsSDK", "Ad stopped playing audio")
         }

         TeadsAdPlacementEventName.HEIGHT_UPDATED -> {
            // Ad height changed (useful for dynamic layouts)
            // This is the height your ad container must match
            val height = data?.get("height") as? Int
            Log.d("TeadsSDK", "Ad height updated to: $height")
         }

         else -> {
            Log.d("TeadsSDK", "Other event: $event")
         }
      }
   }
}
Do not open the URL manually

The SDK automatically handles opening the click URL in the CLICKED event. Do not implement URL navigation in this event handler — doing so will result in the browser opening twice. Use this event only for tracking/analytics purposes.

Best Practices​

1. Placement Lifecycle Management​

Media, Media Native and Interstitial placements​

Call clean() method for Media, Media Native and Interstitial placements when they're no longer needed to prevent memory leaks:

class ContentActivity : AppCompatActivity(), TeadsAdPlacementEventsDelegate {

   override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      // ... setup your placements
   }

   override fun onDestroy() {
      super.onDestroy()

      when (placement) {
         is TeadsAdPlacementMedia -> placement.clean()
         is TeadsAdPlacementMediaNative -> placement.clean()
         is TeadsAdPlacementInterstitial -> placement.clean()
      }
   }
}

Feed and Recommendations placements​

For Feed and Recommendation placements, ensure you load only one ad instance per screen.

To prevent redundant ad requests during view recycling (RecyclerView) or recomposition (LazyList), cache the loaded ad by holding a strong lifecycle aware reference to it.

2. Error Handling​

Always implement proper error handling:


// Handle errors through the delegate
override fun onPlacementEvent(
   placement: TeadsAdPlacement<*, *>,
   event: TeadsAdPlacementEventName,
   data: Map<String, Any>?
) {
   if (event == TeadsAdPlacementEventName.FAILED) {
      // Ad failed to load
      // Show fallback content or hide ad container
      val reason = data?.get("reason") as? String
      Log.e("TeadsSDK", "Ad failed to load: $reason")
   }
}

3. Testing​

Use test mode during development:

// Enable test mode for development
if (BuildConfig.DEBUG) {
   TeadsSDK.testMode = true
   TeadsSDK.testLocation = "us" // Optional: Test specific geolocations
}

Next Steps​

For additional support, see Support