# 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 配置
```
//权限配置
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
```
如果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链接，因此需要在这里增加以下声明
```
<application
...
android:networkSecurityConfig="@xml/network_security_config"
... />
```
其中network_security_config内容如下
```
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
<base-config cleartextTrafficPermitted="true" />
</network-security-config>
```
SDK需要的provider声明：
```
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}.fileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/file_paths" />
</provider>
```
其中 file_paths.xml 文件内容如下
```
<?xml version="1.0" encoding="utf-8"?>
<paths>
<external-path path="mimoDownload" name="files_root" />
<external-path path="." name="external_storage_root" />
</paths>
```
若您的项目中本身也需要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.** { <fields>; }
-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 <fields>;
}
# glide
-keep public class * implements com.bumptech.glide.module.GlideModule
-keep class * extends com.bumptech.glide.module.AppGlideModule {
<init>(...);
}
-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> getImageList(); // 广告素材url
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(); // 关闭测试请求开关
```
可将问题截图与报错日志等邮件至[mi-ssp@xiaomi.com](mailto:mi-ssp@xiaomi.com)，会有专人进行处理。
网友评论