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.

Mandatory Global Checklist​

1. SDK version​

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: NDK pinned
  • iOS: deployment target 15.0 (and platform :ios, '15.0' in the Podfile if you use CocoaPods)
  • 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 Feed guide.

Pre-Release Testing Checklist​

Test configuration​

  • Test each placement with the IDs in Test PIDs and 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

Mediation Checklist (If Applicable)​

For AdMob mediation, also ensure:

  • The native Teads adapters are added on both platforms, at the plugin's Teads SDK version
  • On iOS with Swift Package Manager, the adapter comes from the Swift package (not the pod) and TeadsAdMobMediation.register() is called
  • Media ad slots comply with the resizing behavior of the Media placement
  • Custom events are configured for each format and platform

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 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. Formats — implement your placements
  3. Test PIDs and 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.