AdDesignSDK-native-android接入文档

注：
(1).欢迎有流量变现需求，接入广告需求的各大企业，团体或开发者前来洽谈合作；或对本文档有细节建议或技术讨论的可加微信：13297089301，添加时请备注流量变现
(2).基于native-android应用框架的demo及SDK依赖库下载地址(master分支)：
https://gitee.com/any-design/ad-design-native-android.git
(3).基于apicloud-android应用框架的demo及SDK依赖库下载地址(master分支)：
https://gitee.com/any-design/ad-design-apicloud-android.git
(4).基于flutter-android应用框架的demo及SDK依赖库下载地址(master分支)：
https://gitee.com/any-design/ad-design-flutter-android.git
(5).与android相关的各应用框架下的发行版本详见表头
(6).最新文档请以上述demo中的README.md为准，最新SDK依赖库也以上述地址为准，均会第一时间且优先发布到上述地址

一、概述

尊敬的开发者朋友，欢迎使用AdDesign聚合广告SDK。本文档旨在帮助native-android 应用开发者在程序中快速接入本SDK。通过本文档，您只需要进行简单配置，就可以快速植入本平台提供的广告。关于SDK具体使用方法，请仔细阅读下面的文档。

二、支持广告类型

测试用AppId与聚合广告位ID：

    //测试广告位-正式服
    long JH_APP_ID = 6;//应用ID
    long JH_SPLASH_POS_ID = 22;//开屏
    long JH_INTERSTITIAL_POS_ID = 23;//插屏
    long JH_FULL_SCREEN_POS_ID = 24;//全屏
    long JH_REWARD_POS_ID = 25;//激励
    long JH_BANNER_POS_ID = 26;//横幅
    long JH_FEED_POS_ID = 27;//信息流

三、SDK嵌入

3.1 示例工程导入运行

如果您是初次使用本SDK，我们建议您利用demo工程来了解本SDK的使用规范。请使用?AndroidStudio?开发环境（建议 AndroidStudio 4.1.2 及以上），按照以下步骤来正确编译运行demo项目：
(1).克隆出对应应用框架的demo项目，根目录下会包含ad-design-exp与ad-design-library两个子目录(以下简称exp、library)
(2).重新导入exp目录对应的项目，编译运行。

示例工程及本SDK的编译环境： AndroidStudio 4.1.2 gradle插件版本：4.1.2 gradle版本：6.8

3.2 正式工程嵌入SDK

配置仓库。在正式工程下的直属build.gradle文件头部添加如下配置(请正确配置相对路径)：

apply from: '../ad-design-library/build.gradle'

导入依赖。在正式工程下的直属settings.gradle文件中添加如下配置(请正确配置相对路径)：

include ':lib-ad-design'
project(':lib-ad-design').projectDir = new File('../ad-design-library/app')

添加依赖。在正式工程下的app下的build.gradle文件的dependencies部分添加如下配置：

implementation project(':lib-ad-design')

注：关于更新依赖。开发者可随时查看远端demo地址下的README文件表头是否有新的发行版发布，若有发布且想接入最新版，则pull demo地址即可。

3.3 权限申请

可以选择动态申请以下权限，但都不是必要权限，乃是为了更精确地推荐个性化广告。可在6.0及以上的系统中及时申请以下权限组：(可参考demo中MainActivity中的动态权限申请)

ACCESS_FINE_LOCATION，
ACCESS_COARSE_LOCATION，
READ_PHONE_STATE，
READ_EXTERNAL_STORAGE，
WRITE_EXTERNAL_STORAGE

所需的其它静态权限由SDK自身配置及维护。

3.4 混淆配置

SDK的混淆已由内部完成，外界无需再为SDK增添额外混淆配置。

资源混淆白名单配置： 如果使用了AndResGuard工具，需要进行以下配置：

"R.string.mbridge*",
"R.layout.mbridge*",
"R.drawable.mbridge*",
"R.anim.mbridge*",
"R.color.mbridge*",
"R.style.mbridge*",
"R.id.mbridge*"

四、接入代码

4.1 SDK初始化

在Application中进行SDK的初始化(具体请参考demo)：

AdDesignSDKConfig config = new AdDesignSDKConfig.Builder()
        .setAppId(KeyConst.JH_APP_ID) //请换为在AdDesign平台上申请的应用ID
        .setTest(false)        // [true,false]表示[测试环境，正式环境]；测试环境已不对外开放，请使用正式环境，即必须为false
        .setDebug(true)       // 开启DEBUG模式，打印内部LOG并显示联盟名称提示等；发布可关闭
        .build();
AdDesignSDK.init(this, config, new InitCallback() {

    //表示已准备好，可以去加载广告了(并非表示所有联盟初始化成功了)
    //对于开屏广告，需要在load前或后做一定的延时处理，以避免code为450的情况出现。例如：
    //方式一：延时1000ms-2500ms-->load-->(可选择再次间隔一定时间如500ms-1500ms或间隔自身业务的处理)-->show
    //方式二：延时1000ms-2500ms-->loadAndShow
    //方式三：死循环等待至initSDK的success回调后再去load,show或loadAndShow。安全起见死循环应给一个极限时间即最大等候时长如2000ms。
    public void success() {

    }

    //所有初始化失败的联盟均会回调此函数，回调多次
    public void fail(AdPlatformEnum platform, int code, String msg) {
   
    }
});

4.2 广告加载通用说明

AdDesignSDK demo中的横竖屏切换功能演示注意：

(1).关于屏幕方向：
穿山甲：横竖屏独立两个广告位ID，创建广告位的时候，已经固定了屏幕方向。显示总是按照创建广告位时的方向，传入的方向不改变显示方向。
优量汇：横竖屏共用一个广告位ID，横竖靠用户设备当前的方向，无需app端传入方向。
快手： 横竖屏共用一个广告位ID，靠接入端传入的方向，传入的方向能够改变显示方向。
其它联盟：略。

(2).demo中使用的联盟测试广告位均为竖屏类型的广告位，所以当demo展示横屏广告时，除了优量汇与快手能够正常外，其它联盟是无法正常的，等应用实际在联盟一方申请的广告位方向与当前屏幕一致时，demo的演示即自然回归正常化。

(3).屏幕方向由sdk获取并处理，不需要app端的传递。即横屏的应用游戏等也能够接入AdDesignSDK，只要广告页的屏幕方向与app在联盟上申请的广告位方向保持一致即可。

(4).demo横竖屏切换功能演示时，应先定向(定竖屏或定横屏)再去加载展示广告，这种固定方向类的应用AdDesignSDK能够完全适应；而对于先展示广告后再去随用户动态变更方向的实时变向类的应用，只有部分联盟的部分广告类型能够做到正常与平滑。

主要api：

Native：com.qlslylq.ad.sdk.core.loader.XXAdLoader(XX表示某具体类型的广告) Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule(XX表示某具体类型的广告) 当前类型广告入口。用于加载，展示和操作当前类型广告

注：以下两种场景下每次展示广告前loader必须再次初始化(或updateListener)，否则listener将不会收到回调(如果不需要在回调中处理业务，则可以选择忽略)
场景一：常驻页面。如MainAct，HomeAct这种在退出前不会出栈的常驻页面，都需要实时初始化loader或，不可保存loader到该页面全局(或updateListener)；如果不会在该loader的回调中处理业务，则也可以选择保存loader到该页面全局。
场景二：共存页面。如处在同一个act中的多个frag都初始化了相同广告类型的loader，则都需要实时初始化loader，不可保存loader到该页面全局(或updateListener)；如果不会在该loader的回调中处理业务，则也可以选择保存loader到该页面全局。

Native：com.qlslylq.ad.sdk.core.listener.XXAdListener:

Web：
所有广告事件均通过initLoader函数中的ret来下发，
广告事件的名称通过ret.eventName下发(与下表中的事件函数名完全)，
广告事件的error数据通过ret.error下发，
广告事件的dislikeValue数据通过ret.dislikeValue下发，
相关key的约定可参考章节"ApiCloud应用中的Web与Native通信相关"中的"key的约定"

所有广告类型公共的adListener回调函数：

4.3 开屏广告示例

提供半屏式展示与全屏式展示方式，半屏式的高度建议不低于屏幕高的75%，否则可能会影响曝光计价。
如果应用存在开屏前的前置页面时，sdk也提供有编写在前置页面，应用在开屏页面的预加载方式。
(暂不支持在application中预加载开屏广告，未来可能会考虑兼容)。
注意：存在前置页面时，不带adContainer的构造仅用于存在前置页面时的预加载，不能用于展示，且事件均不会回调，保持空实现即可；不存在前置页面时，即在开屏展示页面中的加载展示请使用带adContainer的构造。

对于开屏广告，需要在load前或后做一定的延时处理，以避免code为450的情况出现。例如：
方式一：延时1000ms-2500ms-->load-->(可选择再次间隔一定时间如500ms-1500ms或间隔自身业务的处理)-->show
方式二：延时1000ms-2500ms-->loadAndShow
方式三：死循环等待至initSDK的success回调后再去load,show或loadAndShow。安全起见死循环应给一个极限时间即最大等候时长如2000ms。

注：对于ApiCloud应用，提供了Native与Web两种加载展示开屏广告的方式，app端可根据场景需要，选取其中一种方式接入即可。两种开屏广告类型的接入方式已在demo演示示例中，细节请参考demo。

主要api：

Native：com.qlslylq.ad.sdk.core.loader.SplashAdLoader: Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule 当前类型广告入口。用于加载，展示和操作当前类型广告

com.qlslylq.ad.sdk.core.listener.SplashAdListener:
当前类型广告的事件监听

4.4 插屏广告示例

插屏广告是移动广告的一种常见形式，在应用开流程中弹出，当应用展示插页式广告时，用户可以选择点按广告，访问其目标网址，也可以将其关闭，返回应用。在应用执行流程的自然停顿点，适合投放这类广告。

主要api：

Native：com.qlslylq.ad.sdk.core.loader.InterstitialAdLoader: Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule 当前类型广告入口。用于加载，展示和操作当前类型广告

com.qlslylq.ad.sdk.core.listener.InterstitialAdListener:
当前类型广告的事件监听

4.5 全屏广告示例

全屏视频广告，该广告的效果播放全屏的视频，视频一定时间后可跳过，无需全程观看完。 类似于激励广告，但无法获取奖励。

主要api：

Native：com.qlslylq.ad.sdk.core.loader.FullScreenAdLoader: Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule 当前类型广告入口。用于加载，展示和操作当前类型广告

com.qlslylq.ad.sdk.core.loader.FullScreenAdListener:
当前类型广告的事件监听

4.6 激励视频广告示例

激励视频广告是指将短视频融入到app场景当中，成为app“任务”之一，用户观看短视频广告后可以得到一些应用内奖励。常出现在游戏的复活、登录等位置，或者网服类app的一些增值服务场景。

主要api：

Native：com.qlslylq.ad.sdk.core.loader.RewardAdLoader: Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule 当前类型广告入口。用于加载，展示和操作当前类型广告

com.qlslylq.ad.sdk.core.listener.RewardAdListener:
当前类型广告的事件监听

4.7 横幅广告示例

位于页面的顶部、中部、底部任意一处，横向贯穿整个页面。

主要api：

Native：com.qlslylq.ad.sdk.core.loader.BannerAdLoader: Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule 当前类型广告入口。用于加载，展示和操作当前类型广告

com.qlslylq.ad.sdk.core.listener.BannerAdListener:
当前类型广告的事件监听

4.8 信息流广告示例

当用户浏览应用内的重要分页列表数据时，可融入此类型广告平滑展示。 常插入到应用内的分页列表中进行展示。

主要api：

Native：com.qlslylq.ad.sdk.core.loader.FeedAdLoader: 当前类型广告入口。用于加载，展示和操作当前类型广告

com.qlslylq.ad.sdk.core.loader.FeedAdListener:
当前类型广告的事件监听

五、常见问题及说明

5.1 接入相关Q&A

Q : 某某_file_path.xml，某某_provider_path not found？
A : 对应的联盟sdk没有download下来，从清单合并显示图中通过关键字找到对应的联盟，检查对应的联盟是否正常download下来了。

例如如果是gdt_file_path.xml not found，则是优量汇sdk没有download下来，请调整各仓库根地址的顺序以保证其下载下来或从demo根目录的压缩包中找到优量汇的aar配置到项目中；

例如如果是mb_provider_paths.xml not found，请确认是否配置了mbridge的依赖与其仓库根地址(参考本文档的嵌入广告sdk节中的mbridge配置)。

Q : Duplicate class...found in...and...？
A : 引入了相同依赖的不同版本，统一到合适的版本并确保在运行后没有出现相关依赖中class method等找不到的问题。可使用exclude group语法排除其中一个不合适的版本。
例如如果alicloud-android-utdid重复引入了，则可(其它依赖的重复引入同理)：

api('io.gitee.any-design:ad-design:version') {
    exclude group: "com.aliyun.ams", module: "alicloud-android-utdid"
}

Q : 广告展示过程中的联盟名称提示如何关闭掉？
A : 通过初始化sdk时setDebug为false以关闭提示。

5.2 开屏广告相关Q&A

Q : 开屏广告，点击之后开始下载不跳转主页面，或者跳转到广告落地页后返回开屏不跳转主页面，或者广告点击之后跳转的落地页被主页覆盖，或者其他有关开屏跳转逻辑问题，该如何处理？
A : 开屏跳转逻辑较为严格，请参考demo中的开屏?告示例

Q : 开屏广告的跳过按钮是否支持自定义样式和倒计时时?？
A : 自定义样式暂不?持，倒计时时长请参考开屏SplashLoader类构造中的fetchDelay参数

Q : 开屏广告在网络较慢时会有较长时间白屏，该如何处理？
A :1>.可以设置开屏界面主题的windowBackground来过渡；
    2>.如果在开屏页之前有前置页面，可以在前置页面中进行预加载
    3>.后期sdk也会考虑使开屏广告能够在application中进行预加载，以加快开屏页的展示效率

5.3 信息流广告相关Q&A

Q : 信息流广告中部分没有关闭按钮？
A : 关闭按钮分为普通关闭按钮与dislike按钮(一般会弹出一个选择原因的弹窗)。对于信息流广告，大部分联盟提供的是dislike按钮，部分联盟既不会提供dislike按钮，也不会提供普通关闭按钮。

5.4 插屏广告相关Q&A

Q : 快手联盟的部分插屏广告点击广告中的任何区域包括关闭按钮无反应？
A : 快手sdk旧版本的问题，快手3.3.20版本及以下会有部分素材发生的可能，请升级快手sdk版本并确保升级后没有找不到快手相关的类，函数的问题。

六、SDK错误码

展示广告失败时会回调接? onAdShowError(AdError error)，AdError中的实例函数：

getPlatform()：当前展示所使用的联盟
getCode()：错误码
getMsg()：错误描述

常见错误码如下：