优盟广告 Android SDK用户指导手册 v1.1.5.0

1 简介

本指导手册针对玩咖旗下优盟广告Android SDK v1.1.5.0版本,如有疑问请联系 QQ：372797035

邮箱：fengzhanao@gm825.com

2 阅读对象

本文档面向所有使用玩咖优盟广告Android SDK的Android开发人员、测试人员、合作伙伴以及对此感兴趣的其他用户，由此产生的广告收入进行合作分配。

3 核心功能清单

本章只罗列出优盟广告Android SDK对App提供的核心功能清单，详细调用方法见第4章。 开屏广告接入

插屏广告接入

Banner接入

原生接入

激励视频广告接入

4 使用UM Android SDK开发应用(重要)

我们提供了样例代码，指导合作方如何集成广告SDK.

4.1 添加jar包到Android工程libs下(非常重要)

4.2 配置 权限配置

接入任意广告(Banner、开屏、插屏、原生)都需要在XML中添加以下声明：

注意事项：

确保所使用的android-support-v4.jar包中的android.support.v4.app.NotificationCompat.Builder类包含setProgress方法，如果不包含此方法请升级android开发套件 Android 6.0适配

如果您打包App时的targetSdkVersion >= 23：请在先获取到SDK要求的所有权限，然后再调用SDK的广告接口。否则SDK将无法工作，我们建议您在App启动时就去获取SDK需要的权限，需要代码手动申请的权限有:

android7.0适配

targetSDKVersion >= 24时的文件访问兼容处理 如果您打包时的targetSDKVersion >= 24，为了让SDK能够正常下载、安装App类广告，必须按照下面的步骤做兼容性处理。注意：如果您的targetSDKVersion < 24，不需要做这个兼容处理。

(1)在AndroidManifest.xml中的Application标签中添加provider标签，接入代码如下所示：

android:name="android.support.v4.content.FileProvider"

android:authorities="${applicationId}.fileprovider"

android:exported="false"

android:grantUriPermissions="true">

android:name="android.support.FILE_PROVIDER_PATHS"

android:resource="@xml/file_paths"/>

需要注意的是provider的authorities值为${applicationId}.fileprovider，对于每一个开发者而言，这个值都是不同的，${applicationId}在代码中和Context.getPackageName()值相等，是应用的唯一id。例如Demo示例工程中的applicationId为"com.huanju.fs.demo"。

(2)在项目结构下的res目录下添加一个xml文件夹，再新建一个file_paths.xml的文件，文件内容如下：

name="ssp_download_path" path="" />

name="external_files_path"

path="Download"/>

android8.0适配

如果您打包App时的targetSdkVersion >= 26：需要在AndroidManifest.xml增加权限声明android.permission.REQUESTINSTALLPACKAGES，详情见前面添加权限声明部分。

适配下载与安装功能

为了适配下载和安装相关功能，在工程中引用的包 com.android.support:support-v4:24.2.0

使用24.2.0以及以上版本。

代码混淆

代码混淆 如果您需要使用proguard混淆代码，需确保不要混淆SDK的代码和support-v4和support-v7。请在proguard.cfg文件(或其他混淆文件)尾部添加如下配置：

-ignorewarnings

-keep class com.huanju.ssp.** {

public protected *;

}

-keep class android.support.v4.**{

public *;

}

-keep class android.support.v7.**{

public *;

}

-keep class com.qq.e.** {

public protected *;

}

-keep class com.huanju.fs.** {

public protected *;

}

-keep class com.youdao.sdk.** { *;}

-keepclassmembers class * extends android.app.Activity {

public void *(android.view.View);

}

-keepclassmembers enum * {

public static **[] values();

public static ** valueOf(java.lang.String);

}

-keep class com.baidu.mobads.*.** { *; }

-keep class com.bytedance.sdk.openadsdk.** { *; }

-keep class com.androidquery.callback.** {*;}

-keep public interface com.bytedance.sdk.openadsdk.downloadnew.** {*;}

4.3 Listener及返回参数明细

> 4.3.1 HjAdListener 通用广告回调监听 - void onAdError(String msg,int code) ; 广告加载失败

- void onDisplayAd();广告展示时回调

- void onClickAd();广告被点击

- void onCloseAd();广告被关闭

- void onAdReady();广告加载完毕

> 4.3.2 HjNativeAdListener 原生广告回调监听 - void onAdError(String msg, int code); 广告展示失败(主线程回调)

* String msg 错误信息

* int code 错误码(详情见附件)

- void onADLoaded(List parseData);广告数据返回(主线程回调)

* List parseData 广告数据对象的集合

> 4.3.3 HjSpalshAdListener 开屏广告回调监听 - void onAdError(String msg,int code) ; 广告加载失败

- void onDisplayAd();广告展示时回调

- void onClickAd();广告被点击

- void onCloseAd();广告被关闭

4.4 调用API

> 4.4.1 SDK初始化 接口描述：

建议在APP的自定义application类调用API接口。

注意：在此方法之前调用任何本sdk相关api，将报运行时异常。

调用接口：

HjAdClient.init(Context context,String app_id);

输入参数：

context 上下文

appid appid为在我广告平台注册app时自动生成，唯一识别app

> 4.4.2 开屏广告接入

//1.当前Acitivity;2.需要跳转到的Acitivity;3.广告位id.

splashAd = new HjSplashAd(this, MainActivity.class, adSlotId);

//设置加载失败是否自动跳转至目标界面.

splashAd.setIsJumpTargetWhenFail(true)

splashAd.setAdListener(new HjSpalshAdListener() {

@Override

public void onDisplayAd() {

Log.e("SplashActivity","onDisplayAd");

}

@Override

public void onClickAd() {

Log.e("SplashActivity","onClickAd");

}

@Override

public void onCloseAd() {

Log.e("SplashActivity","onCloseAd");

}

@Override

public void onAdError(String msg, int code) {

Log.e("SplashActivity","onAdError");

}

});

splashAd.showSplashAd();

/**

* 开屏页一定要禁止用户对返回按钮的控制，否则将可能导致用户手动退出了App而广告无法正常曝光和计费

*/

@Override

public boolean onKeyDown(int keyCode, KeyEvent event) {

if (keyCode == KeyEvent.KEYCODE_BACK || keyCode == KeyEvent.KEYCODE_HOME) {

return true;

}

return super.onKeyDown(keyCode, event);

}

@Override

protected void onPause() {

super.onPause();

splashAd.onPause();

}

@Override

protected void onResume() {

super.onResume();

splashAd.onResume();

}

> 4.4.3 插屏广告接入

private void build() {

insertAd = new HjInsertAd(this, AdSetting.getInsertID());

insertAd.setAdListener(new HjAdListener() {

@Override

public void onDisplayAd() {

Log.e(TAG, "onDisplayAd");

}

@Override

public void onClickAd() {

Log.e(TAG, "onClickAd");

}

@Override

public void onCloseAd() {

Log.e(TAG, "onCloseAd");

}

@Override

public void onAdReady() {

Log.e(TAG, "onAdReady");

//广告返回,直接展示,或者宿主自己控制展示.

//showAd();

}

@Override

public void onAdError(String msg, int code) {

Log.e(TAG, "onAdError msg:" + msg + " code: " + code);

}

});

}

private void loadAd() {

if (insertAd != null) {

insertAd.loadAd();

}

}

private void showAd() {

if (insertAd != null) {

insertAd.show();

}

}

@Override

protected void onDestroy() {

if (insertAd != null) {

insertAd.destroy();

}

super.onDestroy();

}

> 4.4.4 Banner接入

HjBannerAd hjBannerAd = new HjBannerAd(this, adSlotId);

hjBannerAd.setCloseBtnVisible(true); //设置是否展示关闭按钮

hjBannerAd.setADListener(new HjAdListener() {

@Override

public void onDisplayAd() {

Log.d(TAG, "onDisplayAd");

}

@Override

public void onClickAd() {

Log.e(TAG, "onClickAd");

}

@Override

public void onCloseAd() {

Log.e(TAG, "onCloseAd");

}

@Override

public void onAdReady() {

Log.e(TAG, "onAdReady");

}

@Override

public void onAdError(String msg) {

Log.e(TAG, "onAdError" );

}

});

FrameLayout layout = hjBannerAd.getAdView();

//判断是否可以加载广告

if (hjBannerAd.loadAd()) {

FrameLayout layout = hjBannerAd.getAdView();

bannerContainer.addView(layout);

}

> 4.4.5 原生广告接入 请求原生广告 (具体使用方式见demo)

HjNativeAd nativeAd = new HjNativeAd(this, adSlotId);

nativeAd.setListener(new HjNativeAdListener() {

@Override

public void onADLoaded(List response) {

adapter.notifyDataSetChanged(response, isLoadMore);

}

@Override

public void onADError(String errorMsg, int errorCode) {

}

});

nativeAd.loadData(); 当用户点击广告,需要调用handlerClick方法,当用户关闭广告,需要调用handlerClose方法

v.setOnClickListener(new View.OnClickListener() {

@Override

public void onClick(View v) {

nativeResponse.handlerClick(v);

}

});

holder.iv_close.setOnClickListener(new View.OnClickListener() {

@Override

public void onClick(View view) {

item.handleClose();

}

}); HjNativeAdDataRef 提供的方法

getType(): 获取图文类型,共4种,分别是3小图;1大图,1小图,双图(一小一大).

bindingTitle(int titleId):绑定标题的控件id.

bindingDesc(int descId): 绑定内容控件id.

bindingImg3(int[] images3): 绑定三张大图.

bindingImgBig(int imageBigId)

bindingImgSmall(int imageSmallId)

recordImpression(View nativeView):当界面曝光的时候调用.调用该函数时确保视图已经被加载，勿漏

handlerClick(View nativeView):绑定点击事件.需要在recordImpression()方法调用后才能调用

handleClose(); 当原生广告被关闭的时候调用.

isApp():判断是否为app类的广告.

> 4.4.6 激励视频广告

(具体使用方式见demo)

(1) 添加视频配置文件

android:name="com.youdao.sdk.common.YouDaoBrowser"

android:configChanges="keyboardHidden|orientation|screenSize"

android:launchMode="singleTask" />

android:name="com.youdao.sdk.video.YouDaoVideoActivity"

android:launchMode="singleTask"

android:hardwareAccelerated="true"

android:configChanges="keyboardHidden|orientation|screenSize" >

android:name="com.youdao.sdk.common.YouDaoAppService"

android:enabled="true" >

android:name="com.baidu.mobads.AppActivity"

android:configChanges="screenSize|keyboard|keyboardHidden|orientation"

android:theme="@android:style/Theme.Translucent.NoTitleBar" />

android:name="com.baidu.mobads.production.rewardvideo.MobRewardVideoActivity"

android:configChanges="screenSize|orientation|keyboardHidden"

android:launchMode="singleTask"

android:theme="@android:style/Theme.Translucent.NoTitleBar" >

android:name="com.youdao.sdk.extra.common.AdDownloadProvider"

android:authorities="${applicationId}.youdaosdk"

android:exported="false"

android:grantUriPermissions="true" >

android:name="android.support.FILE_PROVIDER_PATHS"

android:resource="@xml/file_paths" />

android:name="com.baidu.mobads.openad.FileProvider"

android:authorities="${applicationId}.bd.provider"

android:exported="false"

android:grantUriPermissions="true">

android:name="android.support.FILE_PROVIDER_PATHS"

android:resource="@xml/file_paths" />

android:name="com.qq.e.ads.PortraitADActivity"

android:screenOrientation="portrait"

android:configChanges="keyboard|keyboardHidden|orientation|screenSize" />

android:name="com.qq.e.ads.LandscapeADActivity"

android:screenOrientation="landscape"

android:configChanges="keyboard|keyboardHidden|orientation|screenSize" />

android:name="com.bytedance.sdk.openadsdk.TTFileProvider"

android:authorities="${applicationId}.TTFileProvider"

android:exported="false"

android:grantUriPermissions="true">

android:name="android.support.FILE_PROVIDER_PATHS"

android:resource="@xml/file_paths" />

android:name="com.bytedance.sdk.openadsdk.multipro.TTMultiProvider"

android:authorities="${applicationId}.TTMultiProvider"

android:exported="false" />

android:name="com.bytedance.sdk.openadsdk.activity.TTLandingPageActivity"

android:configChanges="keyboardHidden|orientation|screenSize"

android:launchMode="singleTask" />

android:name="com.bytedance.sdk.openadsdk.activity.TTVideoLandingPageActivity"

android:configChanges="keyboardHidden|orientation|screenSize"

android:launchMode="singleTask" />

android:name="com.bytedance.sdk.openadsdk.activity.TTRewardVideoActivity"

android:configChanges="keyboardHidden|orientation|screenSize"

android:launchMode="singleTask" />

android:name="com.bytedance.sdk.openadsdk.activity.TTFullScreenVideoActivity"

android:configChanges="keyboardHidden|orientation|screenSize"

android:launchMode="singleTask" />

android:name="com.bytedance.sdk.openadsdk.activity.TTDelegateActivity"

android:launchMode="singleTask"

android:theme="@android:style/Theme.Translucent.NoTitleBar" />

android:name="com.ss.android.socialbase.downloader.downloader.IndependentProcessDownloadService"

android:process=":downloader" >

android:name="com.ss.android.socialbase.appdownloader.view.DownloadSizeLimitActivity"

android:launchMode="singleTask"

android:theme="@android:style/Theme.Dialog" />

android:name="com.ss.android.socialbase.appdownloader.view.DownloadTaskDeleteActivity"

android:launchMode="singleTask"

android:theme="@android:style/Theme.Dialog" />

android:name="com.ss.android.downloadlib.activity.InteractionMiddleActivity"

android:launchMode="standard" />

将资源文件夹中的资源拷贝到项目中去.

若目标版本大于android 7.0 需要在xml中的file_paths.xml 确保

name="external_files_path"

path="Download"/>

(2) 创建视频广告,

mHjVideoAd = new HjVideoAd(AdSetting.getRewardID(), RewardVideoActivity.this, new HjVideolistener() {

//没有广告返回或者网络有问题,导致请求失败.需要重新请求.

@Override

public void onFail() {

Log.e(TAG, "onFail");

}

//当广告可以展示后,会回调此方法,何时展示由开发者自行决定.

@Override

public void onSuccess() {

Log.e(TAG, "onSuccess");

if (mHjVideoAd != null) {

if (mHjVideoAd.isReady()) {

mHjVideoAd.show();

}

}

}

@Override

public void onAdShow() {

Log.e(TAG, "onAdShow");

}

//广告关闭,可以重新load下一条广告,一般4-5次

@Override

public void onAdClose() {

Log.e(TAG, "onAdClose");

}

@Override

public void onAdClick() {

Log.e(TAG, "onAdClick");

}

//视频缓存失败或者播放失败走此处回调,重新请求一般4-5次即可

@Override

public void onAdFailed(String msg) {

Log.e(TAG, "onAdFailed: " + msg);

}

//播放完成回调,一般在此处给奖励

@Override

public void onPlayEnd() {

Log.e(TAG, "onPlayEnd");

}

});

(3) 加载激励视频

mHjVideoAd.loadAd();

(4) 播放激励视频

if (mHjVideoAd.isReady()) {

mHjVideoAd.show();

}

(5) onPause(),onResume(),onDestroy()的调用见demo.

(6) 激励设置

视频播放完成之后会回调onPlayEnd，开发者可在此方法中给用户激励。

(7) 混淆文件的配置

确认混淆文件配置包含以下,否则可能打包失败

-ignorewarnings

-keep class com.youdao.sdk.** { *;}

-keepclassmembers class * extends android.app.Activity {

public void *(android.view.View);

}

-keepclassmembers enum * {

public static **[] values();

public static ** valueOf(java.lang.String);

}

-keep class com.baidu.mobads.*.** { *; }

-keep class com.bytedance.sdk.openadsdk.** {*;}

-keep class com.androidquery.callback.** {*;}

-keep public interface com.bytedance.sdk.openadsdk.downloadnew.** {*;}

(8)注意事项:

1.由于视频广告比较大,所以建议用户最好提前load,否则当用户触发激励条件的时候再去load有可能没有广告返回或者加载等待时间较长.

2.只有在此次播放完成后才能进行下次视频的缓存播放.每次使用前需要重新new HjVideoAd.

3.如果load失败,最多重试4-5次

> 4.4.7 退出app时调用 接口描述

建议app退出的出口处调用。

调用接口

HjAdClient.onDestroy()

附件 错误码对照表 本地错误 -1 程序异常

-2 广告请求超时

-3 广告渲染超时

-4 广告渲染失败

-5 广告展示失败

-6 广告位与展示广告信息不符

-7 原生广告列表为空

-1280 无网络

系统错误 0 NO_ERROR 请求响应无错误

1 INTERNAL_ERROR 系统内部错误

2 PARAM_ERROR 参数错误

3 API_UNSUPPORTED 不支持的API

4 ABOLITION_API 废除的API

5 VERIFICATION_FAILURE 验证失效

6 NO_CONTENT 无内容

7 ANTI_CHEATING 防刷策略

8 LOWER_SDK_VERSION SDK版本过低

公共参数错误 50 MISSING_SVR SDK版本号缺失

51 MISSING_DEVICE 设备名缺失

52 MISSING_CUID 用户ID缺失

53 MISSING_CLIENT_ID 客户端ID缺失

54 MISSING_DEVICE_ID 设备ID缺失

请求ID信息错误 100000 ERROR_FORMAT_REQUEST 请求数据格式错误

API版本信息错误 102000 MISSING_API_VERSION 使用API版本信息缺失

102010 ERROR_API_FORMAT API格式不正确

应用信息错误

103000 MISSING_APP_INFO 应用信息缺失

103010 MISSING_APP_ID 应用ID 信息缺失

103011 ERROR_APP_ID 应用ID 信息错误，DAP 未收录

103012 DISABLED_APP_ID 应用ID 无效，DAP 上未生效

103020 ERROR_CHANNEL_ID 渠道ID 信息错误

103030 MISSING_APP_VERSION 应用版本信息缺失

103031 ERROR_APP_VERSION 应用版本信息错误 设备信息错误

104000 MISSING_DEVICE_INFO 设备信息缺失

104010 MISSING_DEVICE_TYPE 设备类型信息缺失

104011 ERROR_DEVICE_TYPE 设备类型信息错误

104020 MISSING_OS_TYPE 操作系统信息缺失

104021 ERROR_OS_TYPE 操作系统信息错误

104030 MISSING_OS_VERSION 操作系统版本信息缺失

104031 ERROR_OS_VERSION 操作系统版本信息错误

104050 MISSING_VENDOR 厂商信息缺失

104060 MISSING_MODEL 设备型号信息缺失

104070 MISSING_ANDROID_ID android id 缺失

104071 ERROR__ANDROID_ID android id 错误

104080 MISSING_IMEI imei号缺失

104081 MISSING_IMEI_MD5 imei_md5缺失

104082 ERROR_IMEI imei号错误

104083 ERROR_IMEI_MD5 imei_md5错误

104090 MISSING_MAC mac信息缺失

104091 ERROR_MAC mac信息格式错误

104100 MISSING_SCREEN_SIZE_WIDTH 设备屏幕尺寸宽度缺失

104110 MISSING_SCREEN_SIZE_HEIGHT 设备屏幕尺寸高度缺失 网络环境信息错误

105000 MISSING_NETWORK_INFO 网络环境信息缺失

105010 MISSING_IPV4 网络地址信息缺失

105011 ERROR_FORMAT_IPV4 网络地址信息格式错误

105020 MISSING_CONNECTION_TYPE 网络连接类型缺失

105021 ERROR_CONNECTION_TYPE 网络连接类型错误

105030 MISSING_OPERATOR_TYPE 网络运营商类型缺失

105031 ERROR_CARRIER 运营商类型 GPS坐标信息错误

106000 MISSING_COORDINATE_TYPE 坐标类型信息缺失

106001 ERROR_COORDINATE_TYPE 坐标类型信息错误

106010 MISSING_LONGITUDE 经度信息缺失

106020 MISSING_LATITUDE 纬度信息缺失

106030 MISSING_GPS_TIMESTAMP 定位时间戳信息缺失 广告位信息错误

107000 MISSING_ADSLOT 广告位信息缺失

107010 MISSING_ADSLOT_ID 广告位ID 缺失

107011 ERROR_ADSLOT_ID 广告位ID 未收录

107012 DISABLED_ADSLOT_ID 广告位ID 未启用

107013 NOT_MATCH_ADSLOT_ID 广告位ID与AppID不匹配

107020 ERROR_ADSLOT_SIZE_WIDTH 广告位尺寸宽度错误

107030 ERROR_ADSLOT_SIZE_HEIGHT 广告位尺寸高度错误