菜单

Android 弹窗集成

集成 SDK

集成神策分析 SDK

在使用弹窗 SDK 前，请确保已经集成了神策分析 SDK，版本需要在 v5.2.7 及以上，详细集成步骤请参照 Android SDK 埋点集成使用帮助文档 。

如果使用多 module，请确保神策分析 SDK 和神策弹窗 SDK 在同一 module 中引入，或者确保引用神策弹窗 SDK 的 module 能引用到神策分析 SDK。

集成神策弹窗 SDK

在 build.gradle 文件中添加神策弹窗 SDK 依赖：

dependencies {
	//添加 SensorsFocus SDK 依赖
	implementation 'com.sensorsdata.analytics.android:SensorsFocusSDK:0.5.3'
}

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

初始化 SDK

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

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

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

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

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

配置 Scheme

关于 Scheme 的配置方法，参考：配置 Scheme。

实现弹窗回调

设置回调

在 SensorsFocusAPI 初始化时，可以通过 SFConfigOptions 的 setPopupListener 方法设置弹窗的回调监听。setPopupListener 提供了四个监听接口：

SensorsFocusAPI.startWithConfigOptions(this, new SFConfigOptions("弹窗服务端地址")
    .setPopupListener(new PopupListener() {
       
        @Override
        public void onPopupLoadSuccess(String planId) {}

        @Override
        public void onPopupLoadFailed(String planId, int errorCode, String errorMessage) {}

        @Override
        public void onPopupClick(String planId, SensorsFocusActionModel actionModel) {}

        @Override
        public void onPopupClose(String planId) {}
    }));
}

方法说明

设置弹窗加载成功回调

弹窗加载成功时，会触发 onPopupLoadSuccess(String planId) 方法，其中 planId 为计划 ID。

设置弹窗加载失败回调

弹窗失败时会触发 onPopupLoadFailed(String planId, int errorCode, String errorMessage) 方法，其中 planId 为计划 ID，errorCode 为错误码，errorMessage 为错误信息。

具体错误码对应信息如下：

错误码描述信息

1000

图片加载失败

1001

预览信息解析失败，请检查计划配置

设置弹窗按钮点击回调

弹窗点击时，会触发 onPopupClick(String planId, SensorsFocusActionModel actionModel) 方法，其中 planId 为计划 ID，actionModel 包含了后端配置弹窗的一些信息，具体含义如下：

字段弹窗点击后行为
SensorsFocusActionModel.CLOSE点击弹窗时就关闭弹窗
SensorsFocusActionModel.OPEN_LINK点击后打开一个链接，可通过 actionModel.getValue() 获取链接
SensorsFocusActionModel.COPY点击后复制文本内容，可通过 actionModel.getValue() 获取复制文本
SensorsFocusActionModel.CUSTOMIZE自定义行为，可通过 actionModel.getExtra() 获取自定义字段


示例代码如下：

public void onPopupClick(String planId, SensorsFocusActionModel actionModel) {
    switch (actionModel) {
        case OPEN_LINK:
            // 自定义处理打开链接操作
            String url = actionModel.getValue();
            Log.d("PopupClick", "url = " + url);
            break;
        case COPY:
            // 自定义处理复制操作
            String copyText = actionModel.getValue();
            Log.d("PopupClick", "copyText = " + copyText);
            break;
        case CLOSE:
            // 处理 close
            break;
        case CUSTOMIZE:
            // 处理自定义操作
            JSONObject customizeJson = actionModel.getExtra();
            break;
    }
}

设置弹窗被关闭回调

弹窗关闭时会触发 onPopupClose(String planId) 方法，其中 planId 为计划 ID。

弹窗自定义触达

名词解释

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

API 使用

版本要求

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

在初始化 SDK 时，实现 SensorsFocusCampaignListener 接口，即可使用自定义触达功能，示例代码如下：

SensorsFocusAPI.startWithConfigOptions(this, new SFConfigOptions(apiBaseUrl)
    .setCampaignListener(new SensorsFocusCampaignListener() {
		/**
         * 返回 bool 值决定触达是否开始
         */
        @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 onCampaignEnd(SFCampaign sfCampaign) {}
		/**
         * 触达失败时调用
         */
        @Override
        public void onCampaignFailed(SFCampaign sfCampaign, int errorCode, String errorMessage) {}
    })
    .setPopupListener(new PopupListener() {
        /**
         * 弹窗加载成功
         */
        @Override
        public void onPopupLoadSuccess(String planId) {}
		/**
         * 弹窗加载失败
         */
        @Override
        public void onPopupLoadFailed(String planId, int errorCode, String errorMessage) {}

        /**
         * 弹窗点击
         */
        @Override
        public void onPopupClick(String planId, SensorsFocusActionModel actionModel) {}

        /**
         * 弹窗关闭
         */
        @Override
        public void onPopupClose(String planId) {}
    }));

禁用弹窗在闪屏页使用

初始化 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 字段
typeSDK 内定义枚举 Type 触达类型，为 SDK 内枚举，PRESET 为预置弹窗，CUSTOMIZED 为自定义触达

状态码说明

失败或成功状态码，失败时会回调 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