# MIMO COMMON SDK 集成文档
v5.0.6_20201124
## 一、SDK介绍
米盟广告SDK (Android) 是由小米联盟官方推出，帮助开发者在安卓平台上轻松实现广告变现的软件工具包。
目前米盟广告SDK提供各种广告形式给客户端集成，SDK支持的广告形式包括：
BANNER 广告 插屏广告 激励视频广告 开屏广告 原生模板广告 原生自渲染广告
## 二、SDK 接入说明
1、米盟广告sdk仅包含一个aar包
mimo-ad-sdk.aar
2、申请应用APP ID 和 广告位ID
开发者需要前往米盟SPP，注册开发者账户，并创建应用。相关帮助请见：点击此处
3、接入注意事项
①请使用小米手机调试，且仅支持Android4.4以上的系统
②在测试环境调试成功后，替换为自己的appid和广告位id，并关闭调试环境，即可申请上架
## 三、接入准备
#### 第一步：AndroidManifest.xml 配置
```
//权限配置
```
如果app目标sdk版本是23及以上，需要在程序中显式申请权限，例子如下：
```
// 如果api >= 23 需要显式申请权限
if (Build.VERSION.SDK_INT >= 23) {
if (ContextCompat.checkSelfPermission(this,Manifest.permission.READ_PHONE_STATE) != PackageManager.PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(this,new String[]{Manifest.permission.READ_PHONE_STATE}, 0);
}
}
```
适配Android 9.0，由于部分广告下载地址依然是http链接，因此需要在这里增加以下声明
```
... android:networkSecurityConfig="@xml/network_security_config" ... /> ``` 其中network_security_config内容如下 ``` ``` SDK需要的provider声明： ``` android:name="androidx.core.content.FileProvider" android:authorities="${applicationId}.fileprovider" android:exported="false" android:grantUriPermissions="true"> android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/file_paths" /> ``` 其中 file_paths.xml 文件内容如下 ``` ``` 若您的项目中本身也需要fileProvider，可与上述的provider合并。合并时在file_paths.xml 中加入文件路径即可。 #### 第二步：build.gradle配置 ``` dependencies { /*引用米盟 sdk ：mimo-ad-sdk*/ implementation(name: 'mimo-ad-sdk', ext: 'aar') implementation 'androidx.appcompat:appcompat:1.0.0' implementation 'com.google.code.gson:gson:2.8.5' implementation 'com.github.bumptech.glide:glide:4.9.0' annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0' } ``` #### 第三步: 配置Proguard 开发者需要在配置里配置 ``` # mimo SDK -keep class com.miui.zeus.mimo.sdk.* { *; } -keep class com.miui.analytics.** { *; } -keep class com.xiaomi.analytics.* { public protected *; } -keep class * extends android.os.IInterface{ *; } # gson -keepattributes Signature -keepattributes *Annotation* -dontwarn sun.misc.** -keep class com.google.gson.examples.android.model.** { -keep class * implements com.google.gson.TypeAdapterFactory -keep class * implements com.google.gson.JsonSerializer -keep class * implements com.google.gson.JsonDeserializer -keepclassmembers,allowobfuscation class * { @com.google.gson.annotations.SerializedName } # glide -keep public class * implements com.bumptech.glide.module.GlideModule -keep class * extends com.bumptech.glide.module.AppGlideModule { } -keep public enum com.bumptech.glide.load.ImageHeaderParser$** { **[] $VALUES; public *; } -keep class com.bumptech.glide.load.data.ParcelFileDescriptorRewinder$InternalRewinder { *** rewind(); } # androidx -dontwarn com.google.android.material.** -keep class com.google.android.material.** { *; } -dontnote com.google.android.material.** -dontwarn androidx.** -keep class androidx.** { *; } -keep interface androidx.** { *; } -keep public class * extends androidx.** ``` #### 第四步：初始化SDK 在 Application onCreate 时候需要初始化 联盟sdk。 调用如下接口: APP_ID请在开发者网站注册后获取 ``` /** * @param context context * @param appId 米盟appid */ MimoSdk.init(this, APP_ID); // 以下为调试开关，上线需关闭，默认均为false MimoSdk.setDebugOn(boolean enable); // 设置sdk 是否打开debug MimoSdk.setStagingOn(boolean enable); // 设置sdk是否打开测试环境 ``` ## 四、具体广告接入方式 （具体可参考demo） #### BANNER 广告 ##### 1、请求广告 ``` // 请求banner广告 BannerAd bannerAd = new BannerAd(); bannerAd.loadAd(BANNER_POSITION_ID, new BannerAd.BannerLoadListener() { @Override public void onBannerAdLoadSuccess() { // 请求广告成功, 在需要的时候可以展示广告 showAd(); } @Override public void onAdLoadFailed (int error, String errorMsg) { // 请求广告失败 } }) ``` 2、展示广告 ``` mBannerAd.showAd(container, mBannerInteractionListener); ``` 3、销毁广告，在不需要广告的时候进行销毁 ``` mBannerAd.destroy(); ``` 4、相关接口 ``` public interface BannerLoadListener { void onBannerAdLoadSuccess(); // 广告请求成功 void onAdLoadFailed(int errorCode, String errorMsg); // 广告请求失败 } public interface BannerInteractionListener { void onAdClick(); // 广告被点击 void onAdShow(); // 广告被展示 void onAdDismiss(); // 广告消失 void onRenderSuccess(); // 广告渲染成功 void onRenderFail(int code, String msg); // 广告渲染失败 } ``` #### 插屏广告 ##### 1、请求广告 ``` // 请求广告 mInterstitialAd = new InterstitialAd(); mInterstitialAd.loadAd(POSITION_ID, new InterstitialAd.InterstitialAdLoadListener() { @Override public void onAdLoadSuccess() { } @Override public void onAdLoadFailed(int errorCode, String errorMsg) { Log.e(TAG, "onAdLoadFailed errorMsg=" + errorMsg); } }); ``` ##### 2、展示广告 ``` mInterstitialAd.show(activity,mInterstitialAdInteractionListener); ``` ##### 3、销毁广告，在不需要广告的时候进行销毁 ``` mInterstitialAd.destroy(); ``` ##### 4、相关接口 ``` public interface InterstitialAdLoadListener { void onAdLoadSuccess(); // 广告请求成功 void onAdLoadFailed(int errorCode, String errorMsg); // 广告请求失败 } public interface InterstitialAdInteractionListener { void onAdClick(); // 广告被点击 void onAdShow(); // 广告展示 void onAdClosed(); // 广告关闭 void onRenderFail(int code, String msg); // 广告渲染失败 //视频广告会收到下面的回调 void onVideoStart();//视频开始播放 void onVideoPause();//视频暂停 void onVideoResume(); void onVideoEnd(); } ``` #### 激励视频广告 ##### 1、请求广告 ``` // 请求广告 mRewardVideoAd = new RewardVideoAd(); mRewardVideoAd.loadAd(PORTRAIT_POS_ID, new RewardVideoAd.RewardVideoLoadListener() { @Override public void onAdLoadSuccess() { showAd(); } @Override public void onAdLoadFailed(int errorCode, String errorMsg) { Log.e("", "errorcode = " + errorCode + ", errorMsg = " + errorMsg); } }); ``` ##### 2、展示广告 ``` mRewardVideoAd.showAd(activity,mRewardVideoInteractionListener); ``` ##### 3、销毁广告，在不需要广告的时候进行销毁 ``` mRewardVideoAd.recycle(); ``` ##### 4、相关接口 ``` public interface RewardVideoLoadListener { void onAdRequestSuccess(); //请求广告成功，服务端成功返回广告 void onAdLoadSuccess(); //请求广告成功，且素材缓存成功 void onAdLoadFailed(int errorCode, String errorMsg); // 请求广告失败 } // 正常情况下，onAdRequestSuccess()和onAdLoadSuccess()会先后回调，回调onAdLoadSuccess()之后，调用show()方法展示广告，详见demo public interface RewardVideoInteractionListener { void onAdPresent(); // 广告被曝光 void onAdClick(); // 广告被点击 void onAdDismissed(); // 广告消失 void onAdFailed(String message); // 渲染失败 void onVideoStart(); // 视频开始播放 void onVideoPause(); // 视频暂停 void onVideoComplete(); // 视频播放完成 void onPicAdEnd(); // 图片类型广告播放完成 } ``` #### 开屏广告 请注意：暂不支持SDK内竖版开屏广告类型，如您有竖版开屏的广告需求，请根据SSP后台提示启动系统开屏广告位 ##### 1、加载并展示广告 ``` // 初始化广告 SplashAd mSplashAd = new SplashAd(); /** * 请求并展示广告 * mContainer 装载广告的容器 * POSITION_ID 广告位id * mSplashAdListener 广告监听listener */ mSplashAd.loadAndShow(mContainer, POSITION_ID, mSplashAdListener); ``` ##### 2、销毁广告 ``` // 销毁广告，在不需要广告的时候进行销毁 mSplashAd.destroy(); ``` ##### 3、相关接口 ``` public interface SplashAdListener { void onAdShow(); // 广告展示 void onAdClick(); // 广告被点击 void onAdDismissed(); // 广告消失 void onAdLoadFailed(int errorCode, String errorMessage); // 广告加载失败 void onAdLoaded(); // 广告加载成功 void onAdRenderFailed(); //广告渲染失败 } // 销毁广告，在不需要广告的时候进行销毁 mTemplateAd.destroy(); ``` #### 原生模板广告 请注意：信息流广告在V5.0.0版本起升级为原生模板广告，支持个性化调整模板样式 原信息流大图对应原生模板上图下文；原信息流小图广告对应原生模板左文右图(带标题)；原信息流组图对应原生模板上文下图(组图) ##### 1、请求广告 ``` /** * POSITION_ID 广告位id * mTemplateAdLoadListener 原生模板广告加载监听listener */ TemplateAd mTemplateAd = new TemplateAd(); mTemplateAd.load(POSITION_ID, mTemplateAdLoadListener); ``` ##### 2、展示广告 ``` /** * mContainer 用来装载广告的容器 * mTemplateAdInteractionListener 广告行为监听listener */ mTemplateAd.show(mContainer, mTemplateAdInteractionListener); ``` ##### 3、销毁广告 ``` mNativeAd.destroy(); ``` ##### 4、相关接口 ``` // 广告加载监听接口 public interface TemplateAdLoadListener { void onAdLoaded(); // 加载成功 void onAdLoadFailed(int errorCode, String errorMessage); // 加载失败 } // 广告行为监听接口 public interface TemplateAdInteractionListener { void onAdShow(); // 广告展示 void onAdClick(); // 广告被点击 void onAdDismissed(); // 广告消失 void onAdRenderFailed(int errorCode, String errorMsg); // 广告渲染失败 } ``` #### 原生自渲染广告 请注意：对接原生自渲染广告形式，需向对接的商务经理申请使用权限，权限开通后，可在米盟SSP后台申请创建原生自渲染广告位 自渲染广告需明确标示广告来源，小米广告logo文件详见压缩包png文件 ##### 1、请求广告 ``` // 请求自渲染广告 NativeAd mNativeAd = new NativeAd(); mNativeAd.loadAd(NATIVE_POSITION_ID, new NativeAd.NativeAdLoadListener() { @Override public void onAdLoadSuccess(NativeAdData nativeAdData){ // **重要** 注册自渲染广告的container，不注册无法产生广告收益 mNativeAd.registerAdView(mTvAdContent, mNativeAdInteractionListener); // 请求广告成功, 在需要的时候可以展示广告 showAd(); } @Override public void onAdLoadFailed (int error, String errorMsg) { // 请求广告失败 } }) ``` ##### 2、广告数据对象接口说明 ``` String getTitle(); // 广告标题 String getDesc(); // 广告描述 List String getIconUrl(); // 广告icon url String getAdMark(); // 广告logo String getButtonText(); // 广告按钮文本 // 广告交互类型 // NativeAdData.AD_TYPE_LINK 外链 // NativeAdData.AD_TYPE_DOWNLOAD 下载类 int getAdType(); // 广告样式 // NativeAdData.AD_STYLE_IMAGE_BIG 大图 // NativeAdData.AD_STYLE_IMAGE_SMALL 小图 // NativeAdData.AD_STYLE_IMAGE_GROUP 组图 int getAdStyle(); ``` ##### 3、销毁广告，在不需要广告的时候进行销毁 ``` mNativeAd.destroy(); ``` ##### 4、相关接口 ``` public interface NativeAdLoadListener { void onAdLoadSuccess(NativeAdData nativeAdData); // 广告请求成功，返回了广告数据对象 nativeAdData void onAdLoadFailed(int errorCode, String errorMsg); // 广告请求失败 } public interface NativeAdInteractionListener { void onAdClick(); // 广告被点击 void onAdShow(); // 广告被展示 } ``` ### 五、SDK调试 开发者接入SDK时，应用包可能还未上架应用商店，在接入的时候，建议使用demo中的测试广告位进行调试,保证接入方式无问题。 测试使用的appid：2882303761517518052 | 广告类型 | 测试广告位ID | | ------------------------- | :------------------------------- | | 横幅 | 802e356f1726f9ff39c69308bfd6f06a | | 横版插屏 | 1d576761b7701d436f5a9253e7cf9572 | | 竖版插屏 | 67b05e7cc9533510d4b8d9d4d78d0ae9 | | 横版激励视频广告 | 17853953c5adafd100f24cd747edd6b7 | | 竖版激励视频广告 | 92d90db71791e6b9f7caaf46e4a997ec | | 横版开屏 | 94f4805a2d50ba6e853340f9035fda18 | | 悬浮球广告 | a6fa00f86c8d849bd9eccade17e3eba5 | | 激励下载广告 | 6d089fcf31523ea73ca94138571ed31e | | 原生模板-上文下图 | 4966931579570a31c70269f560e9577e | | 原生模板-左文右图 | e8cad3a962d8f5ccb3e42a5c2427107d | | 原生模板-左图右文（A版） | 4cc5ca1fa86d05c3c9dbec05ce5bb1b8 | | 原生模板-左图右文（B版） | 8577377ac0a045a5187a5506f3cf6ba6 | | 原生模板-上图下文（大图） | 8f02fd1f100b57f536da160a84fa95a6 | | 原生模板-上图下文（组图） | 9d72e47b9640044d1f6bcbd4d3277d19 | | 自渲染——大图 | 702b6a3b2f67a52efd3bdbf51fbef5fe | | 自渲染——小图 | 60d2a98004f3a2a3625a1665796e0ebb | | 自渲染——组图 | c020c2cbc40301a2a18fe32977bddcaa | 如果接入能正常显示广告，则说明广告接入无问题。此时替换成自己的appid和广告位id，并关闭调试环境即可见到广告展现。 ### 六、错误码 | code | 含义 | 备注 | | :----- | :---------------------------- | :---------------------------------------- | | 300001 | 广告位不存在 | 请确认广告位是否是开启状态 | | 300002 | 广告位在米盟SSP被暂停 | 开发者关闭了广告位 | | 300003 | upId不存在 | | | 300004 | 广告位被加入黑名单 | 通常是因为有作弊嫌疑，请联系米盟解决 | | 300005 | 应用在米盟SSP被暂停 | 开发者暂停了应用下所有广告位 | | 300006 | 应用被加入黑名单 | 通常是因为有作弊嫌疑，请联系米盟解决 | | 300007 | 应用不存在 | 确认广告位的应用信息是否正确 | | 300009 | 应用未上架 | | | 100401 | 被联盟投放限制过滤 | 根据开发者在SSP后台设置的屏蔽策略屏蔽广告 | | 100402 | 请求包名与注册包名不一致 | 请求包名与注册包名不一致将不返回广告 | | 101101 | 广告位内部解析错误 内部错误， | 请联系米盟解决 | | 101102 | 内部错误 | 请联系米盟解决 | | 101103 | 内部错误 | 请联系米盟解决 | | 101104 | 内部错误 | 请联系米盟解决 | | 300215 | 频控限制 | 更换调试设备解决 | | 300216 | 请联系米盟解决 | 请联系米盟解决 | | 300217 | 请联系米盟解决 | 请联系米盟解决 | | 300218 | 请联系米盟解决 | 请联系米盟解决 | | 300220 | 请联系米盟解决 | 请联系米盟解决 | | 300221 | 请联系米盟解决 | 请联系米盟解决 | | 300222 | 请联系米盟解决 | 请联系米盟解决 | | 300223 | 请联系米盟解决 | 请联系米盟解决 | | 300224 | 请联系米盟解决 | 请联系米盟解决 | | 300225 | 请联系米盟解决 | 请联系米盟解决 | | 300226 | 请联系米盟解决 | 请联系米盟解决 | | 300227 | 请联系米盟解决 | 请联系米盟解决 | | 300228 | 请联系米盟解决 | 请联系米盟解决 | 如根据以上的解决方案仍未解决问题，可开启debug调试环境，获取报错日志，放到txt文件中提供给我们，不用做任何tag筛选。 使用调试环境时，请使用测试广告位id和测试appid,正式环境广告位id和测试环境广告位id只能在相应环境下使用，不能混用。测试环境广告位id在本文第五节提供，正式环境广告位id在您的米盟账户中相应媒体下创建，正式环境中，不同媒体的广告位的广告位id不能混用。 以下为开启调试环境的方式 MimoSdk.setDebugOn(); // 打开调试，输出调试信息 ；MimoSdk.setStageOn(); // 打开测试请求开关，请求测试广告 上架提审前，必须关闭调试开关，否则无法正常计费，示例： ``` // MimoSdk.setDebugOn(); // 关闭调试 // MimoSdk.setStageOn(); // 关闭测试请求开关 ``` 可将问题截图与报错日志等邮件至[[email protected]](mailto:[email protected])，会有专人进行处理。