# ad-design-flutter-android

**Repository Path**: any-design/ad-design-flutter-android

## Basic Information

- **Project Name**: ad-design-flutter-android
- **Description**: ad-design-flutter-android
- **Primary Language**: Dart
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2022-12-08
- **Last Updated**: 2023-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AdDesignSDK-flutter-android接入文档

| 发行版 | 适配范围 | 修改人 | 更新记录 | 更新日期 |
| :-----: | :------: | :--: | :------ | :--: |
| 1.0.0 | native-android<br/>apicloud-android<br/>flutter-android | [gitee.com/qlslylq](https://gitee.com/qlslylq/)  | 1.提供仅加载，仅展示，加载且展示等公共服务<br/>2.提供静音策略设置，关闭销毁广告，dislike监测，开屏前置页预加载等等个性化功能<br/>3.提供兼容横竖屏切换功能<br/>4.提供实时竞价策略选择，强化收益进阶能力<br/>5.提供服务矩阵离线续命能力，强化收益续航能力<br/>6.提供主从式四支路树型策略矩阵架构，支撑广告生命骨架<br/>7.各项收益指标稳步监测，适时调整至最合适于App的策略矩阵 | 20220910

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

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

## 二、支持广告类型

| 类型 | 简介 | 适用场景 |
| :---------- | :-- | :---------- |
| 开屏广告 |  开屏广告以App启动作为曝光时机，提供5s的<br/>可感知广告展示。  | app启动时，<br/>常会使用开屏广告。
| 插屏广告 |  插屏广告是移动广告的一种常见形式，<br/>在应用开流程中弹出，<br/>当应用展示插页式广告时，用户可以选择点按广告，<br/>访问其目标网址，也可以将其关闭，返回应用。  | 在应用执行流程的自然停顿点，<br/>适合投放这类广告。
| 全屏广告 |  全屏视频广告，该广告的效果播放全屏的视频，<br/>视频一定时间后可跳过，无需全程观看完。  | 类似于激励广告，<br/>但无法获取奖励。
| 激励广告 |  激励视频广告是指将短视频融入到app场景当中，<br/>成为app“任务”之一，<br/>用户观看短视频广告后可以得到一些应用内奖励。 | 常出现在游戏的复活、登录等位置，<br/>或者网服类app的一些增值服务场景。
| 横幅广告 |  位于页面的顶部、中部、底部任意一处，<br/>横向贯穿整个页面。  | 任意界面的固定位置。
| 信息流广告 |  当用户浏览应用内的重要分页列表数据时，<br/>可融入此类型广告平滑展示。<br/>仅原生应用框架支持。<br/>apicloud，flutter等应用框架不支持。 | 常插入到应用内的分页<br/>列表中进行展示。


测试用AppId与聚合广告位ID：
```java
    //测试广告位-正式服
    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的使用规范。表头链接中提供了flutter工程类型的demo项目供app端查看功能列表与使用效果。

>as开发环境下的示例工程编译环境：<br/>
AndroidStudio 4.1.2<br/>
gradle插件版本：4.1.2<br/>
gradle版本：6.8(https\://services.gradle.org/distributions/gradle-6.8-all.zip)<br/>
flutter版本：flutter_windows_3.0.0-stable<br/>
dart版本：2.17.0

### 3.2 嵌入广告SDK
>依赖接入包含有本地依赖包与远程依赖。本地依赖包请从demo的libs目录中获取。下面配置中的”选其一”为根据app自身的android或androidx环境进行选择配置。工程下的build.gradle配置如下：
```groovy
buildscript {
    repositories {
        //jcenter() 使用阿里云镜像
        maven { url 'https://maven.aliyun.com/nexus/content/repositories/jcenter' }

        //google() 使用阿里云镜像
        maven { url 'https://maven.aliyun.com/repository/google' }

        //mavenCentral()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:4.1.2"
    }
}

allprojects {
    repositories {
        //jcenter() 使用阿里云镜像
        maven { url 'http://maven.aliyun.com/nexus/content/repositories/jcenter' }
        maven { url 'https://maven.aliyun.com/nexus/content/repositories/releases/' }

        //google() 使用阿里云镜像
        maven { url 'https://maven.aliyun.com/repository/google' }

        //mavenCentral()
        mavenCentral()

        maven {//穿山甲
            url 'https://artifact.bytedance.com/repository/pangle'
        }

        maven { //mintegral，非上架GP市场应用 非安卓X版本（选其一）
            url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_support/"
        }
        maven { //mintegral，非上架GP市场应用 安卓X版本（选其一）
            url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_china"
        }
        maven { //mintegral，上架GP市场应用 安卓X版本（选其一）
            url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea"
        }
    }
}
```

>基于android：app下的build.gradle配置如下(以下配置中包含的本地依赖包请拷贝到libs目录下)：
```groovy
dependencies {
    //libs(不要包含aar，需单独编译)
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    //布局相关
    implementation 'com.android.support:design:28.0.0'
    implementation 'com.android.support:support-v4:28.0.0'
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.android.support:recyclerview-v7:28.0.0'

    //广告聚合SDK相关
    implementation 'io.gitee.any-design:ad-design:version'
    implementation(name: 'msa_mdid_1.0.22', ext: 'aar')
    implementation(name: 'open_ad_sdk_4.3.0.8', ext: 'aar')
    implementation 'com.qq.e.union:union:4.462.1332'
    implementation(name: 'kssdk-ct-3.3.27.3', ext: 'aar')
    implementation(name: 'windAd-3.5.6', ext: 'aar')
    
    //Mintegral-20220220最新版本(选其一：android)
    implementation 'com.mbridge.msdk.support:reward:16.1.37'
    implementation 'com.mbridge.msdk.support:mbsplash:16.1.37'
    implementation 'com.mbridge.msdk.support:mbbanner:16.1.37'
    implementation 'com.mbridge.msdk.support:newinterstitial:16.3.17'
    implementation 'com.mbridge.msdk.support:mbnative:16.1.37'
}

```

>基于androidx：app下的build.gradle配置如下(以下配置中包含的本地依赖包请拷贝到libs目录下)：
```groovy
dependencies {
    //libs(不要包含aar，需单独编译)
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    //布局相关
    implementation 'com.google.android.material:material:1.1.0'
    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    implementation 'androidx.appcompat:appcompat:1.3.0-alpha02'
    implementation 'androidx.recyclerview:recyclerview:1.1.0'

    //广告聚合SDK相关
    implementation 'io.gitee.any-design:ad-design:version'
    implementation(name: 'msa_mdid_1.0.22', ext: 'aar')
    implementation(name: 'open_ad_sdk_4.3.0.8', ext: 'aar')
    implementation 'com.qq.e.union:union:4.462.1332'
    implementation(name: 'kssdk-ct-3.3.27.3', ext: 'aar')
    implementation(name: 'windAd-3.5.6', ext: 'aar')
    
    //Mintegral-20220220最新版本(选其一：androidx)
    implementation 'com.mbridge.msdk.china:reward:16.1.32'
    implementation 'com.mbridge.msdk.china:mbsplash:16.1.32'
    implementation 'com.mbridge.msdk.china:mbbanner:16.1.32'
    implementation 'com.mbridge.msdk.china:newinterstitial:16.1.32'
    implementation 'com.mbridge.msdk.china:mbnative:16.1.32'
}

```

### 3.3 权限申请
使⽤SDK时可以选择动态申请以下权限，但都不是必须的权限，只是为了更精确地推荐个性化广告，请在6.0及以上的⼿机中使⽤SDK前及时申请以下权限组：(可参考sdkDemo中MainActivity中的动态权限申请)
```java
ACCESS_FINE_LOCATION，
ACCESS_COARSE_LOCATION，
READ_PHONE_STATE，
READ_EXTERNAL_STORAGE，
WRITE_EXTERNAL_STORAGE
```
所需的其它静态权限由sdk自身配置及维护。

### 3.4 混淆配置
本SDK内部已经混淆，无需再为SDK增添额外混淆配置。

资源混淆白名单配置：
如果使用了AndResGuard工具，需要进行以下配置：
```java
"R.string.mbridge*",
"R.layout.mbridge*",
"R.drawable.mbridge*",
"R.anim.mbridge*",
"R.color.mbridge*",
"R.style.mbridge*",
"R.id.mbridge*"
```

## 四、接入代码

### 4.1 SDK初始化

```dart
      var param = {
        "appId": KeyConstant.JH_APP_ID,
        "isTest": false,
        "isDebug": true
      };
      await AdXSdk.initSDK(param);
```
```text
注：isTest：[true,false]表示[测试环境，正式环境]；测试环境已不对外开放，请使用正式环境，即isTest的值必须为false。对于初始化失败的联盟，本SDK内部已做了策略处理；app端不需要做任何处理，仅用于调试时信息的获悉。
```

### 4.2 广告加载通用说明
>AdDesignSDK demo中的横竖屏切换功能演示注意：
_ _ _
(1).关于屏幕方向：  
穿山甲：横竖屏独立两个广告位ID，创建广告位的时候，已经固定了屏幕方向。显示总是按照创建广告位时的方向，传入的方向不改变显示方向。  
优量汇：横竖屏共用一个广告位ID，横竖靠用户设备当前的方向，无需app端传入方向。  
快手：  横竖屏共用一个广告位ID，靠接入端传入的方向，传入的方向能够改变显示方向。  
其它联盟：略。
_ _ _
(2).demo中使用的联盟测试广告位均为竖屏类型的广告位，所以当demo展示横屏广告时，除了优量汇与快手能够正常外，其它联盟是无法正常的，等应用实际在联盟一方申请的广告位方向与当前屏幕一致时，demo的演示即自然回归正常化。
_ _ _
(3).屏幕方向由sdk获取并处理，不需要app端的传递。即横屏的应用游戏等也能够接入AdDesignSDK，只要广告页的屏幕方向与app在联盟上申请的广告位方向保持一致即可。
_ _ _
(4).demo横竖屏切换功能演示时，应先定向(定竖屏或定横屏)再去加载展示广告，这种固定方向类的应用AdDesignSDK能够完全适应；而对于先展示广告后再去随用户动态变更方向的实时变向类的应用，只有部分联盟的部分广告类型能够做到正常与平滑。
_ _ _


|onAdShow()|展示成功
|onAdShowError(AdError error)|展示错误 <br/>error：错误信息 <br/>error.getCode()错误码（详见文档末的错误码说明） <br/>error.getMsg()错误描述 <br/>error.getPlatform()当前展示所使用的联盟平台
|onAdDismiss()|广告被关闭（跳过/倒计时结束/点击关闭/dislike时都会回调）
|onAdClick()|广告被点击（可能出现部分联盟的部分广告类型不回调的情形）
|onDislikeShow()|dislike页-展示(同种广告类型,部分联盟含dislike入口,以实际可见物料为准）
|onDislikeSelected(String value)|dislike页-选中原因
|onDislikeDismiss()|dislike页-关闭
|download相关监听回调|暂不提供

### 4.3 横幅广告示例
位于app顶部、中部、底部任意一处，横向贯穿整个app页面

>主要api：

`Native：com.qlslylq.ad.sdk.core.loader.BannerAdLoader:`
`Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule`
当前类型广告入口。用于加载，展示和操作当前类型广告
|函数名|函数介绍|
|:-|:-|
|Native：<br/>BannerAdLoader(Activity context, <br/>long posId, ViewGroup adContainer, BannerAdListener adListener) | 构造函数，参数说明：<br/>adContainer：展示用广告容器注：建议使用此构造来初始化。<br/>adContainerWidth默认为屏幕宽度；<br/>adSize将优先使用在平台上申请该广告位时所绑定的联盟模板尺寸，不可用时将使用构造中的模板尺寸，再次不可用时，将使用默认模板尺寸。
|Native：<br/>BannerAdLoader(Activity context, <br/>long posId, ViewGroup adContainer, int adContainerWidth, AdSize adSize, BannerAdListener adListener)| 构造函数，参数说明：<br/>adContainer：广告容器<br/> adContainerWidth：展示用广告容器宽度(px)<br/>adSize：期望加载的物料模板尺寸。请与在平台上申请该广告位时所绑定的联盟模板尺寸保持一致，非必传，建议传null。<br/>注：adContainerWidth一般填屏幕宽度；adSize将优先使用在平台上申请该广告位时所绑定的联盟模板尺寸，不可用时将使用构造中的模板尺寸，再次不可用时，将使用默认模板尺寸。
|Web：<br/>initBannerAdLoader({param}, function(ret, err))|构造函数，参数说明：<br/>x：广告容器坐标x值<br/>y：广告容器坐标y值<br/>w：广告容器宽度，传0则映射屏幕宽<br/>h：广告容器高度，传0则映射屏幕高<br/>gravity：广告视图在广告容器中的位置，参考附表<br/>adSize：参考Native构造中的同名参数说明，非必传，建议不传，参考附表<br/>
|setSlideIntervalTime(int slideIntervalTime)| 设置轮播间隔时间(ms)，<br/>值域：[30 * 1000，120 *1000]<br/>若设置为0，则不开启轮播；默认不开启<br/>离开页面时请务必调用，以停止轮播
|closeAd()| 关闭广告
|destroyAd()| 销毁广告

`com.qlslylq.ad.sdk.core.listener.BannerAdListener:`<br/>当前类型广告的事件监听
|函数名|函数介绍|
|:-|:-|
|无新增的状态监听函数|参考【广告加载通用说明】章节中的公共adListener回调函数介绍

### 4.4 插屏广告示例

插屏⼴告是移动⼴告的⼀种常⻅形式，在应⽤流程中弹出，当应⽤展示插屏⼴告时，⽤户可以选择点击
⼴告，访问其⽬标⽹址，也可以将其关闭并返回应⽤；插屏广告包含插屏（半屏）与插屏（全屏）两个子广告类型，具体使⽤请参考Demo

>主要api：

`Native：com.qlslylq.ad.sdk.core.loader.InterstitialAdLoader:`
`Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule`
当前类型广告入口。用于加载，展示和操作当前类型广告
|函数名|函数介绍|
|:-|:-|
|Native：<br/>InterstitialAdLoader(Activity context, <br/>long posId, InterstitialAdListener adListener)|构造函数，参数说明：<br/>声音策略：广告弹出页默认为静音，广告详情页固定为外放
|Native：<br/>InterstitialAdLoader(Activity context, <br/>long posId, boolean autoPlayMuted, <br/> InterstitialAdListener adListener)|构造函数，参数说明：<br/>autoPlayMuted：设置广告弹出页的声音策略，<br/>[true,false]表示[静音,外放]；广告详情页固定为外放
|Web：<br/>initInterstitialAdLoader({param}, function(ret, err))|构造函数，参数说明：<br/>autoPlayMuted：参考Native构造中的同名参数说明
|setAutoPlayMuted(boolean autoPlayMuted)|autoPlayMuted：变更广告弹出页的声音策略，<br/>[true,false]表示[静音,外放]；广告详情页固定为外放

`com.qlslylq.ad.sdk.core.listener.InterstitialAdListener:`<br/>当前类型广告的事件监听
|函数名|函数介绍|
|:-|:-|
|onAdComplete()|视频播放完毕（如果属于视频类型广告）

### 4.5 开屏广告示例
提供半屏式展示与全屏式展示方式，半屏式的高度建议不低于屏幕高的75%，否则可能会影响曝光计价。<br/>
如果应用存在开屏前的前置页面时，sdk也提供有编写在前置页面，应用在开屏页面的预加载方式。<br/>
(暂不支持在application中预加载开屏广告，未来可能会考虑兼容)。<br/>
注意：存在前置页面时，不带adContainer的构造仅用于存在前置页面时的预加载，不能用于展示，且事件均不会回调，保持空实现即可；不存在前置页面时，即在开屏展示页面中的加载展示请使用带adContainer的构造。<br/>
<br/>
对于开屏广告，需要在load前或后做一定的延时处理，以避免code为450的情况出现。例如：<br/>
方式一：延时1000ms-2500ms-->load-->(可选择再次间隔一定时间如500ms-1500ms或间隔自身业务的处理)-->show<br/>
方式二：延时1000ms-2500ms-->loadAndShow<br/>
方式三：死循环等待至initSDK的success回调后再去load,show或loadAndShow。安全起见死循环应给一个极限时间即最大等候时长如2000ms。

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

>主要api：

`Native：com.qlslylq.ad.sdk.core.loader.SplashAdLoader:`
`Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule`
当前类型广告入口。用于加载，展示和操作当前类型广告
|函数名|函数介绍|
|:-|:-|
|Native：<br/>SplashAdLoader(Activity context, <br/>long posId, ViewGroup adContainer, <br/>int fetchDelay, SplashAdListener adListener)|构造函数，参数说明：<br/>adContainer：广告容器<br/>fetchDelay：请求到展示的最大允许时长(ms)，默认为5s<br/>注：当前开屏页面的展示必须使用此构造。
|Native：<br/>SplashAdLoader(Activity context, <br/>long posId, int adContainerWidth, <br/>int adContainerHeight, int fetchDelay, SplashAdListener adListener)|构造函数，参数说明：<br/>adContainerWidth：广告容器宽[px]，必须大于0<br/>adContainerHeight：广告容器高[px]，必须大于0<br/>fetchDelay：请求到展示的最大允许时长(ms)，默认为5s<br/>注：仅用于开屏前置页面的预加载，禁止使用此构造去展示广告，即此构造后只能load，不能show与loadAndShow。
|Web：<br/>initSplashAdLoader({param}, function(ret, err))|构造函数，参数说明：<br/>x：广告容器坐标x值<br/>y：广告容器坐标y值<br/>w：广告容器宽度，传0则映射屏幕宽<br/>h：广告容器高度，传0则映射屏幕高<br/>gravity：广告视图在广告容器中的位置，参考附表<br/>fetchDelay：参考Native构造中的同名参数说明<br/>
|Web：<br/>initSplashAdLoaderForPreload({param}, function(ret, err))|构造函数，参数说明：<br/>adContainerWidth：参考Native构造中的同名参数说明，不能传0<br/>adContainerHeight：参考Native构造中的同名参数说明，不能传0<br/>fetchDelay：参考Native构造中的同名参数说明<br/>


`com.qlslylq.ad.sdk.core.listener.SplashAdListener:`<br/>当前类型广告的事件监听
|函数名|函数介绍|
|:-|:-|
|无新增的状态监听函数|参考【广告加载通用说明】章节中的公共adListener回调函数

### 4.6 激励视频广告示例
将短视频融⼊到APP场景当中，⽤户观看短视频⼴告后可以给予⼀些应⽤内奖励。<br/>

>主要api：

`Native：com.qlslylq.ad.sdk.core.loader.RewardAdLoader:`
`Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule`
当前类型广告入口。用于加载，展示和操作当前类型广告
|函数名|函数介绍|
|:-|:-|
|Native：<br/>RewardAdLoader(Activity context, long posId, RewardAdListener adListener)|构造函数，参数说明：<br/>无
|Web：<br/>initRewardAdLoader({param}, function(ret, err))|构造函数，参数说明：<br/>无


`com.qlslylq.ad.sdk.core.listener.RewardAdListener:`<br/>当前类型广告的事件监听
|函数名|函数介绍|
|:-|:-|
|onReward()|已达到获取奖励的条件
|onAdComplete()|视频播放完毕

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

>主要api：

`Native：com.qlslylq.ad.sdk.core.loader.FullScreenAdLoader:`
`Web：com.qlslylq.ad.sdk.library.apicloud.AdDesignModule`
当前类型广告入口。用于加载，展示和操作当前类型广告
|函数名|函数介绍|
|:-|:-|
|Native：<br/>FullScreenAdLoader(Activity context, <br/>long posId, FullScreenAdListener adListener)|构造函数，参数说明：<br/>无
|Web：<br/>initFullScreenAdLoader({param}, function(ret, err))|构造函数，参数说明：<br/>无

`com.qlslylq.ad.sdk.core.loader.FullScreenAdListener:`<br/>当前类型广告的事件监听
|函数名|函数介绍|
|:-|:-|
|onAdComplete()|视频播放完毕

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

>主要api：

`Native：com.qlslylq.ad.sdk.core.loader.FeedAdLoader:`
当前类型广告入口。用于加载，展示和操作当前类型广告
|函数名|函数介绍|
|:-|:-|
|Native：<br/>FeedAdLoader(Activity context, long posId, <br/>FeedAdListener adListener)|构造函数，参数说明：<br/>声音策略：广告弹出页默认为外放，广告详情页固定为外放
|Native：<br/>FeedAdLoader(Activity context, long posId, <br/>float expressWidth, float expressHeight, <br/>int adCount, boolean autoPlayMuted,<br/> FeedAdListener adListener)|构造函数，参数说明：<br/>expressWidth：期望物料宽度(默认：屏幕宽,px)<br/>expressHeight：期望物料高度(默认：0,即自适应,px)<br/>adCount：单个联盟单次请求数量(默认：1)<br/>autoPlayMuted：设置广告弹出页的声音策略，<br/>[true,false]表示[静音，外放]；广告详情页固定为外放
|setAutoPlayMuted(boolean autoPlayMuted)|autoPlayMuted：变更广告弹出页的声音策略，<br/>[true,false]表示[静音，外放]；广告详情页固定为外放




`com.qlslylq.ad.sdk.core.loader.FeedAdListener:`<br/>当前类型广告的事件监听
|函数名|函数介绍|
|:-|:-|
|onAdReadyShow(List`<SingleFeedAd>` list)|预备展示，参数说明：<br/>list：装有<=adCount数量的广告，app将给此list中的各广告模型插入到列表数据中，再通过多布局方式渲染正常数据和广告视图。<br/>SDK支持模板渲染信息流：singleFeedAd.render()<br/>SingleFeedAd：信息流广告模型，函数提供有：<br/>getAd()：获取联盟广告模型<br/>getPlatform()：获取联盟<br/>getAdView()：获取模板渲染下的广告视图<br/>render()：模板渲染
|onAdClick(SingleFeedAd ad)|广告被点击，参数说明：<br/>ad：信息流广告模型，详见构造中的SingleFeedAd说明
|onAdDismiss(SingleFeedAd ad)|广告被关闭，参数说明：<br/>ad：信息流广告模型，详见构造中的SingleFeedAd说明



## 五、所有函数一览表

### 5.1 插件中可封装的native所有函数预览


>主要api：

|函数名|函数介绍|
|:-|:-|
|initSDK()|初始化广告聚合SDK
|initSplashAdLoader()|初始化开屏广告加载器
|loadSplashAd()|加载开屏广告
|showSplashAd()|展示开屏广告
|loadAndShowSplashAd()|加载并展示开屏广告
|initRewardAdLoader()|初始化激励广告加载器
|loadRewardAd()|加载激励广告
|showRewardAd()|展示激励广告
|loadAndShowRewardAd()|加载并展示激励广告
|setUserId()|服务端奖励方式下透传消息所需
|setExtraData()|服务端奖励方式下透传消息所需
|initInterstitialAdLoader()|初始化插屏广告加载器
|loadInterstitialAd()|加载插屏广告
|showInterstitialAd()|展示插屏广告
|loadAndShowInterstitialAd()|加载并展示插屏广告
|setAutoPlayMuted()|插屏广告设置声音策略
|initBannerAdLoader()|初始化横幅广告加载器
|loadBannerAd()|加载横幅广告
|showBannerAd()|展示横幅广告
|loadAndShowBannerAd()|加载并展示横幅广告
|setSlideIntervalTime()|横幅广告设置轮播间隔时间（ms）
|setAllowShowCloseBtn()|横幅广告设置是否允许展示关闭按钮
|closeAd()|关闭横幅广告
|destroyAd()|销毁横幅广告


## 六、Flutter应用中Web与Native通信相关

### 6.1 通信key约定

```java
    /**
     * 广告位相关
     */
    String JH_SPLASH_POS_ID = "JH_SPLASH_POS_ID";//开屏
    String JH_REWARD_POS_ID = "JH_REWARD_POS_ID";//激励
    String JH_INTERSTITIAL_POS_ID = "JH_INTERSTITIAL_POS_ID";//插屏
    String JH_BANNER_POS_ID = "JH_BANNER_POS_ID";//横幅


    /**
     * 广告事件相关
     */
    String EVENT_NAME = "eventName";
    String DISLIKE_VALUE = "dislikeValue";
    String ERROR = "error";

    /**
     * 开屏广告相关
     */
    String AD_CONTAINER_WIDTH = "adContainerWidth";
    String AD_CONTAINER_HEIGHT = "adContainerHeight";
    String FETCH_DELAY = "fetchDelay";

    /**
     * 横幅广告相关
     */
    String X = "x";
    String Y = "y";
    String W = "w";
    String H = "h";
    String GRAVITY = "gravity";
    String AD_SIZE = "adSize";
    String SLIDE_INTERVAL_TIME = "slideIntervalTime";
    String ALLOW_SHOW_CLOSE_BTN = "allowShowCloseBtn";

    /**
     * 插屏广告相关
     */
    String AUTO_PLAY_MUTED = "autoPlayMuted";

    /**
     * 激励广告相关
     */
    String USER_ID = "userId";
    String EXTRA_DATA = "extraData";

    /**
     * 普通成功回执相关
     */
    String CODE = "code";
    String DATA = "data";

    /**
     * 版本相关
     */
    String VERSION_NAME = "versionName";
    String VERSION_CODE = "versionCode";
    String UPDATE_TIME = "updateTime";
```

### 6.2 通信数据格式约定

AdError数据模型：可参考：com.qlslylq.ad.sdk.core.rsp.AdError
```java
{
    platform："",  //联盟
    adType："",    //广告类型
    code：450,     //错误码
    msg：""        //错误描述
}
```

普通成功回调格式：
```java
{
    code：200,
    msg:""
}
```

普通成功并携带数据回调格式：
```java
{
    code：200,
    msg:""
    data:{
        
    }
}
```

普通失败回调格式：
```java
{
    code：480,
    msg:"",
    error:""
}
```

广告事件回调格式：
```java
{
    eventName："onAdShowError",
    error: AdError数据模型
}
```

```text
注：
广告聚合sdk初始化失败的数据格式：AdError数据模型；  
广告事件通过initLoader回调；  
load，show，loadAndShow等加载展示型函数有校验型错误回调(广告加载器没有初始化)，格式为：AdError数据模型（无成功回调）；  
loader中的非加载，展示类型的函数，如setSlideIntervalTime，closeAd等此类辅助性函数有成功与失败回调，格式为普通成功回调格式，普通失败回调格式。
```

### 6.3 附表

gravity取值源：android.view.Gravity<br/>
gravity值域：
```java
TOP = 48;
BOTTOM = 80;
LEFT = 3;
RIGHT = 5;
START = 8388611;
END = 8388613;
CENTER_HORIZONTAL = 1;
CENTER_VERTICAL = 16;
CENTER = 17;
```

adSize取值源：com.qlslylq.ad.sdk.enums.AdSize<br/>
adSize值域：
```java
"c_b_30045",
"c_b_300150",
"c_b_300200",
"c_b_300250",
"c_b_300130",
"c_b_30045",
"c_b_30075",
"c_b_32050",
"c_b_32090",
"c_b_345194",
```

## 七、常见问题及说明

### 7.1 接入相关Q&A
Q : 某某_file_path.xml，某某_provider_path not found？ <br/>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...？ <br/>A :
引入了相同依赖的不同版本，统一到合适的版本并确保在运行后没有出现相关依赖中class method等找不到的问题。可使用exclude group语法排除其中一个不合适的版本。  
例如如果alicloud-android-utdid重复引入了，则可(其它依赖的重复引入同理)：
```groovy
api('io.gitee.any-design:ad-design:version') {
    exclude group: "com.aliyun.ams", module: "alicloud-android-utdid"
}
```

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

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

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

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

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

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

## 八、SDK错误码
>展示⼴告失败时会回调接⼝ onAdShowError(AdError error)，AdError中的实例函数：

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

>常⻅错误码如下：

|code|说明|
|:-|:-|
|450|获取数据失败，请稍后再试
|451|AppId或AppKey无效
|452|联盟SDK初始化失败
|453|本地及远端均无广告位配置数据
|454|暂无可用的广告，请重新请求
|455|播放异常，请重新请求
|456|渲染失败，请重新请求
|457|加载失败
|458|加载异常
|459|展示失败
|460|展示异常
|461|未准备就绪，还不能展示
|462|该广告已失效，请重新请求
|463|[开屏]请初始化含有adContainer的构造器来展示；<br/>不含adContainer的构造器仅用于预加载，不能用于展示
|464|请在initSDK的success之后或延时合适的时间直到success后再load开屏广告
|480|FAILD
|481|context必须为activity类型
|482|请先初始化广告加载器