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 prerequisites 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.0.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​

1. Add the Teads Maven repository​

The native Android SDK is served from Teads' own Artifactory, so Gradle needs that repository. Add it in your app's android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://teads.jfrog.io/artifactory/SDKAndroid-maven-prod" }
    }
}

If your project centralizes repositories in android/settings.gradle instead, add it to the dependencyResolutionManagement { repositories { … } } block there.

2. Add the AdMob application ID — required even without AdMob​

The native SDK depends transitively on play-services-ads, whose MobileAdsInitProvider crashes at process start if no AdMob application ID is declared. You need this entry even if you never use AdMob:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-XXXXXXXXXXXXXXXX~YYYYYYYYYY" />
    </application>
</manifest>
tip

No AdMob account? Google's own sample ID — ca-app-pub-3940256099942544~3347511713 — initializes the SDK correctly. Replace it with your real ID before shipping if you do monetize through AdMob.

3. 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
}

4. 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. 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. Install pods​

cd ios
pod install

TeadsSDK is published on the CocoaPods trunk and is declared by the plugin's own podspec, so a plain pod install resolves it — no manual pod line needed.

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 Configurations for the other placements' test IDs.

Troubleshooting Installation​

Android​

Could not resolve tv.teads.sdk.android:sdk The Teads Maven repository is missing, or your build blocks project-level repositories. Verify Step 2.1, and check whether settings.gradle sets repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) — if it does, the repository must be declared in settings.gradle, not build.gradle.

App crashes immediately on launch, before any Flutter code runs The AdMob APPLICATION_ID meta-data entry is missing. See Step 2.2.

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

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​

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. Integration Guide — implement each placement
  2. Prerequisites — the full pre-release checklist
  3. Test Configurations — test PIDs and widget IDs
info

Need help? See the Troubleshooting Guide or contact support.