Installing and configuring the SDK

Integration Guide.

Release version 1.7.0 | Release date 03/20/2025

Minimum requirements:

• Use the Android API level 22 (Android OS 5.1) and above.

Demo application

Use our demo application as an example.

GitHub - MadexTech/madex-android-demoGitHub

Installation

General description of the installation process

To install the Android SDK, you will need:

• Check out the demo application

• Add settings.gradle to your project

• Complete the build.gradle of your project

• Synchronize the gradle of the project

• Check the installation correctness by initializing the SDK with debug mode enabled

Prepare the Gradle

Android 11 has changed the way it requests applications and interacts with other applications installed by the user on the device. For this reason, make sure that you are using a version of Cradle that matches one of the ones listed here.

1. Complete the settings.gradle file with the repository necessary for installing the SDK. The full list of repositories will be provided to you by the Madex account manager. Check out your version of Android Studio, and paste the appropriate code intosettings.gradle at the root of the project. An example of connecting a repository in settings.gradle.

Starting from Arctic Fox and above

// project-level settings.gradle

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        // ... other project repositories
        
        // connecting the Madex SDK repository
        maven { url  "https://sdkpkg.sspnet.tech" }
        
        // connecting the SDK repository of the IronSource advertising network
        maven { url "https://android-sdk.is.com" }
        
        // connecting the SDK repository of the Mintegral advertising network
        maven { url  "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea" }
    }
}

For the version before Arctic Fox

// project-level settings.gradle

allprojects {
    repositories {
        // ... other project repositories
        
        // connecting the Madex SDK repository
        maven { url  "https://sdkpkg.sspnet.tech" }
        
        // connecting the SDK repository of the IronSource advertising network
        maven { url "https://android-sdk.is.com" }
        
        // connecting the SDK repository of the Mintegral advertising network
        maven { url  "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea" }
    }
}

1. Complete the build.gradle with the necessary build parameters for the correct installation of the SDK.

// app-level build.gradle

android {
  // ... other settings
     
   defaultConfig {
     // ... other settings
       
     multiDexEnabled true // Enable multidex
   }
 
   compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
   }
}

1. In the same file, add dependencies to install all the necessary adapters. The full list of dependencies with the current version numbers of libraries and adapters will be provided to you by the Madex account manager. Example of dependencies for Madex, Applovin, Yandex, IronSource and Mintegral networks

dependencies {
    // ... other dependencies
    
    // connection of Madex SDK dependency
    implementation 'sspnet.tech:madex:1.7.0'
    
    // connection of Applovin SDK advertising network dependency
    implementation 'sspnet.tech.adapters:applovin:1.4.0'
    implementation 'com.applovin:applovin-sdk:13.0.0'
    
    // connection of IronSource SDK advertising network dependency
    implementation 'sspnet.tech.adapters:ironsource:1.5.0'
    implementation 'com.ironsource.sdk:mediationsdk:8.3.0'
    
    // connection of Yandex SDK advertising network dependency
    implementation 'sspnet.tech.adapters:yandex:1.5.0'
    implementation 'com.yandex.android:mobileads:7.1.0'
    
    // connection of Mintegral SDK advertising network dependency
    implementation 'sspnet.tech.adapters:mintegral:1.5.0'
    implementation 'com.mbridge.msdk.oversea:reward:16.6.31'
    implementation 'com.mbridge.msdk.oversea:newinterstitial:16.6.31'
}

1. Save the file and click Gradle Sync.

Network Security Configuration

Android 9.0 (API 28) blocks http traffic (non-HTTPS) by default, which may prevent ads from displaying correctly. More information about this you can find here.

To allow the use of http traffic, you need to add the usesCleartextTraffic attribute to the AndroidManifest.xml file:

<application
    ...
    android:usesCleartextTraffic="true">
    ...
</application>

Code obfuscation

If code obfuscation is enabled in your application, then add the following text to the end of the file proguard-rules.pro:

-keep class sspnet.tech.**.* { *; }

OAID support

The SDK uses GAID, Google's advertising identifier, to analyze user activity.

If you want to distribute your application to Huawei devices without Google Mobile Services support, you need to enable OAID support in your application.

1. Check out your version of Android Studio, and paste the appropriate code intosettings.gradle at the root of the project.

Starting from Arctic Fox and above

// project-level settings.gradle

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        // ... other project repositories
        
        // connecting the Huawei repository
        maven { url 'https://developer.huawei.com/repo/' }
    }
}

For the version before Arctic Fox

// project-level settings.gradle

allprojects {
    repositories {
        // ... other project repositories
        
        // connecting the Huawei repository
        maven { url 'https://developer.huawei.com/repo/' }
    }
}

1. Complete the build.gradle with the necessary build parameters for the correct installation of the SDK.

// app-level build.gradle

dependencies {
    // ... other dependencies
    
   // connection of Huawei Mobile Services dependency
   implementation 'com.huawei.hms:ads-identifier:3.4.62.300'
}

Add the Applovin SDK key

If you are using an adapter for Applovin, then add the following <meta-data> element to your AndroidManifest.xml inside the <application> element:

<meta-data android:name="applovin.sdk.key"
           android:value="APPLOVIN_SDK_KEY"/>

You can copy your APPLOVIN_SDK_KEY in the "Keys" section of your Applovin personal account.

Installation check

To make sure that the SDK is installed correctly, you will need to enable debug mode and initialize the SDK.

Debug mode

In debug mode SDK logs errors and events. It is disabled by default.

Use the enableDebug method to enable debug mode.

Madex.enableDebug(true);

Initialization

Use the code below to initialize the SDK in your project.

You can copy your publisher_id in the "Settings" section of your Madex personal account.

Madex.initialize("publisher_id", new InitializationListener() {
   @Override
   public void onInitializeSuccess() {
      // Called when the SDK is installed correctly
   }

   @Override
    public void onInitializeFailed(AdException error) {
      // Called when an error occurred during SDK installation
      // Using AdException error, you can get detailed information about the error
    }
});

If the SDK is installed correctly, you will see the following message in the console.

SDK initialized(<Madex SDK version number>)

Done! The SDK is installed, you can proceed to setting up ads.

We recommend that you don't disable debug mode until you finish working with ads.

If the SDK is installed incorrectly

In case of errors, we recommend clearing the Gradle cache.

Clearing the Gradle cache in Android Studio on Mac OS

If this doesn't help, try installing the SDK in a clean project. If the SDK is installed correctly, try to debug errors in your project.

We also recommend to take a look at the installation and initialization in the demo application.

If you are unable to install the SDK correctly and the above steps didn't lead to successful initialization, please contact support.

Additional actions to increase revenue

Geolocation data collection

To make targeted ads work more effectively and increase revenue, you can collect in app data about a user's exact and/or approximate geolocation, and feed it into the Madex SDK.

Permission to access coarse location ACCESS_COARSE_LOCATION is already enabled in the SDK when you install it.

If you don't want to provide the user's coarse location:

1. Add the following code to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove" />

1. Update the app on Google Play. During the publishing process, make sure that there are no warnings in the Google Play Console about the availability of location permission without mentioning this in the application's privacy policy and/or without needing it use for app functions.

Other SDK settings

User Consent Screen

In order to comply with the requirements of the app store and the laws governing the collection, processing and use of user's personal data, it is required to obtain his consent to the above actions.

Usually, the user's consent is obtained on a special screen when the application is first launched — consent-screen.

The Madex SDK implements such a screen, you can add and configure it using the Content Manager library.

You can find out more about its installation and configuration in the corresponding section.

User Consent Screen