变现SDK Android接入文档

前言

• 本文档介绍 Android Studio 开发环境下基于 Maven 方式集成的步骤，请仔细阅读文档和 Demo 工程。
• 个推变现SDK可通过个推广告配置动态下发并展示广告，可精确查询投放信息等。
• 本文档适用SDK 版本：v2.3.0.0 及以后
• SDK最低版本: 17
• 目前支持以下广告SDK及推荐版本
• 单独集成个推变现SDK，包体积增量为：0.6MB左右。在此基础上集成其他第三方SDK，包体积增量参考下表：

• SDK资源包下载：请联系我们的技术支持：文档中心右侧“技术咨询”
• SDK资料包结构：打开下载的 SDK 资料包，资料包的详细结构如下：

GETUI_BX_ANDROID_SDK/
  |- 变现SDK接入文档.pdf
  |- 变现SDK权限说明.pdf
  |- README.pdf
  |- Demo 工程/
  |    |- BX_SDK_Demo_AS_official/ （AndroidStudio 标准集成 Demo 工程）

• 本文默认读者已经具有基础的 Android 知识，以及项目工程结构如下：

BX_SDK_Demo_AS_official/
    |- app/ （项目主模块）
    |    |- libs/ （第三方库）
    |    |- src/ （代码目录）
    |    |- build.gradle （模块级 gradle 文件）
    |- gradle/
    |- build.gradle （顶层 gradle 文件）
    |- settings.gradle
    | ......

注：其中 “......” 表示省略其他与本教程无关的内容，以下 “......” 表示相同意义，不再重复说明。

1. 创建个推应用

• 进入“开发者中心-应用管理”，点击“创建应用”。创建应用指南
• 点击应用配置，获取到相应的AppID信息。
• 在广告平台创建应用，获取广告平台的AppID，详见第三方平台聚合指南。

2. Maven 集成（推荐）

2.1. 在工程的根目录下的build.gradle文件中的 allprojects { } 中，添加如下代码:

maven {
 url "http://mvn.gt.igexin.com/nexus/content/repositories/releases/"
}

2.2. 在 app/build.gradle 文件中的 android.defaultConfig 下添加 manifestPlaceholders

manifestPlaceholders = [
   GETUI_APPID: "your GETUI_APPID",
   GT_INSTALL_CHANNEL: "your GT_INSTALL_CHANNEL",
   CSJ_APP_ID: "your CSJ_APP_ID", // 穿山甲官网申请
   GDT_APP_ID: "your GDT_APP_ID",  // 广点通官网申请
   INMOBI_APP_ID: "your INMOBI_APP_ID" // InMobi官网申请
]

2.3. 在app所在module的build.gradle文件中的 dependencies { } 中，添加如下代码:

// 变现SDK 核心库
implementation 'com.getui:bxsdk:2.3.0.0'
// 如果需要接入广点通SDK，需接入bxsdk-gdt
implementation 'com.getui:bxsdk-gdt:4.332.1202'
// 如果需要接入穿山甲SDK，需接入bxsdk-csj
implementation 'com.getui:bxsdk-csj:3.0.0.3'
// 如果需要接入Inmobi SDK，需接入bxsdk-inmobi、picasso
implementation 'com.getui:bxsdk-inmobi:7.4.4'
implementation 'com.squareup.picasso:picasso:2.71828'
// gtc 为个推公司公共代码库，如果已经接入的个推其他产品内已经包含 gtc ，则无需再次引入
implementation 'com.getui:gtc:3.1.0.0'

2.4. 适配 Android7.0 及以上:

如果您的应用需要在 Android7.0 及以上环境运行，请在 AndroidManifest 中添加如下代码：

穿山甲SDK

如果集成穿山甲SDK，请在AndroidManifest.xml配置如下参数：

<provider
 android:name="com.bytedance.sdk.openadsdk.TTFileProvider"
 android:authorities="${applicationId}.TTFileProvider"
 android:exported="false"
 android:grantUriPermissions="true">
    <meta-data
     android:name="android.support.FILE_PROVIDER_PATHS"
     android:resource="@xml/csj_file_paths" />
</provider>

并在项目结构下的 res 目录下添加一个 xml 文件夹，再新建一个csj_file_paths.xml的文件，文件内容如下：

<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <!--为了适配所有路径可以设置 path = "." -->
    <external-path name="tt_external_root" path="." />
    <external-path name="tt_external_download" path="Download" />
    <external-files-path name="tt_external_files_download" path="Download" />
    <files-path name="tt_internal_file_download" path="Download" />
    <cache-path name="tt_internal_cache_download" path="Download" />
</paths>

3. 初始化SDK

说明：

• 初始化变现SDK
• 请在主线程中调用，建议在Application

参数：

context：应用的 ApplicationContext

示例

BXManager.getInstance().init(context);

4. Debug模式

说明：

• 开启Debug模式，广告位配置默认过期，会在每次请求广告业务时向服务端请求最新的广告位配置
• 开启Debug模式，会影响性能，建议线上版本关闭Debug模式

参数：

• isDebug：是否打开Debug模式，默认关闭.

示例

BXManager.getInstance().setDebug(boolean isDebug);

5. 获取版本号

说明：

• 获取版本号

示例

BXManager.getInstance().getVersion();

6. Banner广告

说明：

• 初始化Banner广告

参数：

• activity：当前activity对象
• viewGroup：广告容器
• gtAdId: 个推广告Id
• bXConfig：配置项
• listener: 回调接口

调用示例：

BXConfig config = new BXConfig.Builder()
                //设置广告素材的高度（仅穿山甲有效）
                .setExpressViewHeight(300f)
                //设置广告素材的宽度（仅穿山甲有效）
                .setExpressViewWidth(500f)
                //设置请求超时时间，请求超时时间必须>=500毫秒，否则不会生效
                .setAdTimeOut(3000)
                .build();
BXManager.getInstance().startBannerAD(this,llAdContainer, "⼴告id", config, new BXBannerListener() {
        @Override
    public void loadError(int type, String message) {
            //加载失败，type是最终失败的广告渠道，例如type==BXConsts.TYPE_CSJ，则是穿山甲渠道
            Log.d(TAG,"loadError:"+message);
    }

    @Override
    public void loadSuccess(int type ,View bannerView) {
            //加载成功，type是最终失败的广告渠道，例如type==BXConsts.TYPE_CSJ，则是穿山甲渠道
            Log.e(TAG,"loadSuccess"+type);
    }

    @Override
    public void onAdShow() {
            //广告展示
            Log.d(TAG,"onAdShow");
    }

    @Override
    public void onAdClick() {
            //广告被点击
            Log.d(TAG,"onAdClick");
    }

    @Override
    public void onAdClosed() {
            //广告被关闭
            Log.d(TAG,"onAdClosed");
    }

    @Override
    public void onAdTimeOut() {
            //加载广告超时
            Log.d(TAG,"onAdTimeOut");
    }
});

BXBannerListener回调对象

public interface BXBannerListener {
        //加载失败
    void loadError(int type, String message);
    //加载成功
    void loadSuccess(int type,View bannerView);
    //广告展示
    void onAdShow();
    //广告被点击
    void onAdClick();
    //广告被关闭
    void onAdClosed();
    //广告加载超时
    void onAdTimeOut();
}

7. 开屏广告

说明：

• 初始化开屏广告

参数：

• activity：当前activity对象
• viewGroup：广告容器
• gtAdId: 个推广告Id
• bXConfig：配置项
• listener: 回调接口

示例

BXConfig config = new BXConfig.Builder()
                // 设置广告素材的高度（仅穿山甲有效）
                .setExpressViewHeight(300f)
                // 设置广告素材的宽度（仅穿山甲有效）
                .setExpressViewWidth(500f)
                // 设置请求超时时间，请求超时时间必须>=500毫秒，否则不会生效，建议开屏广告设置为5000ms
                .setAdTimeOut(5000)
                .build();
BXManager.getInstance().startSplashAD(this, container, "⼴告id", config, new BXSplashAdListener() {
        @Override
    public void loadError(int type, String message) {
            // 加载失败，type是最终失败的广告渠道，例如type==BXConsts.TYPE_CSJ，则是穿山甲渠道
            Log.d(TAG,"loadError:"+message);
    }

    @Override
    public void loadSucceed(int type) {
            // 加载成功，type是最终失败的广告渠道，例如type==BXConsts.TYPE_CSJ，则是穿山甲渠道
            Log.d(TAG,"loadSucceed"+type);
    }

    @Override
    public void onAdShow() {
            // 广告展示
            Log.d(TAG,"onAdShow");
    }

    @Override
    public void onAdClick() {
            //广告被点击
            Log.d(TAG,"onAdClick");
    }

    @Override
    public void onAdDismiss() {
            //广告被关闭
            Log.d(TAG,"onAdDismiss");
    }

    @Override
    public void onAdTimeOut() {
            //加载超时
            Log.d(TAG,"onAdTimeOut");
    }
});

BXSplashAdListener回调对象

public interface BXSplashAdListener {
    //加载失败
    void loadError(int type, String message);
    //加载成功
    void loadSucceed(int type);
    //广告展示
    void onAdShow();
    //广告被点击
    void onAdClick();
    //广告被关闭
    void onAdDismiss();
    //加载超时
    void onAdTimeOut();
}

8. 插屏广告

说明：

初始化插屏广告

参数：

• activity：当前activity对象
• gtAdId: 个推广告Id
• bXConfig：配置项
• listener: 回调接口

调用示例：

BXConfig config = new BXConfig.Builder()
                //设置广告素材的高度（仅穿山甲有效）
                .setExpressViewHeight(300f)
                //设置广告素材的宽度（仅穿山甲有效）
                .setExpressViewWidth(500f)
                //设置请求超时时间，请求超时时间必须>=500毫秒，否则不会生效
                .setAdTimeOut(3000)
                .build();
BXManager.getInstance().startInterstitialAD(this, "⼴告id", config, new BXInterstitialListener() {
        @Override
    public void loadError(int type, String message) {
            //加载失败
            Log.d(TAG,"当前渠道："+type+",loadError"+message);
    }

    @Override
    public void loadSuccess(int type,BXInterstitialAd bxInterstitialAd) {
            //加载成功
            Log.e(TAG,"loadSuccess:"+type);
            bxInterstitialAd.show();
       }

    @Override
    public void onAdShow() {
            //广告展示
            Log.e(TAG,"onAdShow");
    }

    @Override
    public void onAdClick() {
            //广告被点击
            Log.e(TAG,"onAdClick");
    }

    @Override
    public void onAdClosed() {
            //广告被关闭
            Log.e(TAG,"onAdClosed");
    }

    @Override
    public void onAdTimeOut() {
            //广告加载超时
            Log.e(TAG,"onAdTimeOut");
    }

    @Override
    public void onVideoComplete() {
            //全屏视频广告播放完成
            Log.e(TAG,"onVideoComplete");
    }

    @Override
    public void onSkippedVideo() {
            //全屏视频广告被跳过
            Log.e(TAG,"onSkippedVideo");
    }

    @Override
    public void onAdVideoBarClick() {
            //全屏视频广告广告相关的View被点击
            Log.e(TAG,"onAdVideoBarClick");
    }

});

BXInterstitialListener回调对象

public interface BXInterstitialListener {
        //广告加载失败
    void loadError(int type, String message);
    //广告加载成功
    void loadSuccess(int type ,BXInterstitialAd bxInterstitialAd);
    //广告被展示
    void onAdShow();
    //广告被点击
    void onAdClick();
    //广告被关闭
    void onAdClosed();
    //广告加载超时
    void onAdTimeOut();
    //全屏视频广告播放完成
    void onVideoComplete();
        //全屏视频广告被跳过
    void onSkippedVideo();
    //全屏视频广告广告相关的View被点击
    void onAdVideoBarClick();
}

9. 激励视频广告

说明：

• 初始化激励视频广告

参数：

• activity：当前activity对象
• gtAdId: 个推广告Id
• bXConfig：配置项
• listener: 回调接口

调用示例：

BXConfig config = new BXConfig.Builder()
                //设置广告素材的高度（仅穿山甲有效）
                .setExpressViewHeight(300f)
                //设置广告素材的宽度（仅穿山甲有效）
                .setExpressViewWidth(500f)
                //设置请求超时时间，请求超时时间必须>=500毫秒，否则不会生效
                .setAdTimeOut(5000)
                .build();
BXManager.getInstance().startRewardVideoAD(this, "⼴告id", config, new BXRewardVideoAdListener() {
        @Override
    public void loadError(int type, String message) {
            //加载失败
            Log.e(TAG,"loadError:"+message);
    }


    @Override
    public void loadSuccess(int type,BXRewardVideo bxRewardVideo) {
            //加载成功
            Log.e(TAG,"loadSuccess");
            //展示广告
            bxRewardVideo.show();
    }

    @Override
    public void onAdTimeOut() {
            //广告加载超时
            Log.e(TAG,"onAdTimeOut");
    }

    @Override
    public void onAdShow() {
            //广告被展示
            Log.e(TAG,"onAdShow");
    }

    @Override
    public void onAdClick() {
            //广告被点击
            Log.e(TAG,"onAdClick");
    }

    @Override
    public void onAdDismiss() {
            //广告被关闭
            Log.e(TAG,"onAdDismiss");
    }

    @Override
    public void onRewardVideoCached() {
            //广告被缓存成功
            Log.e(TAG,"onRewardVideoCached");
    }

    @Override
    public void onVideoComplete() {
            //广告视频播放完毕
            Log.e(TAG,"onVideoComplete");
            finish();
    }

    @Override
    public void onSkippedVideo() {
            //广告被点击跳过
            Log.e(TAG,"onSkippedVideo");
    }

    @Override
    public void onRewardVerify() {
            //视频广告播完验证奖励有效性回调
            Log.e(TAG,"onRewardVerify");
    }
});

BXRewardVideoAdListener回调对象

public interface BXRewardVideoAdListener {
    // 加载失败
    void loadError(int type, String message);
    //加载成功
    void loadSuccess(int type ,BXRewardVideo bxRewardVideo);
    // 超时
    void onAdTimeOut();
    // 展示
    void onAdShow();
    // 点击
    void onAdClick();
    // 广告关闭
    void onAdDismiss();
    // 视频缓存
    void onRewardVideoCached();
    // 播放完成
    void onVideoComplete();
    // 点击跳过
    void onSkippedVideo();
    // 视频广告播完验证奖励有效性回调
    void onRewardVerify();
}

10. 信息流广告

说明：

• 初始化信息流广告

参数：

• activity：当前activity对象
• gtAdId: 个推广告Id
• BXConfig：广告id
• listener: 回调接口

示例

BXConfig config = new BXConfig.Builder()
                //设置广告素材的高度（仅穿山甲有效）
                .setExpressViewHeight(300f)
                //设置广告素材的宽度（仅穿山甲有效）
                .setExpressViewWidth(500f)
                //设置请求超时时间，请求超时时间必须>=500毫秒，否则不会生效
                .setAdTimeOut(3000)
                .build();
BXManager.getInstance().startNativeAD(this, "⼴告id",config, new BXNativeAdListener() {
    @Override
    public void loadError(int type, String message) {
            //加载失败，type是最终失败的广告渠道，例如type==BXConsts.TYPE_CSJ，则是穿山甲渠道
            Log.d(TAG,"loadError");
    }

    @Override
    public void loadSuccess(int type,List<BXNativeAd> bxNativeAdList) {
        //加载成功，type是最终失败的广告渠道，例如type==BXConsts.TYPE_CSJ，则是穿山甲渠道
            Log.d(TAG,"loadError");  
    }

    @Override
    public void onAdTimeOut() {
               //加载超时
            Log.d(TAG,"onAdTimeOut");
    }

    @Override
    public void onAdClosed(BXNativeAd bxNativeAd) {
            //信息流广告被关闭
            Log.d(TAG,"onAdClosed"); 
    }

    @Override
    public void onAdShow() {
            //广告被展示
            Log.d(TAG,"onAdShow");
    }

    @Override
    public void onAdClick(BXNativeAd bxNativeAd) {
            //广告被点击
            Log.d(TAG,"onAdClick");
    }
});

BXNativeAdListener回调对象

public interface BXNativeAdListener {
    // 加载失败
    void loadError(int type,String message);
    // 加载成功
    void loadSuccess(int type ,List<BXNativeAd> bxNativeAdList);
    // 加载达到设置的超时时间，加载超时
    void onAdTimeOut();
    // 信息流广告被关闭
    void onAdClosed(BXNativeAd bxNativeAd);
    // 信息流广告被展示
    void onAdShow();
    // 信息流广告被点击
    void onAdClick(BXNativeAd bxNativeAd);
}

11. Draw信息流广告

说明：

• 初始化Draw信息流广告

参数：

• activity：当前activity对象
• gtAdId: 个推广告Id
• bXConfig：配置项
• listener: 回调接口

调用示例：

BXConfig config = new BXConfig.Builder()
                                //设置广告素材的高度（仅穿山甲有效）
                .setExpressViewHeight(300f)
                //设置广告素材的宽度（仅穿山甲有效）
                .setExpressViewWidth(500f)
                //设置请求超时时间，请求超时时间必须>=500毫秒，否则不会生效
                .setAdTimeOut(3000)
                .build();
BXManager.getInstance().startDrawAD(this, "⼴告id", config, new BXDrawListener() {
        @Override
        public void loadError(int type, String message) {
                //加载失败
            Log.d(TAG,"loadError："+message);
    }

    @Override
    public void loadSuccess(int type, List<BXDrawAd> bxDrawAdList) {
            //加载成功
            Log.d(TAG,"loadSuccess");
        BXDrawAd bxDrawAd =bxDrawAdList.get(0);
        //渲染广告
        bxDrawAd.render();
    }

    @Override
    public void onAdTimeOut() {
            //加载广告超时
            Log.d(TAG,"onAdTimeOut");
    }

    @Override
    public void onAdClicked(View view, int type) {
            //广告被点击
            Log.d(TAG,"onAdClicked");
    }

    @Override
    public void onAdShow(View view, int type) {
            //广告被展示
            Log.d(TAG,"onAdShow");
    }

    @Override
    public void onRenderFail(View view, String msg, int code) {
            //广告渲染失败
            Log.d(TAG,"onRenderFail");
    }

    @Override
    public void onRenderSuccess(View view, float width, float height) {
            //广告渲染成功
            Log.d(TAG,"onRenderSuccess");
     }
});

BXDrawListener回调对象

public interface BXDrawListener {
    //加载失败
    void loadError(int type, String message);
    //加载成功
    void loadSuccess(int type, List<BXDrawAd> bxDrawAdList);
    //超时
    void onAdTimeOut();
        //广告被点击
    void onAdClicked(View view, int type);
        //广告被展示
    void onAdShow(View view, int type);
        //广告渲染失败
    void onRenderFail(View view, String msg, int code);
        //广告渲染成功
    void onRenderSuccess(View view, float width, float height);
}

12. 按钮广告

说明：

• 初始化按钮广告

参数：

• activity：当前activity对象
• adContainer: 承载按钮广告按钮容器
• gtAdId: 个推广告Id
• listener: 回调接口

示例

BXManager.getInstance().startButtonAd(activity, adContainer, "广告id", new BXButtonListener() {
            @Override
            public void onAdShow() {
                // 按钮广告展示回调
                Log.d(TAG,"onAdShow");
            }

            @Override
            public void onAdFailed(int type,String msg) {
                // 按钮广告加载失败回调
                Log.d(TAG,"onAdFailed");
            }

            @Override
            public void onAdClicked() {
                // 按钮广告被点击回调
                Log.d(TAG,"onAdClicked");
            }
});

BXButtonListener回调对象

public interface BXButtonListener {
    //⼴告展示
    void onAdShow();
    //⼴告加载失败
    void onAdFailed(int type,String msg);
    //⼴告点击
    void onAdClicked();
}

13. 浮标广告

说明：

• 初始化浮标广告

参数：

• activity：当前activity对象
• adContainer: 承载浮标广告按钮容器
• gtAdId: 个推广告Id
• listener: 回调接口

示例

BXManager.getInstance().startFloatAd(activity, adContainer, "广告id", new BXButtonListener() {
            @Override
            public void onAdShow() {
                //浮标广告展示回调
                Log.d(TAG,"onAdShow");
            }

            @Override
            public void onAdFailed(int type,String msg) {
                //浮标广告加载失败回调
                Log.d(TAG,"onAdFailed");
            }

            @Override
            public void onAdClicked() {
                //浮标广告被点击回调
                Log.d(TAG,"onAdClicked");
            }

BXButtonListener回调对象

public interface BXButtonListener {
    //⼴告展示
    void onAdShow();
    //⼴告加载失败
    void onAdFailed(int type,String msg);
    //⼴告点击
    void onAdClicked();
}

14. 自渲染广告

说明：

初始化自渲染广告

参数：

• activity：当前activity对象
• adContainer: 将自渲染广告事件注册到该View或List
• gtAdId: 个推广告Id
• listener: 回调接口

示例

BXManager.getInstance().startAdvanceFeedAD(activity, view, "广告id", new BXAdvanceFeedListener() {
            @Override
            public void onLoadAd() {
                //加载自渲染广告完成
                Log.d(TAG,"onLoadAd");
            }

            @Override
            public void onAdFailed(int type,String msg) {
                //加载自渲染广告失败
                Log.d(TAG,"onAdFailed");
            }

            @Override
            public void onAdClicked(View view) {
                //绑定自渲染广告的view被点击
                Log.d(TAG,"onAdClicked");
            }
});

BXAdvanceFeedListener回调对象

public interface BXAdvanceFeedListener {
    //加载自渲染广告完成
    void onLoadAd();
     //加载自渲染广告失败
    void onAdFailed(int type,String msg);
    //绑定自渲染广告的view被点击
    void onAdClicked(View view);
    // 自渲染广告显示
    void onAdShow();
}

15. 设置标签

说明：

设置标签

参数：

• tags：需要设置的标签数组。注意：单个Tag的最大字符串长度为64个字符，且不能包含以下特殊字符（",","|","｜","空格","回车"等）；单次上传Tag的数组最大长度为10个Tag；
• bxTagListener: 标签设置结果的回调

示例

BXTag[] tags = new BXTag[5];
String[] tagName = new String[]{"tag1","tag2","tag3"};
for (int i = 0;i<tagName.length;i++){
        BXTag bxTag = new BXTag();
        bxTag.setName(tagName[i]);
      tags[i] = bxTag;
}
BXManager.getInstance().setTag(tags, new BXTagListener() {
        @Override
    public void onResult(int resultCode,String resultMsg) {
            Log.d("TAG","TAG组设置结果:"+resultMsg);
    }
});

16. 获取gtcID

说明：

获取GTC ID

BXAdvanceFeedListener回调对象

public interface BXTagListener {
        // Tag结果设置的回调
    void onResult(int resultCode,String resultMessage);
}

resultCode说明