Mobile Ads SDK integration

System: YAN, Adfox

Integrating the Yandex Mobile Ads SDK into an app is the first step to ad impressions and revenue. Once the SDK is integrated, you can choose an ad format to be used for your app monetization, such as banner ads or rewarded ads, and perform its setup.

Prerequisites

To prepare your app, follow the steps described in the next sections.

App requirements

• Use Android Studio 2021 or higher.
• Use Android Gradle Plugin 7.3.1 or higher.
• Check that your app's build file uses the following values:
  • MinSdkVersion 21 or higher.
  • CompileSdkVersion 31 or higher.
• If you are using the AppMetrica SDK in your application, make sure you have installed the 6th major version (6.x.x).

Set up the app in your Yandex Advertising Network account

Here's how to register your app in the Yandex Advertising Network:

1. Log in or register your account in the Yandex Advertising Network.
2. Register your app in the Yandex Advertising Network.

Set up your app

1. Add support for the Google and central Maven repositories to the project configuration.

   Depending on the project build settings, these repositories can be added either to the project's build.gradle file or to the repositories section of the settings.gradle file as shown below:

   build.gradle

   settings.gradle

   // Project-level build.gradle file
   buildscript {
       repositories {
           google()
           mavenCentral()
       }
   }
   
   allprojects {
       repositories {
           google()
           mavenCentral()
       }
   }
   

   // Project-level settings.gradle file
   pluginManagement {
       repositories {
           google()
           mavenCentral()
           gradlePluginPortal()
       }
   }
   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
       }
   }
   

2. Add a dependency on the Yandex Mobile Ads SDK to a Gradle file at your app's module level, usually app/build.gradle:

   dependencies {
     implementation 'com.yandex.android:mobileads:7.7.0'
   }
   

3. Set up permission to use an advertising ID (for apps using SDK versions older than 4.5.0).

   How to set up permission to use the ad ID

   The ad ID is a unique identifier provided by Google Play services for displaying ads to users who opt in to personalized ads. Users can opt out of ad personalization or reset their ID in the settings. In this case, advertising networks won't be able to use the ID to select relevant ads for the user.

   If your app runs a Yandex Mobile Ads SDK version below 4.5, add com.google.android.gms.permission.AD_ID to the AndroidManifest.xml file:

   <manifest>
       <application>
       <!-- For apps targeting Android 13 or higher & Yandex Mobile Ads SDK versions lower than 4.5.0 -->
           <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
       </application>
   </manifest>
   

   As of version 4.5.0, the Yandex Mobile Ads SDK adds com.google.android.gms.permission.AD_ID by default. Because of this, you don't have to specify it in the application's main manifest. The permission allows you to use an ad ID to select more relevant ads from advertising networks.

   You can delete the permission if necessary. For example, if a policy does not allow the use of an ID for ad selection, such as the Families Policy.

   To keep the permission from being added to the application's main manifest, add the following code to AndroidManifest.xml:

   <manifest>
       <application>
           <uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove"/>
       </application>
   </manifest>
   

   Warning

   Lack of permission and access to the ID may impact your revenue, because your app may serve less relevant ads.

Initialize the Yandex Mobile Ads SDK

Successful integration of the Yandex Mobile Ads SDK is an important prerequisite for a correct library integration. By default, the SDK is initialized automatically when you run your app. This speeds up ad loading and, hence, increases your app monetization revenue.

If you need to set up privacy policies for personal data on your app, make sure to do this before initializing the Yandex Mobile Ads SDK.

You can set up these policies using the AndroidManifest.file or directly before you initialize the SDK manually.

<manifest>
    <application>
        <!-- Disable the use of child's personal data for app monetization.  -->
        <meta-data
          android:name="@string/yandex_mobileads_age_restricted_user"
          android:value="true" />
    </application>
</manifest>

Manual SDK initialization

If necessary, you can initialize the library on your own using the initialize() method after disabling auto initialization:

<manifest>
    <application>
        <!-- Disable automatic sdk initialization.  -->
        <meta-data
            android:name="com.yandex.mobile.ads.AUTOMATIC_SDK_INITIALIZATION"
            android:value="false" />
    </application>
</manifest>

We recommend adding the initialization code to the onCreate method of the Application class. Make sure to set up the privacy policies for personal data before you initialize the SDK:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // Configure the user data privacy policy before sdk init
        MobileAds.initialize(this) {
            // Now you can use ads
        }
    }
}

public class MyApplication extends Application {
    @Override
    public void onCreate() {
       super.onCreate();
        // Configure the user data privacy policy before sdk init
        MobileAds.initialize(this, () -> {
            // Now you can use ads
        });
    }
}

Testing SDK integration

You can see if your library is successfully integrated using the built-in SDK integration testing tool.

To test your SDK integration, rebuild the project after adding the dependency and initializing the SDK.

Launch Logcat and search for the "Yandex Ads" keyword.

That command will generate a log with information about the SDK integration status. If the integration is successful, you'll get a notification. If an error occurred during integration, the logs will contain a detailed message about what caused it and how to fix it.

mobileads$ adb logcat | grep 'Yandex Ads' -i
[Yandex Ads]  I  Yandex Mobile Ads 7.7.0 integrated successfully
[Yandex Ads]  I  Yandex Mobile Ads 7.7.0 initialized successfully

Indicator of an outdated library version

The indicator of an outdated version of the Yandex Mobile Ads SDK is displayed as a toast when initializing the library or loading ads.

Issue details are also logged to the app logs.

Sample logs:

***************************************************************************************
* The integrated version of the Yandex Mobile Ads SDK is outdated.                    *
* Please update com.yandex.android:mobileads to the latest version.                   *
* Learn more about the latest version of the SDK here:                                *
* https://yandex.ru/dev/mobile-ads/doc/android/quick-start/android-ads-component.html *
* Changelog: https://yandex.ru/dev/mobile-ads/doc/intro/changelog-android.html        *
***************************************************************************************

To disable the indicator's display, call the enableDebugErrorIndicator method set to false:

MobileAds.enableDebugErrorIndicator(false)

Lint check for the latest SDK version

A Lint check for the latest SDK version is run when building the app's release version.

Lint checks are performed by calling the lintVitalRelease gradle task. The task crashes if the ad SDK version is outdated.

The check prevents building an app if a newer SDK version has been released.

To disable the latest SDK version check, use the standard gradle code for disabling Lint checks (for more information, see the Android documentation).

android {
    lintOptions {
        disable 'MobileAdsSdkOutdatedVersion'
    }
}

Next steps

Once you have successfully integrated the Yandex Mobile Ads SDK, you can proceed to implementing your ad formats.

Choose one of the following types of ads that best suits your app: