1. 当贝点金SDK集成指南

1.1 注册AppKey

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

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

1.2 快速集成

1.2.1 Android Studio

1.进入这里下载aar文件，并加入到您项目的libs下。

2.进入这里下载相关必需jar包，并加入到您项目的libs下。

3.将相关aar包以及jar 添加依赖到您的项目下

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目录)。
6. 请拷贝res目录下的xml 目录到您项目中的res目录下。
7. 进入这里下载相关必需jar包，并加入到您项目的classPath下。
8. 确保项目中使用了RecyclerView。

1.2.3 修改AndroidManifest.xml

打开AndroidManifest.xml，添加如下代码：

<manifest ...>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
        //从广告版本3.3.5开始不再提供以下几个权限 有需要自行加上
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

<application ...>
    <receiver android:name="com.dangbei.euthenia.receiver.NetworkChangeReceiver">
      <intent-filter>
          <action android:name="android.net.conn.CONNECTIVITY_CHANGE"/>
      </intent-filter>
    </receiver>
    <receiver android:name="com.dangbei.euthenia.receiver.InstalledReceiver">
            <intent-filter>
                <action android:name="android.intent.action.PACKAGE_ADDED"/>
                <action android:name="android.intent.action.PACKAGE_REPLACED"/>
                <data android:scheme="package"/>
            </intent-filter>
        </receiver>
    //添加渠道配置
    //DangbeiAdManager.init(this, APPKEY, APP_SECRET);初始化调用此方法，则必须配置渠道
    <meta-data android:value="znds" android:name="euthenia_channel"/>
    
    //添加Fileprovider build.gradle中support版本使用v7，防止找不到类
    
 <provider
            android:name="com.dangbei.provider.DBFileProvider"
            android:authorities="${applicationId}.dbfileprovider"
            android:exported="false"
            android:grantUriPermissions="true">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/dbprovider_paths" />
</application>

为避免Provider冲突，广告新增自有DBFileProvider，务必严格按照上面要求配置，以免导致错误

//应用jar包不是aar包需要申明这个activity和service，引用aar包不需要
<activity
        android:name="com.dangbei.euthenia.ui.style.h5.H5Activity"
        android:screenOrientation="landscape"
        android:theme="@android:style/Theme.Translucent.NoTitleBar" />
​
<service android:name="com.ant.downloader.core.DownloadService" />

1.2.3.1 权限说明

注意：Android6.0以上需要动态获取权限，在广告展示时建议先判断是否有读写权限在进行展示广告的操作，避免权限问题导致广告展示失败，sdk中新增没有权限提示。3.3.8以后广告sdk不再对权限做处理，权限判断和动态申请权限开发者自行处理。

1.2.4 混淆相关配置

-keep class com.dangbei.euthenia.**{*;}
-keep class com.ant.downloader.**{*;}
-keep class com.j256.ormlite.**{*;}

3.3.7版本以后下载库有所修改，请使用在jar下载地址处下载新的jar包，并更新混淆配置

1.2.5 初始化

使用后台申请的Appkey/AppSecret在Application::onCreate()处进行初始化，如下：

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

DangbeiAdManager.init(this, APPKEY, APP_SECRET);

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

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

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

1.2.6 展示一个广告

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

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

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

1.2.7 示例代码下载

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

1.3 支持的广告类型

1.3.1 闪屏启动广告（createSplashAdContainer）

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

• 只支持全屏显示

• 支持图片，gif，视频且有倒计时显示(后台配置时长)

  

1.3.2 屏保广告（createScreenSaverAdContainer）

屏保广告显示逻辑如下：

• 只支持全屏显示

• 只支持图片展示，后台配置时长

• 按任意键退出广告

  

1.3.3 视频贴片广告（createVideoPreAdContainer）

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

• 填充ParentView，当ParentView大小变换，调用resize方法刷新UI

• 支持图片，gif，视频且有倒计时显示(后台配置时长)

  

1.3.4 视频暂停广告（createVideoPauseAdContainer）

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

• 填充ParentView

• 支持图片，gif，视频没有倒计时显示

• 调用open()显示广告，调用close()关闭广告

  

1.3.5 视频角标广告（createVideoFloatAdContainer）

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

• 填充ParentView

• 支持图片，gif类型，后台配置展示时长。

• 设置角标位置，支持左上、左下、右下、右上四种位置的配置，默认为右下角，示例代码如下： adContainer.setAdContainerAlign(AdContainerAlign.LEFT_TOP);

• 调用open方法时广告弹出弹出，尺寸一般为素材的像素大小，最大不超过屏幕的四分之一面积

  

1.3.6退出广告（createExitAdContainer）

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

• 按返回键退出应用时，请求接口，弹出退出推荐图
• 系统逻辑判断，如果点金没有退出广告展示计划，则按照应用自有广告逻辑展示

示例代码：

 public boolean dispatchKeyEvent(KeyEvent event) {
​
if (!DangbeiAdManager.getInstance().isExitShowing()
            && event.getAction() == KeyEvent.ACTION_DOWN
            && (event.getKeyCode() == KeyEvent.KEYCODE_BACK
            || event.getKeyCode() == KeyEvent.KEYCODE_ESCAPE)) {
        IAdContainer adContainer = DangbeiAdManager.getInstance().createExitAdContainer(this);
        adContainer.setOnAdDisplayListener(new OnAdDisplayListenerAdapter() {
​
            @Override
            public void onTriggered() {
            }
​
            @Override
            public void onSkipped() {
            }
​
            @Override
            public void onFinished() {
                finish();
​
            }
​
            @Override
            public void onClosed() {
            }
​
            @Override
            public void onTerminated() {
            }
​
            @Override
            public void onFailed(Throwable throwable) {
                super.onFailed(throwable);
                //正常退出逻辑
                Toast.makeText(getApplicationContext(),"正常退出",Toast.LENGTH_SHORT).show();
            }
        });
        adContainer.open(false);
        return false;
    }
    return super.dispatchKeyEvent(event);
}

1.3.7 退出广告新样式（createExitAdFullContainer）

退出广告类型，在调开发者退出页时创建：

• 新样式，提供广告view与推荐应用下载按钮

• 填充ParentView

• 调open方法调出广告

• 可在广告返回失败时走自有的退出逻辑

  

1.4 SDK API

1.4.1 初始化广告

该api只需在Application的onCreate方法中调用一次。

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

• context: 推荐使用applicationContext，不能为空。
• APPKEY: 在当贝点金官网申请的AppKey，不能为空。
• APP_SECRET: 在当贝点金官网申请的AppSecret，不能为空。
• CHANNEL: 渠道名称，可以使用任意字符串，不能为空。
• processName: 支持进程名，接入者所支持初始化及展示广告的进程，默认为只支持主进程。

1.4.2 创建广告容器

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

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

• context: 此处传入的 context 必须为Activity Context，不能使用Application Context。

1.4.3 打开广告

void open()
    or
void openedNoRemove();

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

注意: openedNoRemove()用于打开广告，结束后不移除view

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

1.4.4 关闭广告

void close();

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

1.4.5 设置parentView

void setParentView(ViewGroup parentView);

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

1.4.7 广告是否正在展示

boolean isDisplaying();

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

1.4.8 广告是否尚未展示

boolean isBeforeDisplaying();

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

1.4.9 增加广告展示状态监听

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

void setOnAdDisplayListener(@Nullable OnAdDisplayListener onAdDisplayListener);

OnAdDisplayListener支持的状态回调如下：

public interface OnAdDisplayListener {
    @MainThread
    void onFetch();
    @MainThread
    void onDisplaying();
    @MainThread
    void onFailed(Throwable throwable);
    @MainThread
    void onFinished();
    @MainThread
    void onClosed();
    @MainThread
    void onTerminated();
    @MainThread
    void onSkipped();
    @MainThread
    void onTriggered();
}

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

onFetch()为新增的获取到广告的回调

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.4.9.8 onFetch

调用open()后，成功从服务端获取到广告，此方法会被回调。

1.4.10 设置广告总时长

void setTimeOut(int time);

调用setTimeOut(int time)设置广告调用逻辑总时长，防止广告长时间超时

1.5 技术支持

智能电视网

联系客服：联系客服

Email：report@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 接口返回值查询