AdGain SDK 接入指南

SDK 初始化说明

3. 添加依赖

3.1 本地依赖

dependencies {
    implementation(name: 'adgain-sdk-xxx-release', ext: 'aar')
}

3.2 远程依赖

maven {
    url "http://nexus.datads.cn/repository/maven-releases"
    allowInsecureProtocol = true
    credentials {
        username = "maven-reader"
        password = "maven-reader"
    }
}

dependencies {
    implementation 'com.adgain:adgain-sdk:xxx'
}

4. SDK 初始化配置

        // 个性化广告开关设置
        AdGainSdk.getInstance().setPersonalizedAdvertisingOn(true);
        
        Map<String, Object> customData = new HashMap<>();
        customData.put("custom_key", "custom_value");

        AdGainSdk.getInstance().init(this, new AdGainSdkConfig.Builder()
                .appId("")       //必填，向广推商务获取
                .userId("")      // 用户ID，有就填
                .showLog(false)   // 是否展示adsdk内部日志，正式环境务必为false
                .addCustomData(customData)  //自定义数据
                .customController(new CustomController() {
                    // 是否允许SDK获取位置信息
                    @Override
                    public boolean canReadLocation() {
                        return true;
                    }

                    // 是否允许SDK获取手机信息
                    @Override
                    public boolean canUsePhoneState() {
                        return true;
                    }
                    
                    // 是否允许SDK使用AndoridId
                    @Override
                    public boolean canUseAndroidId() {
                        return true;
                    }
                    // 是否允许SDK获取Wifi状态
                    @Override
                    public boolean canUseWifiState() {
                        return true;
                    }
                    // 为SDK提供oaid
                    @Override
                    public String getOaid() {
                        return "";
                    }
                })
                .setInitCallback(new InitCallback() {
                    // 初始化成功回调，初始化成功后才可以加载广告
                    @Override
                    public void onSuccess() {
                        Log.d(Constants.LOG_TAG, "init--------------onSuccess-----------");
                    }

                    // 初始化失败回调
                    @Override
                    public void onFail(int code, String msg) {
                        Log.d(Constants.LOG_TAG, "init--------------onFail-----------" + code + ":" + msg);
                    }
                }).build());

初始化相关类说明

1. AdGainSdkConfig

com.adgain.sdk.api.AdGainSdkConfig.Builder

2. CustomController

com.adgain.sdk.api.CustomController

3. InitCallback

com.adgain.sdk.api.InitCallback

4. 个性化广告设置（可选）

AdGainSdk.getInstance().setPersonalizedAdvertisingOn(boolean personal);

5. 在 AndroidManifest.xml 文件中添加如下权限

<!-- 必要权限 -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- 可选权限：获取当前网络类型及状态 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- 可选权限：仅用于获取 IMEI 或运营商信息 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<!-- 可选权限：拉新下载类广告需要 -->
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

开屏广告

适用于 App 启动、冷热启动等高曝光入口。参考 Demo，接入代码示例可参考 Demo 中的 SplashDemoActivity 实现。

1. 接入代码示例

可参考 Demo 中的 SplashDemoActivity 实现。

1.1 设置监听回调

private final SplashAdListener mSplashAdListener = new SplashAdListener() {

        @Override
        public void onAdLoadSuccess() {
            Log.d(Constants.LOG_TAG, "--LoadSuc:" + splashAd.isReady() + " " + splashAd.getBidPrice());
        }

        @Override
        public void onAdCacheSuccess() {
            Log.d(Constants.LOG_TAG, "----------onAdCacheSuccess-----" + splashAd.isReady());
            // 展示前先判断广告是否ready
            if (splashAd != null && splashAd.isReady()) {
                // 执行展示广告
                splashAd.showAd(getSplashContainer());
            }
        }

        // 广告加载失败
        @Override
        public void onSplashAdLoadFail(AdError error) {
            Log.d(Constants.LOG_TAG, "----------onSplashAdLoadFail----------" + error.toString());
            gotoMainActivity();
        }

        @Override
        public void onSplashAdShow() {
            Log.d(Constants.LOG_TAG, "----------onSplashAdShow----------");

        }

        // 广告展示错误
        @Override
        public void onSplashAdShowError(AdError error) {
            Log.d(Constants.LOG_TAG, "-----onSplashAdShowError----------" + error.toString());
            gotoMainActivity();
        }

        // 广告被用户点击
        @Override
        public void onSplashAdClick() {
            Log.d(Constants.LOG_TAG, "----onSplashAdClick----------");
        }

        // 广告关闭
        @Override
        public void onSplashAdClose(boolean isSkip) {
            Log.d(Constants.LOG_TAG, "----------onSplashAdClose---------" + isSkip);
            if (isForeground) {
                gotoMainActivity();
            } else {
                // 不在前台，说明打开了广告中的链接，等回到 onResume 时再跳转
                getLifecycle().addObserver(new LifecycleEventObserver() {
                    @Override
                    public void onStateChanged(LifecycleOwner source,Lifecycle.Event event) {
                        if (Lifecycle.Event.ON_RESUME == event) {
                            getLifecycle().removeObserver(this);
                            gotoMainActivity();
                        }
                    }
                });
            }
        }
    };

1.2 开屏广告点击注意事项

/**
* 当设置开屏可点击时，需要等待跳转页面关闭后，再切换至您的主窗口。
* 此时需要增加 isForeground 判断当前 Activity 是否在前台。
* 如果在前台，需要跳转时可以直接跳转，否则等到 回到前台时再跳转。
*/
private boolean isForeground = false;

@Override
protected void onPause() {
    super.onPause();
    isForeground = false;
}

@Override
protected void onResume() {
    super.onResume();
    isForeground = true;
}

/**
 * 跳转到主 Activity
 */
private void gotoMainActivity() {
    Intent intent = new Intent(this, MainActivity.class);
    startActivity(intent);
    this.finish();
}

// 开屏广告关闭通知
@Override
public void onSplashAdClose() {
    if (isForeground) {
        gotoMainActivity();
    } else {
        // 不在前台，说明打开了广告中的链接，等回到 onResume 时再跳转
        getLifecycle().addObserver(new LifecycleEventObserver() {
            @Override
            public void onStateChanged(@NonNull LifecycleOwner source, @NonNull Lifecycle.Event event) {
                if (Lifecycle.Event.ON_RESUME == event) {
                    getLifecycle().removeObserver(this);
                    gotoMainActivity();
                }
            }
        });
    }
}

1.3 开屏广告加载

// 创建ad请求
AdRequest adRequest = new AdRequest.Builder()
        .setCodeId(Constants.SPLASH_ADCOID) // 广告位ID
        .setWidth(UIUtil.getScreenWidthInPx(this)) // 设置需要的广告视图宽度
        .setHeight(getSplashHeight()) // 设置需要的广告视图高度
        .setExtOption(new HashMap()) // 设置透传的自定义数据
        .build();
// 创建开屏AD API对象，监听回调在这里设置,5 * 1000为请求广告超时时间
splashAd = new SplashAd(adRequest, mSplashAdListener, 5 * 1000);
// 加载广告
splashAd.loadAd();

1.4 开屏广告展示

// 展示前先判断广告是否ready
if (splashAd != null && splashAd.isReady()) {
    splashAd.showAd(splashLY);
} else {
   Log.d("TAG", "splashAd is not ready or splashAd is null");
}

1.5 开屏广告销毁

// 界面销毁时，执行销毁Ad接口
if (splashAd != null) {
    splashAd.destroyAd();
    splashAd = null;
}

2. 开屏 API 介绍

2.1 SplashAd

com.adgain.sdk.api.SplashAd

2.2 AdRequest

com.adgain.sdk.api.AdRequest.Builder

2.3 SplashAdListener

com.adgain.sdk.api.SplashAdListener

插屏广告

适用于内容切换、任务完成、页面转场等自然中断场景。参考 Demo 完成加载、展示、销毁和回调监听。

1. 插屏广告接入流程

参考 Demo。

1.1 插屏广告加载

        InterstitialAdListener listener = new InterstitialAdListener() {
            @Override
            public void onInterstitialAdLoadError(AdError error) {
                
            }

            @Override
            public void onInterstitialAdLoadSuccess() {

            }

            @Override
            public void onInterstitialAdLoadCached() {

            }

            @Override
            public void onInterstitialAdShow() {

            }

            @Override
            public void onInterstitialAdPlayEnd() {

            }

            @Override
            public void onInterstitialAdClick() {

            }

            @Override
            public void onInterstitialAdClosed() {

            }

            @Override
            public void onInterstitialAdShowError(AdError error) {

            }
        };
        
        Map<String, Object> options = new HashMap<>();
        options.put("inter_extra_test_key", "inter_extra_test_value");
        
        AdRequest adRequest = new AdRequest.Builder()
                .setCodeId(codeId)
                .setExtOption(options)
                .build();

        mInterstitialAd = new InterstitialAd(adRequest, listener);

        mInterstitialAd.loadAd();

1.2 插屏广告展示

if (interstitialAd != null && interstitialAd.isReady()) {
    interstitialAd.showAd( activity );
}

1.3 插屏广告销毁

if (interstitialAd != null) {
    interstitialAd.destroyAd();
    interstitialAd = null;
}

2. 插屏 API 介绍

2.1 InterstitialAd

com.adgain.sdk.api.InterstitialAd

2.2 AdRequest

com.adgain.sdk.api.AdRequest.Builder

2.3 InterstitialAdListener

com.adgain.sdk.api.InterstitialAdListener

激励视频广告

适用于用户主动观看广告以获取权益、奖励或增值内容的场景。参考 Demo 完成激励视频广告加载、展示、销毁和奖励回调处理。

1. 激励视频广告接入流程

参考 Demo。

1.1 激励视频广告加载

        Map<String, Object> options = new HashMap<>();

        AdRequest adRequest = new AdRequest.Builder()
                .setCodeId(codeID)
                .setExtOption(options)
                .build();

        mRewardAd = new RewardAd(adRequest, new RewardAdListener() {
            @Override
            public void onRewardAdLoadSuccess() {
                
            }

            @Override
            public void onRewardAdLoadCached() {

            }

            @Override
            public void onRewardAdShow() {

            }

            @Override
            public void onRewardAdPlayStart() {

            }

            @Override
            public void onRewardAdPlayEnd() {

            }

            @Override
            public void onRewardAdClick() {

            }

            @Override
            public void onRewardAdClosed() {

            }

            @Override
            public void onRewardAdLoadError(AdError error) {

            }

            @Override
            public void onRewardAdShowError(AdError error) {

            }

            @Override
            public void onRewardVerify() {

            }

            @Override
            public void onAdSkip() {

            }
        });

        mRewardAd.loadAd();

1.2 激励视频广告展示

if (rewardAd != null && rewardAd.isReady()) {
    rewardAd.showAd( activity );
}

1.3 激励视频广告销毁

if (rewardAd != null) {
    rewardAd.destroyAd();
    rewardAd = null;
}

2. 激励视频 API 介绍

2.1 RewardAd

com.adgain.sdk.api.RewardAd

2.2 AdRequest

com.adgain.sdk.api.AdRequest.Builder

2.3 RewardAdListener

com.adgain.sdk.api.RewardAdListener

原生广告（自渲染）

注意：原生广告具体实现可参考 Demo NativeAdSimpleDemoActivity、NativeAdListDemoActivity、NativeAdRecycleDemoActivity 等。自渲染广告由 SDK 返回物料，由开发者自行适配 UI。

1. 接入代码示例

1.1 原生广告加载

  Map<String, Object> options = new HashMap<>();
            options.put("test_extra_key", "test_extra_value");
            AdRequest adRequest = new AdRequest.Builder()
                    .setCodeId(codeId) // 设置广告位id
                    .setExtOption(options) // 自定义参数
                    .build();
            // 创建广告对象
            nativeAd = new NativeUnifiedAd(adRequest, new NativeAdLoadListener() {
                @Override
                public void onAdError( AdError error) {
                    Log.d(Constants.LOG_TAG, "----onAdError----------:" + error.toString());
                }

                @Override
                public void onAdLoad( List<NativeAdData> adDataList) {
                    if (adDataList != null && !adDataList.isEmpty()) {
                        currentAdDataList = adDataList;
                    }
                }
            });
        }
        // 请求广告
        nativeAd.loadAd();

1.2 原生广告展示

请参考 Demo 中 NativeAdUnifiedDemoActivity、NativeDemoRender 类的具体实现。

private ViewGroup adContainer;
private List<NativeAdData> currentAdDataList;

/**
 * 展示广告，请在收到onAdLoad回调后再展示广告
 */
List<NativeAdData> unifiedADDataList = currentAdDataList;
if (unifiedADDataList != null && !unifiedADDataList.isEmpty()) {
    NativeAdData nativeAdData = unifiedADDataList.get(0);
    View view = buildView(nativeAdData);
    // 媒体最终将要展示广告的容器
    if (adContainer != null) {
        adContainer.removeAllViews();
        adContainer.addView(view);
    }
} else {
    logMessage("Ad is not Ready");
    Log.d(Constants.LOG_TAG, "--------请先加载广告--------");
}
private View buildView(NativeAdData nativeAdData) {
    //媒体自渲染的View
    NativeDemoRender adRender = new NativeDemoRender(this);
    View view = adRender.renderAdView(nativeAdData, new NativeAdEventListener() {

        @Override
        public void onAdExposed() {
            Log.d(Constants.LOG_TAG, "----------onAdExposed----------");

        }

        @Override
        public void onAdClicked() {
            Log.d(Constants.LOG_TAG, "----------onAdClicked----------");

        }

        @Override
        public void onAdRenderFail(AdError error) {
            Log.d(Constants.LOG_TAG, "----------onAdRenderFail----------" + error.toString());

        }
    });

    return view;
}

1.3 原生广告销毁

// 原生广告对象的销毁
if (nativeAd != null) {
    nativeAd.destroyAd();
    nativeAd = null;
}

2. 原生 API 介绍

2.1 NativeUnifiedAd

com.adgain.sdk.api.NativeUnifiedAd

2.2 AdRequest

com.adgain.sdk.api.AdRequest.Builder

2.3 NativeAdLoadListener

com.adgain.sdk.api.NativeAdLoadListener

2.4 NativeAdData

com.adgain.sdk.api.NativeAdData

2.5 NativeAdEventListener

com.adgain.sdk.api.NativeAdEventListener

2.6 NativeAdMediaListener

com.adgain.sdk.api.NativeAdData.NativeAdMediaListener

2.7 安卓下载应用六要素信息

com.adgain.sdk.api.AdAppInfo

由于国内监管部门要求，在安卓下载类广告中，需要给用户披露下载的应用的六要素信息。开发者可以通过 getAdAppInfo() 方法获取。六要素信息包括：

2.8 信息流模板

OAID SDK 集成说明

1. Android 10 OAID 描述

Android 10 无法通过常规方式获取 IMEI 等设备 ID，对广告的加载、展示等业务有一定影响。建议开发者集成 OAID，并在 GTAdSdk 设置 customController 时，为 SDK 提供 OAID。详细的集成方式可以参看 MSA 联盟官网 提供的开发者文档。

2. 引入依赖

把 oaid_sdk_x.x.x.aar 拷贝到项目的 libs 目录，并设置依赖，其中 x.x.x 代表版本号。

implementation files('libs/oaid_sdk_x.x.x.aar')

3. gradle 配置

设置 gradle 编译选项，这里可以根据自己对平台的选择进行合理配置。

ndk {
  abiFilters 'armeabi-v7a','x86','arm64-v8a','x86_64','armeabi'
}

packagingOptions {
    doNotStrip "*/armeabi-v7a/*.so"
    doNotStrip "*/x86/*.so"
    doNotStrip "*/arm64-v8a/*.so"
    doNotStrip "*/x86_64/*.so"
    doNotStrip "armeabi.so"
}

4. 混淆设置

现 SDK 支持 oaid_sdk_1.0.10、1.0.13、1.0.22、1.0.23、1.0.25、1.0.30、1.1.0、1.2.0、1.2.1、2.0.0、2.1.0、2.2.0 等版本，但是媒体必须按照以下混淆配置进行设置。

# 1.0.25 之后

# sdk
-keep class com.bun.miitmdid.** { *; }
-keep interface com.bun.supplier.** { *; }

# asus
-keep class com.asus.msa.SupplementaryDID.** { *; }
-keep class com.asus.msa.sdid.** { *; }
# freeme
-keep class com.android.creator.** { *; }
-keep class com.android.msasdk.** { *; }
# huawei
-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** {*; }
# lenovo
-keep class com.zui.deviceidservice.** { *; }
-keep class com.zui.opendeviceidlibrary.** { *; }
# meizu
-keep class com.meizu.flyme.openidsdk.** { *; }
# nubia
-keep class com.bun.miitmdid.provider.nubia.NubiaIdentityImpl { *; }
# oppo
-keep class com.heytap.openid.** { *; }
# samsung
-keep class com.samsung.android.deviceidservice.** { *; }
# vivo
-keep class com.vivo.identifier.** { *; }
# xiaomi
-keep class com.bun.miitmdid.provider.xiaomi.IdentifierManager { *; }
# zte
-keep class com.bun.lib.** { *; }
# coolpad
-keep class com.coolpad.deviceidsupport.** { *; }

# 1.0.25 之前
-dontwarn com.bun.**
-keep class com.bun.** {*;}
-keep class a.**{*;}
-keep class XI.CA.XI.**{*;}
-keep class XI.K0.XI.**{*;}
-keep class XI.XI.K0.**{*;}
-keep class XI.vs.K0.**{*;}
-keep class XI.xo.XI.XI.**{*;}
-keep class com.asus.msa.SupplementaryDID.**{*;}
-keep class com.asus.msa.sdid.**{*;}
-keep class com.huawei.hms.ads.identifier.**{*;}
-keep class com.samsung.android.deviceidservice.**{*;}
-keep class com.zui.opendeviceidlibrary.**{*;}
-keep class org.json.**{*;}
-keep public class com.netease.nis.sdkwrapper.Utils {public <methods>;}

5. 错误码

信息码（引用 InfoCode 类）。

如何检验 OAID 接入成功

错误码与常见问题

错误码信息说明

1. ADGainSDK 错误码信息说明

相关错误信息可参考此翻译表。

常见集成问题

1. targetSdkVersion 28 以上 http 支持

</manifest>
<application
    android:networkSecurityConfig="@xml/network_security_config"
    android:usesCleartextTraffic="true">
</manifest>

network_security_config.xml 文件配置：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true"/>
</network-security-config>

2. 系统 installProvider 失败或者开启 MultiDex 导致的 Not find Class

参考链接 https://developer.android.com/studio/build/multidex

android {
    buildTypes {
        release {
            multiDexKeepProguard file('multidex-config.pro')
            ...
        }
    }
}

3. 方法数 65k 问题解决

参考链接 https://developer.android.com/studio/build/multidex

build.gradle 配置：

defaultConfig {
    multiDexEnabled true
}

dependencies {

    //AndroidX
    implementation "androidx.multidex:multidex:2.0.1"

    //非AndroidX
    implementation 'com.android.support:multidex:1.0.3'
}

修改 MyAppcation 继承 MultiDexApplication：

public class MyAppcation extends MultiDexApplication {

  override fun attachBaseContext(base: Context) {
      super.attachBaseContext(base)
      MultiDex.install(this)
  }

}

4. AndroidX 与 Android support 冲突

在项目根目录下文件 gradle.properties，添加以下代码：

android.enableJetifier=true
android.useAndroidX=true