MIMO COMMON SDK 集成文档

v5.1.7_20220228

一、SDK介绍

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

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

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

二、SDK 接入说明

1、接入方式

1> aar接入

将aar文件的SDK复制到 Application Module/libs 文件夹(没有的话需手动创建),并将以下代码添加到 Application Module/build.gradle中

repositories {
    flatDir {
        dirs 'libs'
    }
}
 
dependencies {
    implementation(name: 'mimo-ad-sdk', ext: 'aar')
}

2> maven接入

第一步，在您工程的build.gradle添加如下maven配置项

xxxxxxxxxx
repositories {
    google()
    jcenter()
    maven {
        url "https://repos.xiaomi.com/maven"
        credentials {
            username 'mimo-developer'
            password 'AKCp8ih1PFG9tV8qaLyws67dLGZi8udFM39SfsHgihN15cgsiRvHuxj8JzFmuZjaViVeNawaA'
        }
    }
}

credentials中的内容是米盟为开发者提供用于访问maven仓库的认证信息

第二步，添加完成之后，在build.gradle添加米盟SDK依赖项

xxxxxxxxxx
implementation 'com.miui.zeus:mimo-ad-sdk:5.1.7'

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

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

3、接入注意事项

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

三、接入准备

1、AndroidManifest.xml 配置

权限配置

xxxxxxxxxx
<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"/>

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

xxxxxxxxxx
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链接，因此需要在这里增加以下声明

xxxxxxxxxx
<application
        ...
        android:networkSecurityConfig="@xml/network_security_config"
        ... />

其中network_security_config内容如下

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

SDK需要的provider声明：

xxxxxxxxxx
<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 文件内容如下

xxxxxxxxxx
<?xml version="1.0" encoding="utf-8"?>
<paths>
    <external-files-path
        name="files_root"
        path="mimoDownload" />
</paths>

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

2、build.gradle配置

xxxxxxxxxx
dependencies {
    /*引用米盟 sdk ：mimo-ad-sdk*/
    implementation(name: 'mimo-ad-sdk', ext: 'aar')
    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'
}

3、混淆配置

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

xxxxxxxxxx
# 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();
}
-keep class com.market.** { *; }
-dontwarn com.market.**

4、初始化SDK

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

注：SDK初始化接口必须在用户选择同意隐私协议后调用，若用户拒绝隐私协议，不可调用该广告SDK初始化接口

xxxxxxxxxx
/**
 * @param context 初始化所需context
 */
MimoSdk.init(Context context);
或者
/**
 * @param context 初始化所需context
 * @param initCallback 初始化结果回调
 */
MimoSdk.init(Context context,InitCallback initCallback)

初始化接口说明

​x
public static void init(Context context)
public static void init(Context context, InitCallback initCallback)

public interface InitCallback {
    /**
     * 初始化成功回调 注意：开发者需要在success回调之后再去请求广告
     */
    void success();
    /**
     * @param code 初始化失败回调错误码
     * @param msg  初始化失败回调信息
     */
    void fail(int code, String msg);
}

fail code说明

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

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

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

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

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

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

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

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

1、BANNER 广告

请求广告

xxxxxxxxxx
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) {
        //请求广告失败
    }
});

展示广告

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

展示广告, 支持等比缩放，bannerViewScale取值范围(0,1]

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

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

xxxxxxxxxx
bannerAd.destroy();

相关接口

xxxxxxxxxx
/**
 * 广告请求监听listener
 */
public interface BannerLoadListener {
    void onBannerAdLoadSuccess(); // 广告请求成功
    void onAdLoadFailed(int errorCode, String errorMsg); // 广告请求失败
}
/**
 * 广告行为监听listener
 */
public interface BannerInteractionListener {
    void onAdClick(); // 广告被点击
    void onAdShow(); // 广告被展示
    void onAdDismiss(); // 广告消失
    void onRenderSuccess(); // 广告渲染成功
    void onRenderFail(int code, String msg); // 广告渲染失败
}

2、插屏广告（图片&全屏视频&半屏视频）

新加插屏半屏视频广告类型，已经创建了广告位的开发者需要在后台自己勾选新的预算类型可增加收入，新创建广告位的开发者会默认勾选图片和视频预算。

请求广告

xxxxxxxxxx
InterstitialAd interstitialAd = new InterstitialAd(); 
interstitialAd.loadAd(POSITION_ID, new InterstitialAd.InterstitialAdLoadListener() {
    @Override
    public void onAdLoadSuccess() {
        //广告请求成功
    }
    
    @Override
    public void onAdLoadFailed(int errorCode, String errorMsg) {
        //广告请求失败
    }
});

展示广告

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

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

xxxxxxxxxx
interstitialAd.destroy();

相关接口

xxxxxxxxxx
/**
 * 广告请求监听listener
 * 正常情况下，onAdRequestSuccess()和onAdLoadSuccess()会先后回调，回调onAdLoadSuccess()之后，调用show()方法展示广告，详见demo
 */
public interface InterstitialAdLoadListener {
    void onAdLoadSuccess(); //广告加载（缓存）成功
    void onAdRequestSuccess(); //广告请求成功
    void onAdLoadFailed(int errorCode, String errorMsg); // 广告请求失败
}

/**
 * 广告行为监听listener
 */
public interface InterstitialAdInteractionListener {
    void onAdClick(); // 广告被点击
    void onAdShow(); // 广告展示
    void onAdClosed(); // 广告关闭
    void onRenderFail(int code, String msg); // 广告渲染失败
    
    //视频广告会收到下面的回调
    void onVideoStart();//视频开始播放
    void onVideoPause();//视频暂停
    void onVideoResume();
    void onVideoEnd();
}

3、激励视频广告

请求广告

xxxxxxxxxx
RewardVideoAd rewardVideoAd = new RewardVideoAd();
rewardVideoAd.loadAd(PORTRAIT_POS_ID, new RewardVideoAd.RewardVideoLoadListener() {
    @Override
    public void onAdRequestSuccess() {
        //广告网络请求成功
    }

    @Override
    public void onAdLoadSuccess() {
        //广告素材缓存成功，可调用show展示广告
    }
    
    @Override
    public void onAdLoadFailed(int errorCode, String errorMsg) {
        //广告加载失败
    }
});

展示广告

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

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

xxxxxxxxxx
rewardVideoAd.recycle();

相关接口

xxxxxxxxxx
/**
 * 广告请求监听listener
 */
public interface RewardVideoLoadListener {
    void onAdRequestSuccess(); //请求广告成功，服务端成功返回广告
    void onAdLoadSuccess(); //请求广告成功，且素材缓存成功
    void onAdLoadFailed(int errorCode, String errorMsg); // 请求广告失败
}
// 正常情况下，onAdRequestSuccess()和onAdLoadSuccess()会先后回调，回调onAdLoadSuccess()之后，调用show()方法展示广告，详见demo

/**
 * 广告行为监听listener
 */
public interface RewardVideoInteractionListener {
    void onAdPresent(); // 广告被曝光
    void onAdClick(); // 广告被点击
    void onAdDismissed(); // 广告消失
    void onAdFailed(String message); // 渲染失败
    void onVideoStart(); // 视频开始播放
    void onVideoPause(); // 视频暂停
    void onVideoComplete(); // 视频播放完成
    void onVideoSkip(); // 跳过视频播放
    void onPicAdEnd(); // 图片类型广告播放完成
    void onReward(); //激励回调
}

4、开屏广告

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

加载并展示广告

xxxxxxxxxx
//初始化广告
SplashAd splashAd = new SplashAd();

/**
 * 请求并展示广告
 *
 * @param container        装载广告的容器
 * @param upId             POSITION_ID 广告位id
 * @param splashAdListener 广告监听listener
 */
splashAd.loadAndShow(mContainer, POSITION_ID, mSplashAdListener);

销毁广告

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

相关接口

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

5、原生模板广告

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

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

请求广告

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

展示广告

xxxxxxxxxx
templateAd.show(mContainer, mTemplateAdInteractionListener);

销毁广告

xxxxxxxxxx
templateAd.destroy();

相关接口

xxxxxxxxxx
/**
 * 广告请求监听listener
 */
public interface TemplateAdLoadListener {
    void onAdLoaded(); // 加载成功
    void onAdLoadFailed(int errorCode, String errorMessage); // 加载失败
}

/**
 * 广告行为监听listener
 */
public interface TemplateAdInteractionListener {
    void onAdShow(); // 广告展示
    void onAdClick(); // 广告被点击
    void onAdDismissed(); // 广告消失
    void onAdRenderFailed(int errorCode, String errorMsg); // 广告渲染失败
}

6、原生自渲染广告

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

请求广告

xxxxxxxxxx
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) {
  // 请求广告失败
}
})

广告数据对象接口说明

xxxxxxxxxx
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 组图
// NativeAdData.AD_STYLE_VIDEO 视频
// NativeAdData.AD_STYLE_IMAGE_AND_VIDEO 图片和视频
int getAdStyle();
String getVideoUrl(); //视频地址

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

xxxxxxxxxx
mNativeAd.destroy();

相关接口

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

7、原生视频

请求广告

xxxxxxxxxx
FeedAd feedAd = new FeedAd();
feedAd.load(POS_ID, new FeedAd.FeedLoadListener() {
    @Override
    public void onAdResourceCached() {
        //资源缓存成功，可调用show()展示广告
    }

    @Override
    public void onAdRequestSuccess() {
        //网络请求成功
    }

    @Override
    public void onAdLoadFailed(int errorCode, String errorMessage) {
        //广告加载失败
    }
});

注册广告行为监听

xxxxxxxxxx
mFeedAd.registerInteraction(mContext, container, new FeedAd.FeedInteractionListener() {
            @Override
            public void onAdShow() {
                //广告展示
            }

            @Override
            public void onAdClick() {
                //广告被点击
            }

            @Override
            public void onAdClosed() {
                //广告被关闭
            }

            @Override
            public void onRenderFail(int errorCode, String message) {
                //广告渲染失败
            }

            @Override
            public void onVideoStart() {
                //视频开始播放
            }

            @Override
            public void onVideoPause() {
                //视频暂停
            }

            @Override
            public void onVideoResume() {
                //视频恢复播放
            }
        });

registerInteraction方法及参数说明

xxxxxxxxxx
/**
 * 注册广告行为监听
 *
 * @param activity                广告所在界面的activity
 * @param container               广告view的父容器
 * @param feedInteractionListener 广告行为listener
 */
 registerInteraction(Activity activity, ViewGroup container,
            FeedAd.FeedInteractionListener feedInteractionListener) 

获取广告视图

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

销毁广告

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

xxxxxxxxxx
feedAd.destroy();

控制是否静音播放

xxxxxxxxxx
feedAd.setMutePlay(mutePlay)

8、个性化推荐广告开关设置

注意：默认为打开个性化推荐广告开关，此设置是时时生效，可以在任何地方设置

1、打开个性化推荐广告

MimoSdk.setPersonalizedAdEnabled(true);

2、关闭个性化推荐广告

MimoSdk.setPersonalizedAdEnabled(false);

五、SDK调试

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

测试使用的appid：2882303761517518052

六、错误码

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

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

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

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

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

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

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

如有个人信息查询或删除等要求也可以发邮件到mi-ssp@xiaomi.com