趣盟 Android SDK 接入文档

广告 SDK 说明：

• 通用版本：兼容androidx跟support版本

• 本 SDK 最低兼容 Android API 14（Android 4.0 ICS）

• 媒体接入信通院 oaid-sdk

一、导入SDK依赖

1.1 本地aar依赖

1. 在 app 目录下新建 libs 文件夹

2. 将压缩包中的 aar 文件放入 libs 文件夹

3. 在 app/build.gradle 添加如下代码

   ​x
   repositories {
       flatDir {
           dirs 'libs'
       }
   }
   
   dependencies {
       api(name: 'aar文件名', ext: 'aar')
   }
   

1.2 AndroidManifest 配置

xxxxxxxxxx
<uses-permission android:name="android.permission.INTERNET" />
<!-- 可选 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" /> //targetApi 33以上，使用通知需要增加这个权限

1.3 混淆配置

注意事项：

如果 tools.build:gradle 版本小于 4.1.0，请检查自定义混淆规则或 proguard-android-optimize，确认混淆规则中没有使用 -allowaccessmodification 属性

1.4 FileProvider 配置

xxxxxxxxxx
<provider
    android:name="com.qumeng.advlib.core.CPCFileProvider"
    android:authorities="${applicationId}.CPCFileProvider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/cpc_external_files" />
</provider>

二、配置相关

2.1 初始化SDK

AiClkAdManager为单例，会做一些初始化工作，需要传入一个Context对象

xxxxxxxxxx
AiClkAdManager.getInstance().init(new QMConfig.Builder()
        .build(this));

2.2 隐私信息控制开关

x
public abstract class QMCustomControl {
  
   /**
    * 是否允许SDK主动获取安装列表
    * @return 默认false 不允许 ， true 允许
    */
   public boolean isCanUseAppList() {
      return false;
   }


   /**
    * 当isCanUseAppList=false时，可传入applist信息，sdk使用您传入的applist信息
    * @return true可以使用，false禁止使用。默认为true
    */
   public List<PackageInfo> getAppList() {
      return null;
   }

   /**
    *  开发者可以传入oaid 仅初始化调用一次
    *  信通院OAID的相关采集——如何获取OAID：
    1. 移动安全联盟官网http://www.msa-alliance.cn/
    2. 信通院统一SDK下载http://msa-alliance.cn/col.jsp?id=120
    *  如果首次传入为null，后续可以通过JFIdentifierManager.getInstance().setOaid(String oaid)方式传入oaid
    * @return oaid 
    */
   public String getOaid() {
      return null;
   }
  
   /**
   * 3.462.15.428版本
   * 媒体主动传入oaid，则优先使用媒体方的oaid，未传入oaid时通过该开关控制是否允许SDK主动获取oaid
   * @return 默认true 允许 ， false 不允许
   */
  public boolean isCanUseOaid() {
    return true;
  }
  
  /**
   * aar版本大于等于3.468.11.434 且仅对小米设备生效，其他设备默认获取
   * 是否允许SDK主动获取Boot ID
   * @return true 允许 ， false 不允许  默认false  
   */
  public boolean isCanUseBootId() {
    return false;
  }
  
  /**
   * aar版本大于等于3.469.13.435版本支持 
   * map方式传入自定义设置
   * 当前支持传入fileProviderAuthority，如果媒体传入了的情况下，优先使用媒体传入的fileprovider，
   * 该情况下可删除趣盟Manifest中 com.qumeng.advlib.core.CPCFileProvider的配置，
   * 但是需要在媒体的provider中配置趣盟所需的<paths>
   * 传入方式：参考示例
   */
  @Override
  public Map<String, Object> getCustomConfig() {
      return null;
  }
  
}

示例：

xxxxxxxxxx
AiClkAdManager.getInstance().init(new QMConfig.Builder()
        .customControl(new QMCustomControl() {
           @Override
           public Map<String, Object> getCustomConfig() {
               Map<String,Object> map = new HashMap<>();
               map.put("FileProviderAuthority","媒体的FileProvider");
               return map;
           }
        })
        .build(this));

2.3 个性化设置

3.455.10.420新增推荐广告开关

xxxxxxxxxx
 /**
   * 设置个性化推荐广告
   * true：允许个性化推荐广告  false：屏蔽个性化推荐广告
   */
void setPersonalRecommend(boolean enable)

3.469.13.435新增摇一摇开关（传感器信息使用）

xxxxxxxxxx
 /**
   * 设置个性化摇一摇开关（是否允许使用传感器）
   * true：允许摇一摇广告  false：不允许摇一摇广告
   */
void setTwistSwitch(boolean enable)

示例：

xxxxxxxxxx
AiClkAdManager.getInstance().setPersonalRecommend(true) //默认true 允许个性化推荐广告
AiClkAdManager.getInstance().setTwistSwitch(true);//默认true 允许摇一摇广告

2.4 通用接口说明

接口IMultiAdObject说明

2.5 接入注意事项

1、广告无效：通过isValid()方法可以判断广告是否有效，无效广告将不计入展点消数据

三、信息流广告

3.1 请求广告

通过管理类构造请求对象-AdRequest

xxxxxxxxxx
IMultiAdRequest request = AiClkAdManager.getInstance().createAdRequest();

构造请求参数-AdRequestParam

xxxxxxxxxx
AdRequestParam requestParam = new AdRequestParam.Builder()
    .adslotID("9004885")//栏位id
    .adType(AdRequestParam.ADTYPE_FEED)//广告类型：信息流
    .extraBundle(bundle)//扩展字段
    .adLoadListener(new AdRequestParam.ADLoadListener() {
        @Override
        public void onADLoaded(IMultiAdObject adModel) {

        }

        @Override
        public void onAdFailed(String errorMsg) {
            Log.i("aiclk", "onAdFailed:" + errorMsg);
        }
    })
    .build();

请求广告

xxxxxxxxxx
if (multiAdRequest != null) {
    multiAdRequest.invokeADV(requestParam);
}

3.2 展示广告

3.2.1 自渲染示例

onADLoaded回调得到的对象IMultiAdObject。

注意

①如果有渲染合规前置，点击创意区域直接下载（无二次确认弹窗），请使用bindEvent(ViewGroup adContainer, List clickViews, List creativeViews, ADEventListener listener) 将创意区域的view传入。

代码示例：

xxxxxxxxxx
if (adModel != null && adModel.isValid()) {
    String title = adModel.getTitle();//获取广告标题
    List<String> urls = adModel.getImageUrls();//获取广告图片
    int price = adModel.getECPM();/获取广告价格
    Pair<Integer,Integer> mediaSize = adModel.getMediaSize();//获取素材大小
    int materialType = adModel.getMaterialType();//获取广告物料类型
    View videoView = adModel.getVideoView(adContent.getContext());//获取视频播放器控件
    adModel.bindEvent(adContent, Arrays.asList((View)imageView)
        ,new IMultiAdObject.ADEventListener() {//绑定广告事件
            @Override
            public void onAdClick() {
                Log.i("aiclk","onAdClick... ...");//广告点击
            }

            @Override
            public void onADExposed() {
                Log.i("aiclk","onADExposed... ...");//广告展现
            }

            @Override
            public void onAdFailed(String errorMsg) {
                Log.i("aiclk","onAdFailed... ...");
            }
    });
}

3.2.2 模板渲染示例

onADLoaded回调得到的对象IMultiAdObject。

代码示例：

xxxxxxxxxx
if (adModel != null && adModel.isValid()) {
    adModel.setADStateListener(new IMultiAdObject.ADStateListener() {
       @Override
       public void onAdEvent(int eventType, @NonNull Bundle data) {
          Log.i("aiclk", "eventType = " + eventType);
          if (eventType == ADEvent.EVENT_AD_CLOSE) {
             //客户端处理
             Toast.makeText(FeedAdActivity.this, "广告关闭回调", Toast.LENGTH_SHORT).show();
          }
       }
    });
    adModel.bindView(adTemplateContent, new IMultiAdObject.ADEventListener() {
       @Override
       public void onAdClick() {
          Log.i("aiclk", "onAdClick");
          Toast.makeText(FeedAdActivity.this, "广告点击", Toast.LENGTH_SHORT).show();
       }

       @Override
       public void onADExposed() {
          Log.i("aiclk", "onAdShow");
          Toast.makeText(FeedAdActivity.this, "广告展现", Toast.LENGTH_SHORT).show();
       }

       @Override
       public void onAdFailed(String errorMsg) {
          Log.i("aiclk", "onAdFailed: " + errorMsg);
          Toast.makeText(FeedAdActivity.this, "广告失败", Toast.LENGTH_SHORT).show();
       }
    });
}

3.3 信息流广告下载监听

广告下载事件监听（3.456及以上版本支持）

xxxxxxxxxx
//下载监听设置
adModel.setDownloadListener(new IAppDownloadListener() {
    /**
     * 未开始下载
     */
    @Override
    public void onIdle() {
    }
  
    /**
     * 下载中回调
     * @param totalBytes 安装包总字节数 -1 ：未知
     * @param currBytes 当前已下载的字节数
     * @param appName 当前下载的APP名
     */
    @Override
    public void onDownloadActive(long totalBytes, long currBytes, String appName) {
    }
  
    /**
     * 下载暂停回调
     * @param totalBytes 安装包总字节数 -1 ：未知
     * @param currBytes 当前已下载的字节数
     * @param appName 当前下载的APP名
     */
    @Override
    public void onDownloadPaused(long totalBytes, long currBytes, String appName) {
    }
  
    /**
     * 下载失败回调
     */
    @Override
    public void onDownloadFailed() {
        creativeBtn.setText("下载失败");
    }
  
    /**
     * 下载完成回调
     * @param appName 当前下载的APP名
     */
    @Override
    public void onDownloadCompleted(String appName) {
        creativeBtn.setText("安装应用");
    }
  
    /**
     * 安装完成回调
     * @param appName 当前下载的APP名
     */
    @Override
    public void onInstalled(String appName) {
        creativeBtn.setText("立即体验");
    }
});

3.4 接口说明

接口IMultiAdObject说明

视频状态监听 IMultiAdObject.MediaStateListener 接口说明：

四、激励视频

4.1 广告请求加载

首先请求广告物料，请求方式和信息流基本一样。请注意，adType为ADTYPE_REWARD_VIDEO

xxxxxxxxxx
AdRequestParam requestParam = new AdRequestParam.Builder()
        .adslotID("7124677")  //必选
        .adType(AdRequestParam.ADTYPE_REWARD_VIDEO) //必选，请注意：adType为ADTYPE_REWARD_VIDEO
        .extraBundle(bundle)//扩展字段
        .adLoadListener(new AdRequestParam.ADLoadListener() { //必选，加载监听
@Override
public void onADLoaded(IMultiAdObject object) {
        Log.e(TAG, "onADLoaded");
        }

@Override
public void onAdFailed(String errorMsg) {
        Log.e(TAG, "onAdFailed:" + errorMsg);
        }
        })
        .build();
        IMultiAdRequest multiAdRequest = AiClkAdManager.getInstance().createAdRequest();
        if (multiAdRequest != null) {
        multiAdRequest.invokeADV(requestParam);
        }

onADLoaded回调得到的对象IMultiAdObject，启动激励视频界面

xxxxxxxxxx
if (object != null && object.isValid()) {
        object.showRewardVideo(MainActivity.this,new AdRequestParam.ADRewardVideoListener() {//必选，激励视频回调监听
@Override
public void onAdShow(Bundle bundle) {
        Log.i("aiclk",TAG + ":onAdShow");//广告展示
        }

@Override
public void onAdClick(Bundle bundle) {
        Log.i("aiclk",TAG + ":onAdClick");//广告点击
        }

@Override
public void onAdClose(Bundle bundle) {
        Log.i("aiclk",TAG + ":onAdClose");//激励视频页面关闭
        }

@Override
public void onVideoComplete(Bundle bundle) {
        Log.i("aiclk",TAG + ":onVideoComplete");//激励视频播放完成
        }

@Override
public void onVideoError(Bundle bundle) {
        Log.i("aiclk",TAG + ":onVideoError");//激励视频播放失败
        }

@Override
public void onReward(Bundle bundle) {
        Log.i("aiclk",TAG + ":onReward");//激励视频领取奖励
        }

@Override
public void onSkippedVideo(Bundle bundle) {
        Log.i("aiclk",TAG + ":onSkippedVideo");//激励视频跳过，提前点击关闭
        }
});
}

4.2 文案定制

根据业务特殊需求，可在请求时传入扩展字段extraBundle，比如：

xxxxxxxxxx
JSONObject jsonObject = new JSONObject();
        jsonObject.put("countdown_award_des", "可领金币");
        jsonObject.put("close_dialog_title", "任务提示");
        jsonObject.put("close_dialog_des", "观看完整广告可获得金币奖励");
        jsonObject.put("close_dialog_exit_des", "文案4");
        jsonObject.put("close_dialog_continue_btn_des","文案5");
        jsonObject.put("countdown_wait_des", "文案6");
        jsonObject.put("countdown_success_des","文案7");
        jsonObject.put("countdown_repeat_des","文案8");
        jsonObject.put("countdown_fail_des","文案9");
        jsonObject.put("countdown_icon_light_url","http://cdn.aiclk.com/nsdk/res/imgstatic/incite_video_coin_light.png");
        jsonObject.put("countdown_icon_gray_url","http://cdn.aiclk.com/nsdk/res/imgstatic/incite_video_coin_gray.png");
        extraBundle.putString("descriptions",jsonObject.toString());

文案参数解释

4.3 其他定制

xxxxxxxxxx
//自定义设置发放奖励时间，会在播放结束前给onReward回调
extraBundle.putInt("reward_time",10);

//cpc激励视频全屏（显示状态栏、标题栏），0：关闭  1：开启, 默认关闭
//extraBundle.putInt("fullscreen",1);

五、开屏广告

开屏类型请求时，adType传6

5.1 广告请求

xxxxxxxxxx
Bundle extBundle = new Bundle();
AdRequestParam requestParam = new AdRequestParam.Builder()
  .adslotID(getString(R.string.splash_ad))
  .adType(AdRequestParam.ADTYPE_SPLASH)
  .adLoadListener(new AdRequestParam.ADLoadListener() {

  @Override
  public void onADLoaded(IMultiAdObject adModel) {
    Log.i("aiclk", "onADLoaded:");
    Toast.makeText(SplashActivity.this, "广告加载成功", Toast.LENGTH_SHORT).show();
    if (adModel != null && adModel.isValid()) {
      //设置开屏广告回调接口
      adModel.setADStateListener(new IMultiAdObject.ADStateListener() {
        @Override
        public void onAdEvent(int i, @NonNull Bundle bundle) {
            if (i == ADEvent.EVENT_DOWNLOAD_DIALOG_SHOW) {
              //下载类型广告，点击出现下载合规弹窗回调
            } else if (i == ADEvent.EVENT_DOWNLOAD_DIALOG_DISMISS) {
              //下载类型广告，下载合规弹窗回调
            }
          }
        });
      
      adModel.showSplashView(mSplashContainer, new IMultiAdObject.SplashEventListener() {
        @Override
        public void onObClicked() {
          Log.i("aiclk", "onObClicked:");
          Toast.makeText(SplashActivity.this, "广告点击", Toast.LENGTH_SHORT).show();
        }

        @Override
        public void onObShow() {
          Log.i("aiclk", "onObShow:");
          Toast.makeText(SplashActivity.this, "广告展现", Toast.LENGTH_SHORT).show();
        }

        @Override
        public void onObSkip() {
         Log.i("aiclk", "onObSkip:");
         Toast.makeText(SplashActivity.this, "广告点击跳过", Toast.LENGTH_SHORT).show();
          goToMainActivity();
        }

        @Override
        public void onObTimeOver() {
         Log.i("aiclk", "onObTimeOver:");
         Toast.makeText(SplashActivity.this, "广告倒计时结束", Toast.LENGTH_SHORT).show();
         goToMainActivity();
        }
      });
    }
  }

  @Override
  public void onAdFailed(String errorMsg) {
    Log.i("aiclk", "onAdFailed:" + errorMsg);
    Toast.makeText(SplashActivity.this, "广告无填充", Toast.LENGTH_SHORT).show();
    goToMainActivity();
  }
})
.extraBundle(extBundle)
.build();

IMultiAdRequest multiAdRequest = AiClkAdManager.getInstance().createAdRequest();

if (multiAdRequest != null) {
  multiAdRequest.invokeADV(requestParam);
}

5.2 开屏定制

开屏跳过按钮及合规点击区域默认由趣盟sdk渲染，可通过后台配置隐藏

xxxxxxxxxx
//跳过按钮计时时间，默认5秒。推荐通过后台配置
extraBundle.putInt("countdown_time",5);

5.3 接口说明

IMultiAdObject.SplashEventListener 接口说明

六、插屏广告

6.1 广告请求

插屏类型请求时，adType传2

xxxxxxxxxx
private void requestInteractionAd(String adslotId) {
    AdRequestParam requestParam = new AdRequestParam.Builder()
            .adslotID(adslotId)
            .adType(AdRequestParam.ADTYPE_INTERACTION)
            .adLoadListener(new AdRequestParam.ADLoadListener() {

                @Override
                public void onADLoaded(IMultiAdObject adModel) {
                    Log.i("aiclk", "onADLoaded... ...");
                    String title = adModel.getTitle();
                    List<String> urls = adModel.getImageUrls();
                    Pair<Integer, Integer> mediaSize = adModel.getMediaSize();
                    int materialType = adModel.getMaterialType();
                    Log.i("aiclk", "title:" + title);
                    Log.i("aiclk", "urls:" + urls);
                    Log.i("aiclk", "materialType:" + materialType);
                    Log.i("aiclk", "mediaSize:" + mediaSize);
                    //展示插屏广告
                    showInteractionAd(adModel);

                }

                @Override
                public void onAdFailed(String errorMsg) {
                    Log.i("aiclk", "onAdFailed:" + errorMsg);
                }
            })
            .build();

    IMultiAdRequest multiAdRequest = AiClkAdManager.getInstance().createAdRequest();

    if (multiAdRequest != null) {
        multiAdRequest.invokeADV(requestParam);
    }
}

private void showInteractionAd(IMultiAdObject adModel) {
    if (adModel != null && adModel.isValid()) {
        adModel.showInteractionAd(MainActivity.this, new AdRequestParam.ADInteractionListener() {

            @Override
            public void onAdClick() {
                Log.i("aiclk", "onAdClick");
            }

            @Override
            public void onADExposed() {
                Log.i("aiclk", "onAdShow");

            }

            @Override
            public void onAdFailed(String s) {
                Log.i("aiclk", "onAdFailed: " + s);
            }

            @Override
            public void onAdClose(Bundle bundle) {
                String adslotId = bundle.getString("adslot_id", "");
                Log.i("aiclk", "onAdClose: " + adslotId);
            }
        });
    }
}

6.2 接口说明

AdRequestParam.ADInteractionListener 接口说明

6.3 关闭插屏广告

3.455.10.420 新增主动关闭插屏弹窗接口

示例：

xxxxxxxxxx
//关闭插屏广告
AiClkAdManager.getInstance().closeInteractionAd(adModel) 

七、竞胜竞败回传

3.445版本及以上开始支持回传

示例：

xxxxxxxxxx
adModel.winNotice(1000);
        adModel.lossNotice(100,ADEvent.PRICE_LOW,ADEvent.CSJ);

7.1 接口说明

IMultiAdObject 接口说明

ADEvent

xxxxxxxxxx
/**
 * 竞价失败原因
 * 100 底价过滤
 * 101 bid价格低于最高价
 * 102 素材黑名单过滤
 * 103 竞品过滤
 * 104 在有效时间内，未返回广告
 * >=1000  开发者和广告平台协商补充
 * 1001 缓存超时
 * 1002 超出上限被丟弃
 */
public static final String PRICE_FILTER = "100";
public static final String PRICE_LOW = "101";
public static final String BLACKLIST_FILTER = "102";
public static final String COMPETE_FILTER = "103";
public static final String TIMEOUT_FILTER = "104";

/**
 * 竞价失败原因
 * csj/toutiao  穿山甲
 * ylh/gdt  优量汇
 * kuaishou 快手
 * bqt/baidu  百青藤
 * sigmob sigmob
 * oppo oppo
 * vivo vivo
 * jingdong 京东
 * xiaomi 小米
 * zs 自售
 * other  其他家 （可以联系添加）
 * qumeng/qtt 趣盟
 */
public static final String CSJ = "toutiao";
public static final String GDT = "gdt";
public static final String KUAISHOU = "kuaishou";
public static final String BAIDU = "baidu";
public static final String SIGMOB = "sigmob";
public static final String OPPO = "oppo";
public static final String VIVO = "vivo";
public static final String JINGDONG = "jingdong";
public static final String XIAOMI = "xiaomi";
public static final String ZS = "zs";
public static final String OTHER = "other";
public static final String QUMENG = "qumeng";

八、GroMore聚合平台自定义广告接入文档

接入方式下载jar包集成（根据穿山甲版本选择其一)

穿山甲单独gromore版本：https://docs.qquanquan.com/android_sdk/gromore/1.0.4/gromore_qumeng_pangle_adapter.jar

穿山甲融合gromore版本：https://docs.qquanquan.com/android_sdk/gromore/1.0.5/gromore_qumeng_ronghe_adapter.jar

注：聚合版本可通过gromore的接口设置合规参数(TTAdConfig->setMediationConfig->getLocalExtra)

xxxxxxxxxx
@Override
public Map<String, Object> getLocalExtra() {
Map<String, Object> stringObjectMap = new HashMap<>();
ArrayList<PackageInfo> packageInfos = new ArrayList<>();
packageInfos.add(new PackageInfo());
stringObjectMap.put(QMCustomerConfig.MEDIA_APP_LIST,packageInfos);
stringObjectMap.put(QMCustomerConfig.MEDIA_IS_CAN_APP_LIST,true);
stringObjectMap.put(QMCustomerConfig.MEDIA_IS_CAN_ANDROID_ID,true);
stringObjectMap.put(QMCustomerConfig.MEDIA_KEY_ANDROID_ID,"");
stringObjectMap.put(QMCustomerConfig.MEDIA_OAID,"");
stringObjectMap.put(QMCustomerConfig.MEDIA_NEW_THREAD, 1) //异步初始化趣盟
return stringObjectMap;
}

自定义广告源adapter参数

8.1 添加广告平台

请求返回错误码

3.445版本及以上详细错误码

历史版本

常见问题 Q&A

Q1: 广告请求失败?

参考详细错误码。联系产品进行相关配置来提高填充率.

Q2: 广告栏位号如何申请?

广告栏位号要联系产品进行申请.

Q3: 初始化失败或构建请求为空？

1、检查混淆配置keep是否生效

2、检查androidx或非androidx版本集成是否有问题