集成 SDK
集成神策分析 SDK
在使用弹窗 SDK 前，请确保已经集成了神策分析 SDK，版本需要在 v6.7.0 及以上，详细集成步骤请参照 Android SDK 埋点集成使用帮助文档。
如果使用多 module，请确保神策分析 SDK 和神策弹窗 SDK 在同一 module 中引入，或者确保引用神策弹窗 SDK 的 module 能引用到神策分析 SDK。
集成神策弹窗 SDK
在 build.gradle 文件中添加神策弹窗 SDK 依赖：
dependencies {
//添加 SensorsFocus SDK 依赖
implementation 'com.sensorsdata.analytics.android:SensorsFocusSDK:0.6.6'
}弹窗 SDK 集成 Demo，可参考 GitHub。
初始化 SDK
首先您需要初始化初始化神策分析 SDK，具体可参考：初始化神策分析 SDK。
初始化神策分析 SDK 完成之后，再初始化神策分析弹窗 SDK。弹窗 SDK 和神策分析 SDK 都需要在 Application 类的 onCreate() 方法主线程初始化。在弹窗 SDK 初始化时需要传入弹窗服务端地址，请联系运营人员获取。
// 初始化神策分析 SDK
...
// 初始化神策弹窗 SDK
SFConfigOptions sfOptions = new SFConfigOptions("在线服务地址")
sfConfigOptions.enableSDHIDM("示例-11ee-aeff-525400d4186a", "示例-org-sep-10259");// 设置 accessToken 和 orgID，请设置自己环境的配置
SensorsFocusAPI.startWithConfigOptions(this, sfOptions);
- 延迟初始化 SDK 会导致弹窗计划拉取、前后台判断异常，从而会导致弹窗可能无法弹出。若 App 有合规需求，可参考 Android 合规步骤。
- SF 444 及以上版本，建议需接入弹窗 SDK 0.7.0 及以上版本并且需要设置在线网关相关配置（accessToken、orgID）
- 对于某些私部客户，orgID 和 accessToken 不是必选项，具体情况请联系神策技术同学来确认
设置自定义占位图
SDK 内部有预置的占位图逻辑，如果想设置自定义的占位图，可通过如下接口来设置
sfOptions.setPlaceholderResourceId(R.drawable.xxx); // xxx 代表图片在资源文件 res/drawable 目录下的名字同时，对于占位图不存放在 res/drawable 中或者非本地的， SDK 也提供了另外一种设置方式
sfOptions.setPlaceholderImage(bitmap); // 占位图的二进制数据，Bitmap 类型
- SDK 内部处理的占位图优先级为 setPlaceholderResourceId > setPlaceholderImage > 内置占位图
- SDK 版本号要求 >= 0.5.4
配置 Scheme
关于 Scheme 的配置方法，参考：获取 Scheme。
实现弹窗回调
在 SensorsFocusAPI 初始化时，可以通过 SFConfigOptions 的 setCampaignListener 方法设置弹窗的回调监听（SensorsFocusCampaignListener），提供了五个监听接口：
public interface SensorsFocusCampaignListener {
/**
* 准备触达
*
* @param sfCampaign sfCampaign
* @return true 表示准备好了，触达即将开始；false 表示不进行触达
*/
boolean campaignShouldStart(SFCampaign sfCampaign);
/**
* 触达开始
*
* @param sfCampaign 触达内容
*/
void onCampaignStart(SFCampaign sfCampaign);
/**
* 触达结束
*
* @param sfCampaign 触达内容
*/
void onCampaignEnd(SFCampaign sfCampaign);
/**
* 触达点击
*
* @param sfCampaign 触达内容
*/
void onCampaignClick(SFCampaign sfCampaign);
/**
* 触达失败
*
* @param sfCampaign 弹窗数据
* @param errorCode 错误码
* @param errorMessage 错误信息
*/
void onCampaignFailed(SFCampaign sfCampaign, int errorCode, String errorMessage);
}设置回调示例：
SensorsFocusAPI.startWithConfigOptions(this, new SFConfigOptions(apiBaseUrl)
.setCampaignListener(new SensorsFocusCampaignListener() {
@Override
public boolean campaignShouldStart(SFCampaign sfCampaign) {
//如果是自定义触达
if(SFCampaign.Type.CUSTOMIZED == sfCampaign.getType()){
try {
JSONObject jsonObject = new JSONObject(sfCampaign.getContent());
} catch (JSONException e) {
e.printStackTrace();
}
}else if(SFCampaign.Type.PRESET == sfCampaign.getType()){
}
return true;
}
@Override
public void onCampaignStart(SFCampaign sfCampaign) {}
@Override
public void onCampaignClick(SFCampaign sfCampaign) {
switch (sfCampaign.getAction()) {
case OPEN_LINK:
// 自定义处理打开链接操作
String url = sfCampaign.getAction().getValue();
Log.d(TAG, "url = " + url);
break;
case COPY:
// 自定义处理复制操作
Log.d(TAG, "copyText = " + sfCampaign.getAction().getValue());
Log.d(TAG, "copyTip = " + sfCampaign.getAction().getExtra().optString("copied_tip"));
break;
case CLOSE:
// 处理 close
Log.d(TAG, "关闭弹窗");
break;
case CUSTOMIZE:
// 处理自定义操作
JSONObject customizeJson = sfCampaign.getAction().getExtra();
Log.d(TAG, "customize" + customizeJson.toString());
break;
}
}
@Override
public void onCampaignEnd(SFCampaign sfCampaign) {}
@Override
public void onCampaignFailed(SFCampaign sfCampaign, int errorCode, String errorMessage) {}
}));数据结构
SFCampaign 数据结构介绍：
| 名称 | 类型 | 说明 |
| planId | String | 计划 ID，为下发字段的 plan_id 获取 |
| name | String | 计划名称，为下发字段的 cname 获取 |
| content | String | 计划内容，为下发计划字段的 popup_window_content 中的 content 字段 |
| type | Type | 触达类型，为 SDK 内枚举，PRESET 为预置弹窗，CUSTOMIZED 为自定义触达 |
| action | SensorsFocusActionModel | 弹窗点击动作，为 SDK 内枚举，目前支持的操作有：关闭弹窗、跳转链接、复制文本、自定义链接。 |
SensorsFocusActionModel 类型介绍：
| 序号 | 类型 | 弹窗响应 | type | value | extra |
|---|---|---|---|---|---|
| 1 | 关闭弹窗 | 点击后弹窗关闭 | SensorsFocusActionModel.CLOSE | null | null |
| 2 | 跳转链接 | 点击后弹窗关闭 | SensorsFocusActionModel.OPEN_LINK | URL 跳转链接 | null |
| 3 | 复制文本 | 点击后弹窗不关闭 | SensorsFocusActionModel.COPY | 被复制的文本 | JSONObject |
| 4 | 自定义链接 | 点击后弹窗关闭 | SensorsFocusActionModel.CUSTOMIZE | null | 自定义的 key-value |
状态码说明
失败或成功状态码，失败时会回调 campaignFailed，并且触发的 $PlanPopupDisplay 的 $sf_succeed 为 false，$sf_fail_reason 值为失败原因。
| 触达接口调用情况 | 发生情况 | 失败原因（errorMessage） | 失败状态码 （errorCode） | 备注 | |
|---|---|---|---|---|---|
| 1 | 失败 | SensorsFocusCampaignListener 接口为空 | 自定义触达计划未实现弹窗生命周期回调 | 1006 | |
| 2 | is_trigger 为 false | 计划下发 is_trigger 为 false | 1005 | ||
| 3 | campaignShouldStart 返回 false | campaignShouldStart 接口返回 false | 1004 | ||
| 4 | 对照组，旧版逻辑 | 对照组 | 1003 | 旧版本兼容处理 | |
| 5 | Activity 在后台，仅限弹窗，旧版逻辑 | 内部记录失败原因为空字符串，不会传递给开发者 | 1002 | 旧版本仍然会触发 $PlanPopupDisplay 为成功的事件（$sf_succeed 为 true，且没有 $sf_fail_reason 属性） iOS 不会有这种情况，所以考虑的是 Android 保持现状，和之前一样的逻辑 | |
| 6 | 预览 JSON 信息解析失败，旧版逻辑 | 预览信息解析失败，请检查计划配置 | 1001 | ||
| 8 | 成功 | 展示弹窗 | - | - | |
| 9 | 自定义触达 | - | - |
名词解释
| 名词 | 解释 / 定义 | 备注 |
|---|---|---|
| 自定义触达 | 使用神策智能运营，满足运营条件后，客户可以自定义的触达方式，例如可以发券、弹窗、跳转、红包雨等等 |
API 使用
版本要求
禁用弹窗在闪屏页使用
初始化 SF SDK 时通过 setDelayPopupActivity 接口设置禁止弹窗的闪屏页页面：
//初始化
HashSet<Class<?>> ignoreClass = new HashSet<>();
ignoreClass.add(SplashActivity.class);
SensorsFocusAPI.startWithConfigOptions(this, new SFConfigOptions(apiBaseUrl)
.setDelayPopupActivity(ignoreClass)如果设置启动事件为弹窗条件，那么弹窗可能会弹在闪屏页，会被主页遮盖，那么可以使用此 API，防止弹窗弹在闪屏页。enablePopup/enablePopup 接口在 v0.4.8 及以后版本已被设置过期，可使用 setDelayPopupActivity 接口替代。
弹窗测试
创建运营计划
首先在神策智能运营中创建运营计划，并且“触发条件”中的“平台类型”选择 Android，然后配置好“触达配置”就可以点击右侧的“测试弹窗”按钮以打开二维码。
扫描二维码
使用已安装了测试 App 的设备，通过手机自带的系统浏览器扫描二维码，扫码后会在浏览器中打开二维码对应的网页。
唤起 App
点击网页中的“前往 App 测试弹窗”按钮，若 App 已经成功集成 SDK 则会直接唤起 App 或提示询问是否唤起 App。如果不能正常打开 App，请强杀 App 后重试。
测试弹窗效果
跳转成功后，会在 App 内弹出弹窗。弹窗后的关闭弹窗、点击按钮等效果与创建的运营计划一致。