Initialize the SDK

This page covers the instructions to initialize the Next Gen Mobile Ads SDK.

Before you begin

To use the Next Gen Mobile Ads SDK, you must either integrate without mediation or use Ad Manager as the mediation platform. The other mediation platforms are not compatible with the Next Gen Mobile Ads SDK.

Configure your build for the Next Gen Mobile Ads SDK

The following sections show you the necessary steps to configure the Next Gen Mobile Ads SDK.

Include the Next Gen Mobile Ads SDK dependency

The Next Gen Mobile Ads SDK requires a different Gradle dependency. In your app-level build file, remove the reference to the current Mobile Ads SDK dependency and include the new artifact.

Gradle dependencies
Current

Kotlin

dependencies {
  // ...
  implementation("com.google.android.gms:play-services-ads:24.4.0")
}

Groovy

dependencies {
  // ...
  implementation 'com.google.android.gms:play-services-ads:24.4.0'
}
Next Gen

Kotlin

dependencies {
  // ...
  // Comment out/remove play-services-ads.
  // implementation("com.google.android.gms:play-services-ads:24.4.0")
  implementation("com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk:0.17.0-alpha01")
}

Groovy

dependencies {
  // ...
  // Comment out/remove play-services-ads.
  // implementation 'com.google.android.gms:play-services-ads:24.4.0'
  implementation 'com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk:0.17.0-alpha01'
}

Exclude com.google.android.gms modules in mediation integrations

Mediation adapters continue to depend on the current Mobile Ads SDK. However, the Next Gen Mobile Ads SDK includes all classes required by mediation adapters. To avoid compile errors related to duplicate symbols, you need to exclude the current Mobile Ads SDK from being pulled in as a dependency by mediation adapters.

In your app-level build file, exclude both play-services-ads and play-services-ads-lite modules globally from all dependencies.

Kotlin

configurations.all {
    exclude(group = "com.google.android.gms", module = "play-services-ads")
    exclude(group = "com.google.android.gms", module = "play-services-ads-lite")
}

Groovy

configurations {
  all {
    exclude(group = "com.google.android.gms", module = "play-services-ads")
    exclude(group = "com.google.android.gms", module = "play-services-ads-lite")
  }
}

Set the minimum and compile Android API levels

The Next Gen Mobile Ads SDK requires a minimum Android API level of 24 and a compile Android API level of 34. Adjust the minSdk and compileSdk values in your app-level build file to 24 or higher and 34 or higher, respectively.

Initialize the Next Gen SDK

The Next Gen Mobile Ads SDK requires initialization before loading ads, a change from the current Mobile Ads SDK where initialization is optional but recommended. Update your code if you weren't previously initializing the SDK before loading ads.

This section covers the differences in SDK initialization implementation between the current and Next Gen Mobile Ads SDKs.

Set the Ad Manager app ID

The following examples set the Ad Manager app ID in the current and Next Gen Mobile Ads SDKs:

Current

Integration requires a <meta-data> tag with android:name="com.google.android.gms.ads.APPLICATION_ID" containing your Ad Manager app ID within your app's AndroidManifest.xml file.

<manifest>
  <application>
    <!-- Sample Ad Manager app ID: ca-app-pub-3940256099942544~3347511713 -->
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="SAMPLE_APP_ID"/>
  </application>
</manifest>
Next Gen

Provide your Ad Manager app ID programmatically as part of SDK initialization.

Kotlin

// Initialize the Google Mobile Ads SDK.
val initConfig = InitializationConfig.Builder("SAMPLE_APP_ID").build()
MobileAds.initialize(this@MainActivity, initConfig) {}

Java

// Initialize the Google Mobile Ads SDK.
InitializationConfig initConfig =
    new InitializationConfig.Builder("SAMPLE_APP_ID").build();
MobileAds.initialize(this, initConfig, initializationStatus -> {});

Review implementation changes

The following examples initialize the current and Next Gen Mobile Ads SDKs:

Current

Call MobileAds.initialize() to initialize the Google Mobile Ads SDK. Initialization on a background thread is recommended to reduce ANRs.

Kotlin

import com.google.android.gms.ads.MobileAds
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

class MainActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    val backgroundScope = CoroutineScope(Dispatchers.IO)
    backgroundScope.launch {
      // Initialize the Google Mobile Ads SDK on a background thread.
      MobileAds.initialize(this@MainActivity) {}
    }
  }
}

Java

import com.google.android.gms.ads.MobileAds;
import com.google.android.gms.ads.initialization.InitializationStatus;
import com.google.android.gms.ads.initialization.OnInitializationCompleteListener;

public class MainActivity extends AppCompatActivity {
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    new Thread(
            () -> {
              // Initialize the Google Mobile Ads SDK on a background thread.
              MobileAds.initialize(this, initializationStatus -> {});
            })
        .start();
  }
}
Next Gen

Call MobileAds.initialize() to initialize the Google Mobile Ads SDK. This must be called on a background thread, failure to do so may cause an "Application Not Responding" (ANR) error.

Kotlin

import com.google.android.libraries.ads.mobile.sdk.MobileAds
import com.google.android.libraries.ads.mobile.sdk.initialization.InitializationConfig
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

class MainActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    val backgroundScope = CoroutineScope(Dispatchers.IO)
    backgroundScope.launch {
      // Initialize the Google Mobile Ads SDK on a background thread.
      MobileAds.initialize(
        this@MainActivity,
        // Sample Ad Manager app ID: ca-app-pub-3940256099942544~3347511713
        InitializationConfig.Builder("SAMPLE_APP_ID").build()
      ) {
        // Adapter initialization is complete.
      }
      // Other methods on MobileAds can now be called.
    }
  }
}

Java

import com.google.android.libraries.ads.mobile.sdk.MobileAds;
import com.google.android.libraries.ads.mobile.sdk.initialization.InitializationConfig;

public class MainActivity extends AppCompatActivity {
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    new Thread(
            () -> {
              // Initialize the Google Mobile Ads SDK on a background thread.
              MobileAds.initialize(
                  this,
                  // Sample Ad Manager app ID: ca-app-pub-3940256099942544~3347511713
                  new InitializationConfig.Builder("SAMPLE_APP_ID")
                      .build(),
                  initializationStatus -> {
                    // Adapter initialization is complete.
                  });
              // Other methods on MobileAds can now be called.
            })
        .start();
  }
}
Next
Handle callbacks from background thread