(EN) Android Getting Started - adxcorp/ADXLibrary_Integration GitHub Wiki

Getting started with ADXLibrary

In order to get started, please send a registration request to [email protected]

0. Latest ADXLibrary

Version : 1.17.0

Release Date : 2021/06/28

1. Build with Gradle

build.gradle

repositories {
    // ... other project repositories
    jcenter()
    maven { url 'https://jitpack.io' }
    maven { url 'https://maven.google.com' }
}

// ...
dependencies {
    // the entire library (Please notify us at [email protected] before using this option)
    compile 'com.github.adxcorp.ADXLibrary_Android:adx-library:1.17.0'

    // when using only native ads
    compile 'com.github.adxcorp.ADXLibrary_Android:adx-library-native:1.17.0'

    // when using only interstitial/banner ads
    compile 'com.github.adxcorp.ADXLibrary_Android:adx-library-standard:1.17.0'

    // when using only rewarded video ads
    compile 'com.github.adxcorp.ADXLibrary_Android:adx-library-rewarded-video:1.17.0'

    // for example, include the following dependencies if you are using interstitial/banner/native ads 
    compile 'com.github.adxcorp.ADXLibrary_Android:adx-library-standard:1.17.0'
    compile 'com.github.adxcorp.ADXLibrary_Android:adx-library-native:1.17.0'

    // ADXLibrary currently uses Google Play Service Ads v20.1.0
    //compile 'com.google.android.gms:play-services-ads:20.1.0'
}

android {
    compileOptions {
       sourceCompatibility 1.8
       targetCompatibility 1.8
    }
}

2. Initialization

Before you call any ad-related methods, you need to go through the following initialization using one of Ad Unit IDs you have received from us. Please note that you need to initialize only once. You may proceed to call ad-related methods after onResult method has been called.

If you are not serving traffic from EU, you can call initWithSaveGDPRState to manually set GDPR consent state to ADXConsentStateNotRequired. When calling initWithShowAdxConsent, set isDebug to true to expose EU-only GDPR consent form.

For more information, please refer to GDPR Guide.

- When initWithShowAdxConsent is called, ADXLibrary checks whether the user is within EU and has already given GDPR consent. It then exposes GDPR consent UI form if necessary.

ADXGDPR.initWithShowAdxConsent(activity, "<YOUR AD Unit ID>", isDebug, new ADXGDPR.ADXConsentListener() {
        @Override
        public void onResult(ADXGDPR.ADXConsentState adxConsentState) {
                
        }
});

- To manually set GDPR consent state

ADXGDPR.initWithSaveGDPRState(activity, "<YOUR AD Unit ID>", adxConsentState, new ADXGDPR.ADXConsentListener() {
        @Override
        public void onResult(ADXGDPR.ADXConsentState adxConsentState) {

        }
});

- If you are calling initialization method and Native Ads methods in the same activity

You need to call both NativeAdFactory.init() and NativeAdFactory.setViewBinder() before you call initialization methods(initWithShowAdxConsent, initWithSaveGDPRState). Then you need to call NativeAdFactory.preloadAd() from within ADXConsentListener.onResult as follows:

NativeAdFactory.init(context);
NativeAdFactory.setViewBinder(DefineAdUnitId.NATIVE_AD_UNIT_ID, new ViewBinder.Builder(R.layout.layout_native_ad)
                .mainImageId(R.id.mainImageId)
                .iconImageId(R.id.iconImageId)
                .titleId(R.id.titleId)
                .privacyInformationIconImageId(R.id.privacyInformationIconImageId)
                .callToActionId(R.id.callToActionId)
                .addExtra("ad_choices_container", R.id.ad_choices_container)
                .build());

ADXGDPR.initWithShowAdxConsent(this, DefineAdUnitId.BANNER_AD_UNIT_ID, true, new ADXGDPR.ADXConsentListener() {
        @Override
        public void onResult(ADXGDPR.ADXConsentState adxConsentState) {
                NativeAdFactory.preloadAd(DefineAdUnitId.NATIVE_AD_UNIT_ID);
        }

});

3. Using Rewarded Video Ads

When serving Rewarded Video Ads, you must use either MoPub or AdMob mediation but do not use both. If both mediations are used for serving Rewarded Video Ads, callback method may not get called.

4. Add test device

When serving AdMob Rewarded Video Ads, you must register your test device. Testing without registering your test device may lead to your account being banned. Follow the following instructions:

When you run your application and load Rewarded Video Ads using AdMob, you will see the following log:

 <Google> To get test ads on this device, call:
 request.testDevices = @[ "2077ef9a63d2b398840261c8221a0c9b" ];

Copy the Device ID and register it as test device.

AdRequest request = new AdRequest.Builder()
    .addTestDevice("2077ef9a63d2b398840261c8221a0c9b")
    .build();

* GDPR Guide

  • To comply with GDPR, ADXGDPR class provides the following methods:
// initializes ADXLibrary and checks whether the user is within EU and has already given GDPR consent. It then exposes GDPR consent form if necessary and updates consent state.
public static void initWithShowAdxConsent(final Activity activity, String mopubAdUnitId, final boolean isDebug, final ADXConsentListener gdprListener)

// initializes ADXLibrary and manually sets GDPR consent state without exposing GDPR consent form.
public static void initWithSaveGDPRState(final Context context, final String mopubAdUnitId, final ADXConsentState consentState, final ADXConsentListener gdprListener)

// gets user's GDPR consent state stored in ADXGDPR
public static int getResultGDPR(Context context)

// manually change GDPR consent state
public static void saveResultGDPR(Context context, ADXGDPR.ADXConsentState consentState)

// gets AD(x) Privacy Policy URL
public static String getPrivacyURL()
  • ADXConsentState can be one of the following four values:
// user consent is unknown. Initialization method hasn't been called.
ADXConsentStateUnknown
// user is not within EU and GDPR consent is not required. Personalized ads will be served.
ADXConsentStateNotRequired
// user has not consented to use of personal information. Personalized ads will not be served.
ADXConsentStateDenied
// user has consented to use of personal information. Personalized ads will be served.
ADXConsentStateConfirm
  • When running application, you need to either call initWithShowAdxConsent or initWithSaveGDPRState.
  • If you are not getting traffic from EU, you can call initWithSaveGDPRState to manually set consent state to ADXConsentStateNotRequired.
  • When calling initWithShowAdxConsent, set isDebug to true to expose EU-only GDPR consent form.
  • Ad-related methods can be called only after ADXConsentListener.onResult has been called.
  • If you are calling initialization method and NativeAdFactory.init() and setViewBinder() in the same activity, make sure to call NativeAdFactory.init() and setViewBinder() before the initialization method.
  • You can use any one of Ad Unit IDs you have received from us when calling initialize method.
  • When using AdMob Rewarded Video Ads, you need to add extra data to AdRequest as follows:
Bundle extras = new Bundle();
if (ADXGDPR.ADXConsentState.values()[ADXGDPR.getResultGDPR(this)] == ADXGDPR.ADXConsentState.ADXConsentStateDenied) {
        extras.putString("npa", "1");
}

AdRequest request =  new AdRequest.Builder()
                .addNetworkExtrasBundle(AdMobAdapter.class, extras)
                .build();
⚠️ **GitHub.com Fallback** ⚠️