Skip to content
This repository has been archived by the owner on Mar 12, 2022. It is now read-only.

Initialize

Jump to bottom
Bruno D'Luka edited this page Apr 4, 2021 · 21 revisions

Initialize the Mobile Ads SDK

Before loading ads, have your app initialize the Mobile Ads SDK by calling MobileAds.initialize() which initializes the SDK and return a Future that completes once initialization is done (or after a 30-second timeout). This can be done only once, ideally at app launch. If you try to initialize it more than once, an AssertionError is thrown

import 'package:flutter/foundation.dart';

String get nativeAdUnitId {
  /// Always test with test ads
  if (kDebugMode)
    return MobileAds.nativeAdTestUnitId;
  else return 'your-native-ad-unit-id';
}

String get bannerAdUnitId {
  /// Always test with test ads
  if (kDebugMode)
    return MobileAds.bannerAdTestUnitId;
  else return 'you-banner-ad-unit-id';
}

String get interstitialAdUnitId {
  /// Always test with test ads
  if (kDebugMode)
    return MobileAds.interstitialAdTestUnitId;
  else return 'you-interstitial-ad-unit-id';
}

String get rewardedAdUnitId {
  /// Always test with test ads
  if (kDebugMode)
    return MobileAds.rewardedAdTestUnitId;
  else return 'you-interstitial-ad-unit-id';
}

String get appOpenAdUnitId {
  /// Always test with test ads
  if (kDebugMode) return MobileAds.appOpenAdTestUnitId;
  else return 'you-app-open-ad-unit-id';
}

String get rewardedInterstitialAdUnitId {
  /// Always test with test ads
  if (kDebugMode)
    return MobileAds.rewardedInterstitialAdTestUnitId;
  else return 'you-interstitial-ad-unit-id';
}

void main() {
  // Add this line if you will initialize it before runApp
  WidgetsFlutterBinding.ensureInitialized();
  await MobileAds.initialize(
    nativeAdUnitId: nativeAdUnitId,
    bannerAdUnitId: bannerAdUnitId,
    interstitialAdUnitId: interstitialAdUnitId,
    rewardedAdUnitId: rewardedAdUnitId,
    appOpenAdUnitId: appOpenAdUnitId,
    rewardedInterstitialAdUnitId: rewardedInterstitialAdUnitId,
  );
  runApp(MyApp());
}

You can always change the default ad unit id by using the setter MobileAds.nativeAdUnitId. Avaiable options:

  • MobileAds.nativeAdUnitId = ...
  • MobileAds.bannerAdUnitId = ...
  • MobileAds.interstitialAdUnitId = ...
  • MobileAds.rewardedAdUnitId = ...
  • MobileAds.appOpenAdUnitId = ...
  • MobileAds.rewardedInterstitialAdUnitId = ...

You can also set a custom id in the constructor of every ad, and in the load method of many!

You can find a complete example here

Always test with test ads

When building and testing your apps, make sure you use test ads rather than live, production ads. Failure to do so can lead to suspension of your account. We'll tell you if you're using a production ad with the following message:

It is highly recommended to use test ads in for testing instead of production ads. Failure to do so can lead in to the suspension of your account

Test Ids for Android and iOS are different. You can find the list for each here:

Test Ids:

They've been specially configured to return test ads for every request, and you're free to use it in your own apps while coding, testing, and debugging. Just make sure you replace it with your own ad unit ID before publishing your app.

For more information about how the Mobile Ads SDK's test ads work, see Test Ads.

Enable test devices

If you want to do more rigorous testing with production-looking ads, you can now configure your device as a test device and use your own ad unit IDs that you've created in the AdMob UI. Test devices can either be added in the AdMob UI or programmatically using the Google Mobile Ads SDK.

Add your test device in the AdMob UI

For a simple, non-programmatic way to add a test device and test new or existing app builds, use the AdMob UI. Learn how.

Key Point: New test devices typically start serving test ads in your app within 15 minutes, but it can also take up to 24 hours.

Add your test device programmatically

If you want to test ads in your app as you're developing, follow the steps below to programmatically register your test device.

  1. Load your ads-integrated app and make an ad request.
  2. Check the logcat output for a message that looks like the one below, which shows you your device ID and how to add it as a test device:
    • Android:

    I/Ads: Use RequestConfiguration.Builder.setTestDeviceIds(Arrays.asList("33BE2250B43518CCDA7DE426D04EE231")) to get test ads on this device."

    • iOS:

    To get test ads on this device, set: GADMobileAds.sharedInstance.requestConfiguration.testDeviceIdentifiers = @[ @"2077ef9a63d2b398840261c8221a0c9b" ]; Copy your test device ID to your clipboard. (In the example above, the device ID is, in Android, 33BE2250B43518CCDA7DE426D04EE231, and in iOS, 2077ef9a63d2b398840261c8221a0c9b)

  3. Call MobileAds.setTestDeviceIds(['33BE2250B43518CCDA7DE426D04EE231']) for android and MobileAds.setTestDeviceIds(['2077ef9a63d2b398840261c8221a0c9b']) for iOS.
    NOTE: The ids mentioned are just examples, you should put the id that your console shows.
    ⭐: Be sure to remove the code that sets these test device IDs before you release your app.
  4. On android, you can optionally check MobileAds.isTestDevice() to confirm that your device was properly added as a test device.
  5. Hot restart your app. If the ad is a Google ad, you'll see a Test Ad label centered at the top of the ad (banner, interstitial, or rewarded video). For native advanced ads, the headline asset is prepended with the string 'Test mode':
    Android test ad iOS test ad Native test ad

Enabling hybrid composition for android

Once initialized, you can enable hybrid composition as following:

MobileAds.useHybridComposition = true;

Or you can enable it on initialization:

MobileAds.initialize(useHybridComposition: true);

It's enabled by default on Android 19 and on iOS (it's also enabled by default on Banner Ads. See this for more info). Note that on Android versions prior to Android 10 Hybrid Composition has some performance drawbacks.

You can enable or disable it individually in the constructor of both Banner and Native Ads:

NativeAd(
  useHybridComposition: false,
  ...
)

Note: It autommatically does the checking for you about the android version, so you don't need to worry about it.

Request App Tracking Transparency Authorization for iOS

To display the App Tracking Transparency authorization request for accessing the IDFA, update your Info.plist to add the NSUserTrackingUsageDescription key with a custom message describing your usage. Here is an example description text:

<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>

The usage description appears in the App Tracking Transparency dialog box:

To present the authorization request, call MobileAds.requestTrackingAuthorization(). We recommend waiting for the completion callback prior to loading ads so that if the user grants the App Tracking Transparency permission, the Google Mobile Ads SDK can use the IDFA in ad requests:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await MobileAds.initialize();
  final status = await MobileAds.requestTrackingAuthorization();

  runApp(MyApp());
}

KEY POINT: For a better user experience, we recommend adding an explainer preceding the call to requestTrackingAuthorization: to clarify the permission and data usage to users.

This has no effect on Android!

Possible status values

  1. TrackingAuthorizationStatus.notDetermined: The value returned if a user has not yet received a request to authorize access to app-related data that can be used for tracking the user or the device.
  2. TrackingAuthorizationStatus.restricted: The value returned if authorization to access app-related data that can be used for tracking the user or the device is restricted.
  3. TrackingAuthorizationStatus.denied: The value returned if the user denies authorization to access app-related data that can be used for tracking the user or the device.
  4. TrackingAuthorizationStatus.authorized: The value returned if the user authorizes access to app-related data that can be used for tracking the user or the device.

Native

Banner

Interstitial

Rewarded

App open

Rewarded Interstitial

Clone this wiki locally