菜单

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 内弹出弹窗。弹窗后的关闭弹窗、点击按钮等效果与创建的运营计划一致。



上一个
弹窗触达集成
下一个
iOS 弹窗集成
最近修改: 2024-12-27