Skip to content

Getting started

Android app requirements:

  • minSdkVersion: 21 or higher

  • compileSdkVersion: 34 or higher

  • Android Gradle Plugin: 4.1.* or higher

Add XMediator to your Android project

X3M's Maven repository

In the project level gradle configuration file, include X3M's Maven repository:

allprojects {
    buildscript {
        // [...]
    }

    repositories {
        // [...]

        maven { url "https://android-artifact-registry.x3mads.com/maven" }
    }
}

allprojects {
    buildscript {
        // [...]
    }

    repositories {
        // [...]

        maven {
            url = URI("https://android-artifact-registry.x3mads.com/maven")
        }
    }
}

Token based repository deprecation notice

If you are using the deprecated https://YOUR_MAVEN_TOKEN.artifact-registry.x3mads.com/maven along with the deprecated package domains com.etermax.android.xmediator*, please migrate to the new repository and package domain:

  • https://YOUR_MAVEN_TOKEN.artifact-registry.x3mads.com/maven to https://android-artifact-registry.x3mads.com/maven
  • com.etermax.android.xmediator to com.x3mads.android.xmediator

We'll continue supporting the old repository in the short term, to maintain compatibility with already integrated projects. Please consider migrating as soon as posible to avoid running into issues in the future.

XMediator Core dependency

In the app-level gradle configuration file, add the following dependency:

dependencies {
    implementation 'com.x3mads.android.xmediator:core:1.80.1'
}

dependencies {
    implementation("com.x3mads.android.xmediator:core:1.80.1")
}

Add your Google Ads App Id to the Android Manifest

XMediator utilizes Google Ads services to obtain the GAID (Google Advertising ID) required by some mediation networks to serve ads.

In your app's manifest add the following metadata with your own Google Ads App ID:

<?xml version="1.0" encoding="utf-8"?>
<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>

Mediation adapters

To integrate additional mediation network adapters, add the corresponding dependency in the app level gradle file. You may also need to add additional maven repositories dependending on the network.

For instance, here is how to add the Google Ads mediation adapter for XMediator:

dependencies {
    implementation 'com.x3mads.android.xmediator.mediation:google-ads:22.2.0.6'
}

dependencies {
    implementation("com.x3mads.android.xmediator.mediation:google-ads:22.2.0.6")
}

You can find the dependencies required for each network in the changelogs of the adapters. For a complete list of supported ad partners please refer to Supported ad networks.

Choose networks

Pick networks to generate a code snippet for your build.gradle file:

Initialize the SDK

Before requesting any ad, make sure to call XMediatorAds.startWith(). This method configures your application Key, and fetches the required configuration parameters for the ad placements in your app, among other things.

Additionally, you may want to wait for the initialization callback to complete. This will ensure that your placement' requests have the necessary prebid configurations.

XMediatorAds.startWith(
    activity = activity,
    appKey = "<your-app-key>",
    initSettings = InitSettings(
        userProperties = UserProperties(
            userId = "<your-user-id>",
        ),
    ),
    initCallback = {
        Log.d("X3M", "Initialization complete!")
    },
)

XMediatorAds.startWith(
    activity,
    "<your-app-key>",
    new InitSettings.Builder()
            .setUserProperties(new UserProperties("<your-user-id>", new CustomProperties.Builder().build()))
            .build(),
    initResult -> {
        Log.d("X3M", "Initialization complete!")
        return Unit.INSTANCE;
    }
);

You may also configure additional options using the InitSettings instance in the initialize method.

For a complete list of available options please see InitSettings Class

Warning

To ensure the SDK is correctly configured before ad mediation begins, any method that performs an ad request will raise an exception if they are called before XMediatorAds.startWith() is invoked.

It is mandatory to wait for the init callback to complete before making any ad request.