SDK V3.3.1对接文档


1. 当贝点金SDK集成指南

1.1 注册AppKey

集成当贝点金广告SDK之前,您首先需要到当贝点金官网注册并且添加新应用,获取appKey/appSecret

特别提醒:我们建议开发者在注册账号时使用企业邮箱,避免使用个人邮箱注册,防止由于人员流动带来的问题,建议使用的账号形式 :znds@企业域名、apps@企业域名、dev@企业域名。

1.2 快速集成

1.2.1 Android Studio

首先在build.gradle中添加当贝点金广告依赖,最新版本请点这里查看

  1. dependencies {
  2. compile 'com.dangbei:sdk-euthenia:3.2.7'
  3. }

如果无法正常集成请添加如下代码 :

  1. allprojects {
  2. repositories {
  3. mavenCentral()
  4. }
  5. }

同步Gradle。

如果你的so文件配置不是支持全部的ABI指令集的话,请根据实际情况过滤。例如只支持armeabi ,armeabi-v7a,在build.gradle添加如下代码 :

  1. android {
  2. defaultConfig {
  3. ndk {
  4. abiFilters "armeabi" ,"armeabi-v7a"
  5. }
  6. }
  7. }

同步Gradle。

1.2.2 Eclipse

  1. 进入这里下载aar文件到本地。

  2. 解压aar文件,如有必要修改aar后缀为zip后进行解压。

  3. classes.jar重命名为euthenia-sdk-{版本号}.jar,并加入到您项目的classPath下。

  4. 拷贝assets目录下的文件到您项目中的assets目录下。

  5. 拷贝(根据实际情况拷贝so文件,确保项目本身支持ABI指令集的目录,他们的so文件数据量一致jni目录下的文件到您项目中的jni相关目录(默认为libs目录)。

1.2.3 修改AndroidManifest.xml

打开AndroidManifest.xml,添加如下代码:

  1. <manifest ...>
  2. <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  3. <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  4. <uses-permission android:name="android.permission.INTERNET"/>
  5. <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  6. <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  7. </manifest>
  1. <application ...>
  2. <receiver android:name="com.dangbei.euthenia.receiver.NetworkChangeReceiver">
  3. <intent-filter>
  4. <action android:name="android.net.conn.CONNECTIVITY_CHANGE"/>
  5. </intent-filter>
  6. </receiver>
  7. //添加渠道配置
  8. //DangbeiAdManager.init(this, APPKEY, APP_SECRET);初始化调用此方法,则必须配置渠道
  9. <meta-data android:value="znds" android:name="euthenia_channel"/>
  10. </application>

1.2.3.1 权限说明

所需权限 是否必须 用途
INTERNET 允许应用程序联网,以便向我们的服务器端发送数据
ACCESS_NETWORK_STATE 检测联网方式,区分用户设备使用的是2G、3G或是WiFi
ACCESS_WIFI_STATE 获取用户设备的mac地址,我们会将mac地址作为用户的唯一标识
WRITE_EXTERNAL_STORAGE 写入sd卡的权限
READ_EXTERNAL_STORAGE 读取sd卡信息的权限

1.2.4 混淆相关配置

  1. -keep class com.dangbei.euthenia.**{*;}

1.2.5 初始化

使用后台申请的Appkey/AppSecretApplication::onCreate()处进行初始化,如下:

  1. DangbeiAdManager.init(this, APPKEY, APP_SECRET, CHANNEL);
  1. DangbeiAdManager.init(this, APPKEY, APP_SECRET);
  1. DangbeiAdManager.init(this, APPKEY, APP_SECRET, CHANNEL, ProcessName);

支持channel字段在代码中写入或者在manifest中写入。

ProcessName为app允许初始化及展示广告的进程,不传默认只支持主进程。

1.2.6 展示一个广告

在某个Activity中,使用如下代码展示一个启动页广告:

  1. IAdContainer adContainer = DangbeiAdManager.getInstance().createSplashAdContainer(this);
  2. //注意非空判断,极端情况下会返回空
  3. if(adContainer != null){
  4. adContainer.open();
  5. }

新增adContainer.openedNoRemove()方法,与.open()方法的区别在于,openedNoRemove()方法在sdk中不会进行资源回收,开发者可以通过finish闪屏页面进行资源回收。

1.2.7 示例代码下载

更多的接入细节,可以参照demo代码,点击下载

1.3 支持的广告类型

1.3.1 闪屏启动广告(createSplashAdContainer)

闪屏广告类型,在应用启动时调用展示,闪屏广告显示逻辑如下:

1.3.2 屏保广告(createScreenSaverAdContainer)

屏保广告显示逻辑如下:

1.3.3 视频贴片广告(createVideoPreAdContainer)

视频贴片广告类型,在播放视频之前展示,可放大缩小播放窗口,广告显示逻辑如下:

1.3.4 视频暂停广告(createVideoPauseAdContainer)

视频暂停广告类型,在播放视频暂停时展示,广告显示逻辑如下:

  1. 填充ParentView
  2. 支持图片,gif,视频没有倒计时显示
  3. 调用open()显示广告,调用close()关闭广告

1.3.5 视频角标广告(createVideoFloatAdContainer)

弹窗广告类型,在应用使用的时候弹出展示,广告显示逻辑如下:

  1. 填充ParentView
  2. 支持图片,gif类型,后台配置展示时长。
  3. 设置角标位置,支持左上、左下、右下、右上四种位置的配置,默认为右下角,示例代码如下:
    adContainer.setAdContainerAlign(AdContainerAlign.LEFT_TOP);
  4. 调用open方法时广告弹出弹出,尺寸一般为素材的像素大小,最大不超过屏幕的四分之一面积

1.4 SDK API

1.4.1 初始化广告

该api只需在ApplicationonCreate方法中调用一次。

  1. DangbeiAdManager.init(context, APPKEY, APP_SECRET, CHANNEL);

1.4.2 创建广告容器

在展示广告前需要创建一个广告容器

  1. IAdContainer adContainer = DangbeiAdManager.getInstance().createSplashAdContainer(context);

1.4.3 打开广告

  1. void open();
  2. or
  3. void openedNoRemove();

创建完广告后,再调用adContainer.open()方法即可展示广告。

注意: 一个容器最多只能展示一次广告,也就是说,open()方法只能被调用一次,否则会抛出EutheniaException "The AdContainer CAN NOT be reused, please create a new AdContainer instance."

1.4.4 关闭广告

  1. void close();

开发者可以手动调用此方法来关闭广告,目前只有视频暂停广告视频贴片广告支持开发这手动关闭广告,否则将会抛出EutheniaException 暂不支持此方法

1.4.5 设置parentView

  1. void setParentView(ViewGroup parentView);

创建完广告后,调用adContainer.setParentView()方法设置广view的父view,目前只有视频暂停广告视频贴片广告视频贴片广告支持设置,否则将会抛出EutheniaException 暂不支持此方法

1.4.6 变化adContainer大小

  1. void resize();

展示广告过程中,如果parentView的大小改变,调用adContainer.resize()方法来刷新广告adContainer的大小,目前只有视频贴片广告支持设置,否则将会抛出EutheniaException 暂不支持此方法

1.4.7 广告是否正在展示

  1. boolean isDisplaying();

创建完广告后或者调用open()方法以后,可以调用adContainer.isDisplaying()方法来判断广告是否正在展示中。

1.4.8 广告是否尚未展示

  1. boolean isBeforeDisplaying();

从创建完广告后,到调用open()方法,最后展示出广告有个过程,可以通过调用adContainer.isBeforeDisplaying()方法来判断广告是否在展示之前。

1.4.9 增加广告展示状态监听

开发者可以监听一个广告展示过程的状态,可以在相应的回调方法中进行各自的处理

  1. void setOnAdDisplayListener(@Nullable OnAdDisplayListener onAdDisplayListener);

OnAdDisplayListener支持的状态回调如下:

  1. public interface OnAdDisplayListener {
  2. @MainThread
  3. void onDisplaying();
  4. @MainThread
  5. void onFailed(Throwable throwable);
  6. @MainThread
  7. void onFinished();
  8. @MainThread
  9. void onClosed();
  10. @MainThread
  11. void onTerminated();
  12. @MainThread
  13. void onSkipped();
  14. @MainThread
  15. void onTriggered();

注意: 以上7种状态回调中,除onDisplaying()以外,其他方法都是广告的最终状态。所有的回调方法都运行在MainThread
在一次广告展示过程中,onFailedonFinishedonClosedonTerminatedonSkippedonTriggered这几个方法有且只有一个方法会被回调。

1.4.9.1 onDisplaying

当广告一旦处于展示中,此方法会被回调。

1.4.9.2 onFailed

当广告展示过程失败时会被回调。这里的失败的可能性如下:

开发者可以通过打印这个方法的Throwable来判断广告展示失败的原因。

1.4.9.3 onFinished

如果该广告设置了展示n秒后自动关闭,当广告正常展示n秒后,广告结束,此方法就会被调用。

1.4.9.4 onClosed

如果该广告展示过程中被用户手动关闭(开发者调用了close方法显式地关闭了广告),此方法就会被调用。

1.4.9.5 onTerminated

如果在广告展示过程中,Activity被用户关闭(比如用户按了返回键使得Activity:onDestroy了等等),则认为广告被终止,此方法会被调用。

1.4.9.6 onSkipped

某些广告支持在展示n秒之后允许用户跳过广告,当用户按了“跳过”之后,广告展示结束,此方法就会被回调。

1.4.9.7 onTriggered

CPC类型的广告,支持用户点击触发广告,跳转到其他页面(其他App、H5页面等等),广告展示结束,此方法就会被回调。

1.5 技术支持

智能电视网

联系客服:联系客服

Email:support@znds.com

☺为了能够尽快响应您的反馈,请提供您的appkey及logcat中的详细出错日志,您所提供的内容越详细越有助于我们帮您解决问题。

1.6 FAQ

Q 01. 打开广告时抛出EutheniaException "The AdContainer CAN NOT be reused, please create a new AdContainer instance."异常?

A 01. 同一个AdContainer对象只能打开一次广告,也就是说,open()方法只能被调用一次。如果需要再次展示广告,则需要重新创建AdContainer


Q 02. 集成测试的时候一直无法出现广告?

A 02. 请确定后台正确的创建了测试广告。


Q 03. 集成测试的时候,后台已经创建了广告,还是一直无法出现广告?

A 03. 请确定集成设备的时间是否是网络时间。


Q 04. 抛出---Query local available ad placements EMPTY!--->异常,不展示是因为?

A 04. 本地数据库中无可用广告。

请确认:

1、后台配置广告媒体与接入apk是否为同一个;

2、当前时间(设备的系统时间)是否在配置广告的展示周期中;

3、配置的广告是否有设置频控;

4、配置的广告是否有每日展示次数上限,是否已达上限;


1.7 接口返回值查询

code msg 说明
200 success 成功
201 param is error 请求参数错误
202 request expired 请求超时
203 package is not matched 包名不匹配
204 shielded request 应用不可用
205 channel is null 渠道为空
206 unsupported version 不支持版本
207 request format error 请求格式错误
208 advalidate is null advalidate为空
209 adids is null adids为空
210 trick mode 频繁请求
211 validate error 验证错误
212 No So File Loaded so库缺失
500 internal server error 接口异常