菜单

Android 弹窗集成

集成 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.3'
}

弹窗 SDK 集成 Demo，可参考 GitHub。

初始化 SDK

首先您需要初始化初始化神策分析 SDK，具体可参考：初始化神策分析 SDK。

初始化神策分析 SDK 完成之后，再初始化神策分析弹窗 SDK。弹窗 SDK 和神策分析 SDK 都需要在 Application 类的 onCreate() 方法主线程初始化。在弹窗 SDK 初始化时需要传入弹窗服务端地址，请联系运营人员获取。

// 初始化神策分析 SDK
...

// 初始化神策弹窗 SDK
SFConfigOptions sfOptions = new SFConfigOptions("弹窗服务端地址")
SensorsFocusAPI.startWithConfigOptions(this, sfOptions);

延迟初始化 SDK 会导致弹窗计划拉取、前后台判断异常，从而会导致弹窗可能无法弹出。若 App 有合规需求，可参考 Android 合规步骤。

设置自定义占位图

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) {}
    }));


名词解释

名词解释 / 定义备注
自定义触达使用神策智能运营，满足运营条件后，客户可以自定义的触达方式，例如可以发券、弹窗、跳转、红包雨等等

API 使用

版本要求

  • Android SDK v5.2.7 及以上版本
  • 神策弹窗 SDK v0.6.3 及以上版本

禁用弹窗在闪屏页使用

初始化 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 接口替代。

API 说明

数据结构

SFCampaign 数据结构介绍：

名称类型说明
planIdString计划 ID，为下发字段的 plan_id 获取
nameString计划名称，为下发字段的 cname 获取
contentString计划内容，为下发计划字段的 popup_window_content 中的 content 字段
typeType触达类型，为 SDK 内枚举，PRESET 为预置弹窗，CUSTOMIZED 为自定义触达
actionSensorsFocusActionModel弹窗点击动作，为 SDK 内枚举，目前支持的操作有：关闭弹窗、跳转链接、复制文本、自定义链接。

SensorsFocusActionModel 类型介绍：

序号类型弹窗响应typevalueextra
1关闭弹窗

点击后弹窗关闭

SensorsFocusActionModel.CLOSEnullnull
2跳转链接

点击后弹窗关闭

SensorsFocusActionModel.OPEN_LINKURL 跳转链接null
3复制文本点击后弹窗不关闭SensorsFocusActionModel.COPY被复制的文本JSONObject
4自定义链接

点击后弹窗关闭

SensorsFocusActionModel.CUSTOMIZEnull自定义的 key-value


状态码说明

失败或成功状态码，失败时会回调 campaignFailed，并且触发的 $PlanPopupDisplay 的 $sf_succeed 为 false，$sf_fail_reason 值为失败原因。


触达接口调用情况发生情况失败原因（errorMessage）失败状态码 （errorCode）备注
1失败SensorsFocusCampaignListener 接口为空自定义触达计划未实现弹窗生命周期回调1006
2is_trigger 为 false计划下发 is_trigger 为 false1005
3campaignShouldStart 返回 falsecampaignShouldStart 接口返回 false1004
4对照组，旧版逻辑对照组1003旧版本兼容处理
5Activity 在后台，仅限弹窗，旧版逻辑内部记录失败原因为空字符串，不会传递给开发者1002

旧版本仍然会触发 $PlanPopupDisplay 为成功的事件（$sf_succeed 为 true，且没有 $sf_fail_reason 属性）

iOS 不会有这种情况，所以考虑的是 Android 保持现状，和之前一样的逻辑

6预览 JSON 信息解析失败，旧版逻辑预览信息解析失败，请检查计划配置1001
8成功展示弹窗--
9自定义触达--

弹窗测试

创建运营计划

首先在神策智能运营中创建运营计划，并且“触发条件”中的“平台类型”选择 Android，然后配置好“触达配置”就可以点击右侧的“测试弹窗”按钮以打开二维码。

扫描二维码

使用已安装了测试 App 的设备，通过手机自带的系统浏览器扫描二维码，扫码后会在浏览器中打开二维码对应的网页。

唤起 App

点击网页中的“前往 App 测试弹窗”按钮，若 App 已经成功集成 SDK 则会直接唤起 App 或提示询问是否唤起 App。如果不能正常打开 App，请强杀 App 后重试。

测试弹窗效果

跳转成功后，会在 App 内弹出弹窗。弹窗后的关闭弹窗、点击按钮等效果与创建的运营计划一致。



最近修改: 2024-12-27