v5.0.9_20210310

一、SDK介绍

米盟广告SDK (Android) 是由小米联盟官方推出，帮助开发者在安卓平台上轻松实现广告变现的软件工具包。

目前米盟广告SDK提供各种广告形式给客户端集成，SDK支持的广告形式包括：

• Banner广告
• 插屏广告
• 激励视频广告
• 开屏广告
• 原生模板广告
• 原生自渲染广告
• 原生视频广告

二、SDK 接入说明

1、米盟广告SDK仅包含一个aar包

mimo-ad-sdk.aar

2、申请应用APP ID 和 广告位ID

开发者需要前往米盟SPP，注册开发者账户，并创建应用。相关帮助请见：点击此处

3、接入注意事项

1. 请使用小米手机调试，且仅支持Android4.4以上的系统
2. 在测试环境调试成功后，替换为自己的appid和广告位id，并关闭调试环境，即可申请上架

三、接入准备

1、AndroidManifest.xml 配置

权限配置

1
<uses-permission android:name="android.permission.INTERNET"/>
2
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
3
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
4
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
5
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
6
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
7
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

如果app目标sdk版本是23及以上，需要在程序中显式申请权限，例子如下：

xxxxxxxxxx
5
1
if (Build.VERSION.SDK_INT >= 23) {
2
    if (ContextCompat.checkSelfPermission(this,Manifest.permission.READ_PHONE_STATE) != PackageManager.PERMISSION_GRANTED) {
3
        ActivityCompat.requestPermissions(this,new String[]{Manifest.permission.READ_PHONE_STATE}, 0);
4
    }
5
}

适配Android 9.0，由于部分广告下载地址依然是http链接，因此需要在这里增加以下声明

xxxxxxxxxx
4
1
<application
2
        ...
3
        android:networkSecurityConfig="@xml/network_security_config"
4
        ... />

其中network_security_config内容如下

xxxxxxxxxx
4
1
<?xml version="1.0" encoding="utf-8"?>
2
<network-security-config>
3
    <base-config cleartextTrafficPermitted="true" />
4
</network-security-config>

SDK需要的provider声明：

xxxxxxxxxx
9
1
<provider
2
     android:name="androidx.core.content.FileProvider"
3
     android:authorities="${applicationId}.fileprovider"
4
     android:exported="false"
5
     android:grantUriPermissions="true">
6
     <meta-data
7
         android:name="android.support.FILE_PROVIDER_PATHS"
8
         android:resource="@xml/file_paths" />
9
</provider>

其中 file_paths.xml 文件内容如下

xxxxxxxxxx
6
1
<?xml version="1.0" encoding="utf-8"?>
2
<paths>
3
    <external-files-path
4
        name="files_root"
5
        path="mimoDownload" />
6
</paths>

若您的项目中本身也需要fileProvider，可与上述的provider合并。合并时在file_paths.xml 中加入文件路径即可。

2、build.gradle配置

xxxxxxxxxx
7
1
dependencies {
2
    /*引用米盟 sdk ：mimo-ad-sdk*/
3
    implementation(name: 'mimo-ad-sdk', ext: 'aar')
4
    implementation 'com.google.code.gson:gson:2.8.5'
5
    implementation 'com.github.bumptech.glide:glide:4.9.0'
6
    annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
7
}

3、混淆配置

如果您需要使用proguard混淆代码，需确保不要混淆SDK的代码。请在混淆文件中添加如下配置:

xxxxxxxxxx
36
1
# mimo SDK
2
-keep class com.miui.zeus.mimo.sdk.* {
3
    *;
4
}
5
-keep class com.miui.analytics.** { *; }
6
-keep class com.xiaomi.analytics.* { public protected *; }
7
-keep class * extends android.os.IInterface{
8
    *;
9
}
10
 
11
# gson
12
-keepattributes Signature
13
-keepattributes *Annotation*
14
-dontwarn sun.misc.**
15
-keep class com.google.gson.examples.android.model.** { <fields>; }
16
-keep class * implements com.google.gson.TypeAdapterFactory
17
-keep class * implements com.google.gson.JsonSerializer
18
-keep class * implements com.google.gson.JsonDeserializer
19
-keepclassmembers,allowobfuscation class * {
20
  @com.google.gson.annotations.SerializedName <fields>;
21
}
22
 
23
# glide
24
-keep public class * implements com.bumptech.glide.module.GlideModule
25
-keep class * extends com.bumptech.glide.module.AppGlideModule {
26
 <init>(...);
27
}
28
-keep public enum com.bumptech.glide.load.ImageHeaderParser$** {
29
  **[] $VALUES;
30
  public *;
31
}
32
-keep class com.bumptech.glide.load.data.ParcelFileDescriptorRewinder$InternalRewinder {
33
  *** rewind();
34
}
35
-keep class com.market.** { *; }
36
-dontwarn com.market.**

4、初始化SDK

在使用SDK请求广告之前，您需要初始化联盟SDK。 调用如下接口:

xxxxxxxxxx
4
1
/**
2
 * @param context 初始化所需context
3
 */
4
MimoSdk.init(Context context);

以下为调试开关，上线需关闭，默认均为false

xxxxxxxxxx
2
1
MimoSdk.setDebugOn(boolean enable); //设置sdk 是否打开debug
2
MimoSdk.setStagingOn(boolean enable); //设置sdk是否打开测试环境

SDK日志的prefix关键字为zeus-mimo

当debug开关关闭的情况下，只会输出error日志

当debug开关打开时，可以输出更多调试日志

注意：开发者在接入遇到问题时，如果需要协助排查，请提供完整的系统log日志

• 不要过滤任何关键字或任何信息
• 不要过滤任何关键字或任何信息
• 不要过滤任何关键字或任何信息

四、具体广告接入方式 （具体可参考demo）

1、BANNER 广告

请求广告

xxxxxxxxxx
13
1
BannerAd bannerAd = new BannerAd();
2
bannerAd.loadAd(BANNER_POSITION_ID, new BannerAd.BannerLoadListener() {
3
    @Override
4
    public void onBannerAdLoadSuccess() {
5
        //请求广告成功, 在需要的时候可以展示广告
6
        showAd();
7
    }
8
  
9
    @Override
10
    public void onAdLoadFailed (int error, String errorMsg) {
11
        //请求广告失败
12
    }
13
});

展示广告

xxxxxxxxxx
1
1
bannerAd.showAd(container, new BannerAd.BannerInteractionListener());

销毁广告，在不需要广告的时候进行销毁

xxxxxxxxxx
1
1
bannerAd.destroy();

相关接口

xxxxxxxxxx
17
1
/**
2
 * 广告请求监听listener
3
 */
4
public interface BannerLoadListener {
5
    void onBannerAdLoadSuccess(); // 广告请求成功
6
    void onAdLoadFailed(int errorCode, String errorMsg); // 广告请求失败
7
}
8
/**
9
 * 广告行为监听listener
10
 */
11
public interface BannerInteractionListener {
12
    void onAdClick(); // 广告被点击
13
    void onAdShow(); // 广告被展示
14
    void onAdDismiss(); // 广告消失
15
    void onRenderSuccess(); // 广告渲染成功
16
    void onRenderFail(int code, String msg); // 广告渲染失败
17
}

2、插屏广告

请求广告

xxxxxxxxxx
12
1
InterstitialAd interstitialAd = new InterstitialAd(); 
2
interstitialAd.loadAd(POSITION_ID, new InterstitialAd.InterstitialAdLoadListener() {
3
    @Override
4
    public void onAdLoadSuccess() {
5
        //广告请求成功
6
    }
7
    
8
    @Override
9
    public void onAdLoadFailed(int errorCode, String errorMsg) {
10
        //广告请求失败
11
    }
12
});

展示广告

xxxxxxxxxx
6
1
/**
2
 * 展示广告
3
 * 
4
 * @param context                           展示广告界面activity
5
 * @param interstitialAdInteractionListener 广告行为监听listener
6
 */interstitialAd.show(activity,new InterstitialAd.InterstitialAdInteractionListener());

销毁广告，在不需要广告的时候进行销毁

xxxxxxxxxx
1
1
interstitialAd.destroy();

相关接口

​x
1
/**
2
 * 广告请求监听listener
3
 */
4
public interface InterstitialAdLoadListener {
5
    void onAdLoadSuccess(); // 广告请求成功
6
    void onAdLoadFailed(int errorCode, String errorMsg); // 广告请求失败
7
}
8
​
9
/**
10
 * 广告行为监听listener
11
 */
12
public interface InterstitialAdInteractionListener {
13
    void onAdClick(); // 广告被点击
14
    void onAdShow(); // 广告展示
15
    void onAdClosed(); // 广告关闭
16
    void onRenderFail(int code, String msg); // 广告渲染失败
17
    
18
    //视频广告会收到下面的回调
19
    void onVideoStart();//视频开始播放
20
    void onVideoPause();//视频暂停
21
    void onVideoResume();
22
    void onVideoEnd();
23
}

3、激励视频广告

请求广告

xxxxxxxxxx
17
1
RewardVideoAd rewardVideoAd = new RewardVideoAd();
2
rewardVideoAd.loadAd(PORTRAIT_POS_ID, new RewardVideoAd.RewardVideoLoadListener() {
3
    @Override
4
    public void onAdRequestSuccess() {
5
        //广告网络请求成功
6
    }
7
​
8
    @Override
9
    public void onAdLoadSuccess() {
10
        //广告素材缓存成功，可调用show展示广告
11
    }
12
    
13
    @Override
14
    public void onAdLoadFailed(int errorCode, String errorMsg) {
15
        //广告加载失败
16
    }
17
});

展示广告

xxxxxxxxxx
1
1
rewardVideoAd.showAd(activity,new RewardVideoAd.RewardVideoInteractionListener());

销毁广告，在不需要广告的时候进行销毁

xxxxxxxxxx
1
1
rewardVideoAd.recycle();

相关接口

xxxxxxxxxx
24
1
/**
2
 * 广告请求监听listener
3
 */
4
public interface RewardVideoLoadListener {
5
    void onAdRequestSuccess(); //请求广告成功，服务端成功返回广告
6
    void onAdLoadSuccess(); //请求广告成功，且素材缓存成功
7
    void onAdLoadFailed(int errorCode, String errorMsg); // 请求广告失败
8
}
9
// 正常情况下，onAdRequestSuccess()和onAdLoadSuccess()会先后回调，回调onAdLoadSuccess()之后，调用show()方法展示广告，详见demo
10
​
11
/**
12
 * 广告行为监听listener
13
 */
14
public interface RewardVideoInteractionListener {
15
    void onAdPresent(); // 广告被曝光
16
    void onAdClick(); // 广告被点击
17
    void onAdDismissed(); // 广告消失
18
    void onAdFailed(String message); // 渲染失败
19
    void onVideoStart(); // 视频开始播放
20
    void onVideoPause(); // 视频暂停
21
    void onVideoComplete(); // 视频播放完成
22
    void onPicAdEnd(); // 图片类型广告播放完成
23
    void onReward(); //激励回调 可通过监听该回调作为奖励发放的判断依据
24
}

4、开屏广告

请注意：暂不支持SDK内竖版开屏广告类型，如您有竖版开屏的广告需求，请根据SSP后台提示启动系统开屏广告位

加载并展示广告

xxxxxxxxxx
11
1
//初始化广告
2
SplashAd splashAd = new SplashAd();
3
​
4
/**
5
 * 请求并展示广告
6
 *
7
 * @param container        装载广告的容器
8
 * @param upId             POSITION_ID 广告位id
9
 * @param splashAdListener 广告监听listener
10
 */
11
splashAd.loadAndShow(mContainer, POSITION_ID, mSplashAdListener);

销毁广告

xxxxxxxxxx
2
1
//销毁广告，在不需要广告的时候进行销毁
2
mSplashAd.destroy();

相关接口

xxxxxxxxxx
8
1
public interface SplashAdListener {
2
    void onAdShow(); // 广告展示
3
    void onAdClick(); // 广告被点击
4
    void onAdDismissed(); // 广告消失
5
    void onAdLoadFailed(int errorCode, String errorMessage); // 广告加载失败
6
    void onAdLoaded(); // 广告加载成功
7
    void onAdRenderFailed(); //广告渲染失败
8
}

5、原生模板广告

请注意：信息流广告在V5.0.0版本起升级为原生模板广告，支持个性化调整模板样式:

• 原信息流大图对应原生模板上图下文
• 原信息流小图广告对应原生模板左文右图(带标题)
• 原信息流组图对应原生模板上文下图(组图)

请求广告

xxxxxxxxxx
2
1
TemplateAd templateAd = new TemplateAd();
2
templateAd.load(POSITION_ID, mTemplateAdLoadListener);

展示广告

xxxxxxxxxx
1
1
templateAd.show(mContainer, mTemplateAdInteractionListener);

销毁广告

xxxxxxxxxx
1
1
templateAd.destroy();

相关接口

xxxxxxxxxx
17
1
/**
2
 * 广告请求监听listener
3
 */
4
public interface TemplateAdLoadListener {
5
    void onAdLoaded(); // 加载成功
6
    void onAdLoadFailed(int errorCode, String errorMessage); // 加载失败
7
}
8
​
9
/**
10
 * 广告行为监听listener
11
 */
12
public interface TemplateAdInteractionListener {
13
    void onAdShow(); // 广告展示
14
    void onAdClick(); // 广告被点击
15
    void onAdDismissed(); // 广告消失
16
    void onAdRenderFailed(int errorCode, String errorMsg); // 广告渲染失败
17
}

6、原生自渲染广告

请注意：对接原生自渲染广告形式，需向对接的商务经理申请使用权限，权限开通后，可在米盟SSP后台申请创建原生自渲染广告位

自渲染广告需明确标示广告来源，小米广告logo文件详见压缩包png文件

、请求广告

xxxxxxxxxx
14
1
NativeAd mNativeAd = new NativeAd();
2
mNativeAd.loadAd(NATIVE_POSITION_ID, new NativeAd.NativeAdLoadListener() {
3
  @Override
4
  public void onAdLoadSuccess(NativeAdData nativeAdData){
5
  // **重要** 注册自渲染广告的container，不注册无法产生广告收益
6
  mNativeAd.registerAdView(mTvAdContent, mNativeAdInteractionListener);
7
  // 请求广告成功, 在需要的时候可以展示广告
8
  showAd();
9
} 
10
@Override
11
public void onAdLoadFailed (int error, String errorMsg) {
12
  // 请求广告失败
13
}
14
})

广告数据对象接口说明

xxxxxxxxxx
18
1
String getTitle(); // 广告标题
2
String getDesc(); // 广告描述
3
List<String> getImageList(); // 广告素材url
4
String getIconUrl(); // 广告icon url
5
String getAdMark(); // 广告logo
6
String getButtonText(); // 广告按钮文本
7
// 广告交互类型
8
// NativeAdData.AD_TYPE_LINK 外链
9
// NativeAdData.AD_TYPE_DOWNLOAD 下载类
10
int getAdType(); 
11
// 广告样式
12
// NativeAdData.AD_STYLE_IMAGE_BIG 大图
13
// NativeAdData.AD_STYLE_IMAGE_SMALL 小图
14
// NativeAdData.AD_STYLE_IMAGE_GROUP 组图
15
// NativeAdData.AD_STYLE_VIDEO 视频
16
// NativeAdData.AD_STYLE_IMAGE_AND_VIDEO 图片和视频
17
int getAdStyle();
18
String getVideoUrl(); //视频地址

销毁广告，在不需要广告的时候进行销毁

xxxxxxxxxx
1
1
mNativeAd.destroy();

相关接口

xxxxxxxxxx
8
1
public interface NativeAdLoadListener {
2
    void onAdLoadSuccess(NativeAdData nativeAdData); // 广告请求成功，返回了广告数据对象 nativeAdData
3
void onAdLoadFailed(int errorCode, String errorMsg); // 广告请求失败
4
}
5
public interface NativeAdInteractionListener {
6
    void onAdClick(); // 广告被点击
7
    void onAdShow(); // 广告被展示
8
}

原生视频

请求广告

xxxxxxxxxx
17
1
FeedAd feedAd = new FeedAd();
2
feedAd.load(POS_ID, new FeedAd.FeedLoadListener() {
3
    @Override
4
    public void onAdResourceCached() {
5
        //资源缓存成功，可调用show()展示广告
6
    }
7
​
8
    @Override
9
    public void onAdRequestSuccess() {
10
        //网络请求成功
11
    }
12
​
13
    @Override
14
    public void onAdLoadFailed(int errorCode, String errorMessage) {
15
        //广告加载失败
16
    }
17
});

注册广告行为监听

xxxxxxxxxx
36
1
mFeedAd.registerInteraction(mContext, container, new FeedAd.FeedInteractionListener() {
2
            @Override
3
            public void onAdShow() {
4
                //广告展示
5
            }
6
​
7
            @Override
8
            public void onAdClick() {
9
                //广告被点击
10
            }
11
​
12
            @Override
13
            public void onAdClosed() {
14
                //广告被关闭
15
            }
16
​
17
            @Override
18
            public void onRenderFail(int errorCode, String message) {
19
                //广告渲染失败
20
            }
21
​
22
            @Override
23
            public void onVideoStart() {
24
                //视频开始播放
25
            }
26
​
27
            @Override
28
            public void onVideoPause() {
29
                //视频暂停
30
            }
31
​
32
            @Override
33
            public void onVideoResume() {
34
                //视频恢复播放
35
            }
36
        });

registerInteraction方法及参数说明

xxxxxxxxxx
9
1
/**
2
 * 注册广告行为监听
3
 *
4
 * @param activity                广告所在界面的activity
5
 * @param container               广告view的父容器
6
 * @param feedInteractionListener 广告行为listener
7
 */
8
 registerInteraction(Activity activity, ViewGroup container,
9
            FeedAd.FeedInteractionListener feedInteractionListener) 

获取广告视图

xxxxxxxxxx
1
1
feedAd.getAdView(); //@return View

销毁广告

当您在不需要使用广告时，销毁广告，并释放资源

xxxxxxxxxx
1
1
feedAd.destroy();

五、SDK调试

开发者接入SDK时，应用包可能还未上架应用商店，在接入的时候，建议使用demo中的测试广告位进行调试,保证接入方式无问题。

测试使用的appid：2882303761517518052

如果接入能正常显示广告，则说明广告接入无问题。此时替换成自己的appid和广告位id，并关闭调试环境即可见到广告展现。

六、错误码

如根据以上的解决方案仍未解决问题，可开启debug调试环境，获取报错日志，放到txt文件中提供给我们，不用做任何tag筛选。

使用调试环境时，请使用测试广告位id和测试appid,正式环境广告位id和测试环境广告位id只能在相应环境下使用，不能混用。测试环境广告位id在本文第五节提供，正式环境广告位id在您的米盟账户中相应媒体下创建，正式环境中，不同媒体的广告位的广告位id不能混用。

以下为开启调试环境的方式

xxxxxxxxxx
2
1
MimoSdk.setDebugOn(true); //打开调试，输出调试信息
2
MimoSdk.setStageOn(true); //打开测试请求开关，请求测试广告

上架提审前，必须关闭调试开关，否则无法正常计费，示例：

xxxxxxxxxx
2
1
//MimoSdk.setDebugOn(false); // 关闭调试
2
//MimoSdk.setStageOn(false); // 关闭测试请求开关

可将问题截图与报错日志等邮件至mi-ssp@xiaomi.com，会有专人进行处理。