Skip to main content

Prerequisites & Setup Checklist

info

Before you begin: this checklist covers everything needed for a successful Teads Flutter SDK integration, and everything to verify before you ship.

Development Environment Requirements​

Flutter​

  • Flutter 3.44+ — the version whose build-dependency validation sets the Android floors below
  • Dart 3.12+
  • Verified clean on Flutter 3.47.2 / Dart 3.13.2

iOS​

  • macOS (required for iOS builds)
  • Xcode with an iOS 15+ SDK
  • iOS 15.0+ deployment target — Flutter's floor, not the native SDK's
  • CocoaPods 1.11+

Android​

  • minSdkVersion 24+ — Flutter 3.44's own floor
  • compileSdk 36
  • NDK 27.1.12297006 or newer, pinned explicitly
  • JDK 17 or 21 — normally Android Studio's bundled JBR, which needs no setup
  • Kotlin 2.2.20+, AGP 8.11.1+, Gradle 8.14.3+
Toolchain floors move together

If your app predates these versions, expect to bump Kotlin, AGP and Gradle in lockstep. The native SDK's compiled Kotlin metadata forces the floor — you cannot raise one alone.

Mandatory Global Checklist​

1. SDK version​

  • Use the latest version of the plugin available to you
  • Review the release notes for breaking changes before upgrading

2. Ad display requirements​

  • Ads must be fully visible, clickable, and start properly
  • No widget may cover the placement — not even a transparent one. An Opacity, IgnorePointer, Stack overlay or gradient scrim over a placement breaks viewability measurement and can suppress revenue entirely
  • Do not wrap a placement in a fixed-height SizedBox that clips it — the placements size themselves
  • Verify placements work in ListView, CustomScrollView and PageView
  • Test in both orientations

3. Brand safety configuration​

  • Provide a valid article URL on every placement — this drives contextual targeting and brand safety
  • articleUrl on MediaPlacementConfig, FeedPlacementConfig, BannerPlacementConfig and InterstitialPlacementConfig
  • URLs must be reachable from all regions you serve
  • Pass the URL of the actual content the user is reading, not a generic homepage

4. App-ads.txt setup​

  • Publish an app-ads.txt at the root of the developer website listed on your store pages

  • Include the Teads entry:

    teads.tv, YOUR_PUBLISHER_ID, DIRECT, 15a9c44f6d26cbe1

  • Verify it is publicly accessible at https://yourdomain.com/app-ads.txt

  • Contact your account manager for your publisher ID

Revenue impact

Not listing Teads in your app-ads.txt directly reduces ad serving and revenue from our demand partners.

5. Privacy compliance​

  • Enable GDPR/CCPA/GPP handling where applicable
  • A standards-compliant CMP needs no SDK calls at all — the SDK reads the IAB keys your CMP already writes
  • Only use TeadsPrivacy if you have a custom CMP or a server-driven consent decision
  • See the Privacy & Consent Guide

6. App Tracking Transparency (iOS)​

  • Add NSUserTrackingUsageDescription to Info.plist — without it iOS denies the request instead of prompting
  • Call TeadsPrivacy.requestTrackingAuthorization() after your first frame renders, and before creating placements
  • Treat a null return as "not applicable" (Android), not "declined"

7. Native configuration​

  • Android: Teads Maven repository added, AdMob APPLICATION_ID meta-data present, NDK pinned
  • iOS: platform :ios, '15.0' in the Podfile, pod install run
  • iOS: viewWillTransition forwarded if you use BannerPlacement

8. Integration validation​

  • TeadsSdk.configure() called exactly once, before any placement
  • Every placement type you use tested on both platforms
  • Event callbacks firing
  • InterstitialPlacement.dispose() called
  • RecommendationsViewabilityReporter.dispose() called

Flutter-Specific Requirements​

Widget lifecycle​

  • InterstitialPlacement is not a widget — it holds a native WebView and an Open Measurement session. Call dispose() from your State.dispose().
  • RecommendationsViewabilityReporter owns timers — call untrack when a GlobalKey is reused and dispose() when the list is torn down.
  • MediaPlacement, BannerPlacement and FeedPlacement clean up their own platform views on unmount.

Platform views​

Media and Banner are platform views (AndroidView / UiKitView). Two consequences:

  • They cannot render in flutter test. Widget-test around them, or use the mocks from package:teads_flutter/teads_flutter_mocks.dart.
  • Avoid giving each row of a long list its own placement. A platform view per list item is a known-bad Flutter pattern regardless of which plugin creates it.

State management​

  • Rebuilding a placement with an unchanged config is safe
  • Changing FeedPlacementConfig.darkMode via copyWith pushes into the loaded page; changing any other field only takes effect when the page is recreated
  • Do not recreate placements on every rebuild — hold the config, or use a const constructor where possible

Multiple Feed placements​

  • Use widgetIndex: 0 for the first, then 1, 2, … for the rest
  • A non-zero widgetIndex never loads unless a widgetIndex: 0 placement loads on the same page. See the Integration Guide.

Pre-Release Testing Checklist​

Test configuration​

  • Test each placement with the IDs in Test Configurations
  • The widget ID selects the ad format — pointing Banner or Interstitial at Feed's MB_1 serves a feed, which looks exactly like a broken placement
  • Remove enableValidationMode and testDisplay before release

Devices and environments​

  • Multiple device types (phones and tablets, iPhone and Android)
  • Minimum and latest supported OS versions
  • Wi-Fi, cellular, and degraded connections
  • Different consent scenarios, including a full reject
  • Always test on real devices before release — see the note on emulator DNS in the Troubleshooting Guide

Cross-platform​

  • Consistent behavior on iOS and Android
  • Rotation on both (remember the iOS viewWillTransition forwarding for Banner)
  • Dark mode on both
  • Feed fullscreen video enter and exit

Performance​

  • Profile scrolling with placements present, in --profile mode
  • Watch memory across many placement create/dispose cycles
  • Confirm placements are disposed when screens are popped

User experience​

  • Ads do not interfere with app functionality or navigation
  • Clicks and video playback behave correctly
  • Errors degrade gracefully — an ad that fails should leave no broken layout

Common Issues to Avoid​

Integration​

  • Don't ship test PIDs or validation mode
  • Don't call Recommendations.registerClick before an actual tap — it reports the click
  • Don't forget InterstitialPlacement.dispose()
  • Don't cache the result of interstitial.isReady
  • Don't await requestTrackingAuthorization() before runApp

Configuration​

  • Don't omit articleUrl
  • Don't skip app-ads.txt
  • Don't forget the AdMob APPLICATION_ID — the app crashes at process start without it
  • Don't use a non-zero widgetIndex without a widgetIndex: 0 placement on the page

Flutter-specific​

  • Don't remove widgets from the tree around a fullscreen Feed — collapse them instead
  • Don't place a transparent overlay over a placement
  • Don't give every list row its own platform view
  • Don't run more than one BannerPlacement at a time

App Submission for Review​

Before going live, submit your app to Teads for review:

  • Contact your publisher manager to learn how to submit
  • The review verifies that viewability and brand safety work as expected in your integration
info

Required for review: debuggable iOS and Android builds, so network traffic can be inspected.

Next Steps​

  1. Installation — the setup steps in detail
  2. Integration Guide — implement your placements
  3. Test Configurations — develop against the test IDs
  4. Privacy & Consent — get consent handling right

Support​

tip

Pro tip: keep this checklist handy and re-run it before each release.