优盟广告 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 广告位尺寸高度错误