Skip to main content

Installation

This guide covers adding teads_flutter to your app and completing the Android and iOS setup.

info

Before you begin: check the requirements for the Flutter, iOS, and Android versions the plugin requires.

Step 1: Add the Dependency​

Add teads_flutter to your app's dependencies:

flutter pub add teads_flutter

This adds the package to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  teads_flutter: ^1.1.0

Alternatively, if depending on a specific git revision or local copy:

dependencies:
  teads_flutter:
    git:
      url: <repository URL provided by your Partner Manager>
      ref: <tag or branch>

Then fetch dependencies:

flutter pub get

Step 2: Android Setup​

No Maven repository to add (from 1.1.0)

The native Android SDK is served from Teads' own Artifactory, and from 1.1.0 the plugin registers that repository for your build itself. 1.0.0 does not, so on 1.0.0 add it yourself. The one exception: if your app declares its repositories centrally in android/settings.gradle (dependencyResolutionManagement { … }), Gradle ignores repositories contributed by plugins, so add it to that block yourself:

maven { url "https://teads.jfrog.io/artifactory/SDKAndroid-maven-prod" }

1. Pin the NDK version​

The native SDK's transitive dependencies need a newer NDK than Flutter's default. Set it explicitly in android/app/build.gradle:

android {
    ndkVersion = "27.1.12297006" // or newer
}

2. Check minSdk​

The plugin requires minSdk 24. Flutter 3.44+ already defaults to 24, so minSdk = flutter.minSdkVersion is sufficient. If your app pins a lower value, raise it.

ProGuard / R8

No keep rules to add. The plugin ships its own consumer-rules.pro, which your release build inherits automatically — including the rule for the native SDK's optional Huawei Mobile Services reference that would otherwise fail R8 with Missing class com.huawei.hms.ads.identifier.AdvertisingIdClient.

Step 3: iOS Setup​

1. Set the deployment target​

Flutter itself requires iOS 15.0 or later. Set the Runner target's deployment target to 15.0 — and, if your app uses CocoaPods, in ios/Podfile:

platform :ios, '15.0'
The floor is Flutter's, not Teads'

The native TeadsSDK still supports iOS 14.0. Flutter's own engine pod requires 15.0, and flutter build rewrites your Podfile, Runner.xcodeproj and AppFrameworkInfo.plist on the spot if it finds anything lower — so set 15.0 up front rather than discovering the migration in a diff.

2. Native dependencies​

The plugin supports both of Flutter's iOS dependency managers, and brings TeadsSDK with it either way — no manual pod line or package reference needed:

  • Swift Package Manager (Flutter's default since 3.44): TeadsSDK is resolved from https://github.com/teads/TeadsSDK-iOS on the next flutter run / flutter build.
  • CocoaPods: run pod install in ios/; TeadsSDK is resolved from the CocoaPods trunk.
Teads AdMob mediation

Mediating Teads through AdMob needs the native adapters as well — and on Swift Package Manager, the adapter must come from the Swift package, not the pod. See AdMob mediation.

3. Add the tracking usage description​

To request the IDFA you must declare why, in ios/Runner/Info.plist:

<key>NSUserTrackingUsageDescription</key>
<string>Allows us to show you more relevant ads.</string>

Without this key iOS denies the request outright instead of prompting, and the SDK correctly withholds the advertising identifier. See Privacy & Consent for the request itself.

4. Open the workspace, not the project​

open ios/Runner.xcworkspace

Step 4: Configure the SDK​

Call configure once, before any placement is created:

import 'package:flutter/material.dart';
import 'package:teads_flutter/teads_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await TeadsSdk.configure('YOUR_APP_KEY');
  runApp(const MyApp());
}
iOS App Tracking Transparency: request it after the first frame

Do not await TeadsPrivacy.requestTrackingAuthorization() before runApp. On a physical device the completion handler never fires while there is no UI on screen, so the app hangs on a white screen. The iOS Simulator hides this. Request it from your first screen instead — see Privacy & Consent.

Step 5: Verify the Installation​

flutter pub get
flutter analyze

Then build for each platform:

# Android
flutter build apk --debug

# iOS
flutter build ios --debug --no-codesign

A quick smoke test — this renders a test creative with no live campaign needed:

MediaPlacement(
  config: MediaPlacementConfig(pid: 84242),
  onReady: () => debugPrint('Teads: ad ready'),
  onFailed: (error) => debugPrint('Teads: failed — ${error.reason}'),
)

See Test PIDs and Configurations for the other placements' test IDs.

Troubleshooting Installation​

Android​

Could not resolve tv.teads.sdk.android:sdk Your app declares its repositories in settings.gradle's dependencyResolutionManagement block, so the repository the plugin registers is ignored. Add the Teads repository to that block — see the note under Step 2.

NDK-related build failure, or a version-mismatch warning Pin the NDK explicitly. See Step 2.1.

Unsupported class file major version / JDK errors Use JDK 17 or 21. Android Studio's bundled JBR normally satisfies this with no setup; otherwise point JAVA_HOME at a JDK 21 install.

iOS​

Multiple commands produce …/TeadsSDK.framework The app gets TeadsSDK from two places — usually the TeadsAdMobAdapter pod next to the plugin's Swift package. Take the adapter from the Swift package instead; see AdMob mediation.

pod install fails to find TeadsSDK Update CocoaPods (sudo gem install cocoapods), then rm -rf ios/Pods ios/Podfile.lock && cd ios && pod install.

Missing-framework errors in Xcode Open Runner.xcworkspace, not Runner.xcodeproj.

Deployment-target errors Confirm platform :ios, '15.0' in the Podfile, and that the Runner target's IPHONEOS_DEPLOYMENT_TARGET is 15.0 or higher. If your Podfile has a post_install hook that pins IPHONEOS_DEPLOYMENT_TARGET, raise that too — a hook left at 14.0 puts the pods below the app that links them.

Next Steps​

  1. Formats — implement each placement
  2. Prerequisites — the full pre-release checklist
  3. Test PIDs and Configurations — test PIDs and widget IDs
info

Need help? See the Troubleshooting Guide or contact support.