集成 SDK 并初始化弹框插件

在使用弹窗插件前，请确保同步集成了 Web JS SDK，版本需要在 v1.15.25 及以上（弹窗 SDK v0.4.0 及以上，则 Web JS SDK 需要升级到 v1.17.2 及以上）详细集成步骤请参照 Web SDK 集成文档。

同步引入

<script src="在 github 下载新版本的 popup.min.js"></script>
<script charset='UTF-8' src="https://cdn.jsdelivr.net/npm/sa-sdk-javascript@1.15.15/sensorsdata.min.js"></script>
<script>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="3ee58087-b23d-4799-ac71-20d1155531b5"><ac:plain-text-body><![CDATA[ var sensors = window['sensorsDataAnalytic201505'];
]]></ac:plain-text-body></ac:structured-macro>
sensors.init({
server_url: 'http://test-syg.datasink.sensorsdata.cn/sa?token=27f1e21b78daf376&project=xxxxxx',
heatmap:{},
use_client_time:true,
send_type:'beacon'
});
// 初始化弹框插件
sensors.use('Popup', {
api_base_url: ''
});
sensors.quick('autoTrack');
</script>

AMD 模块化引入

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="5f374687-2f4a-4df6-8f11-bfb0100b9fcd"><ac:plain-text-body><![CDATA[

requirejs(["./popup.amd","./sensorsdata.amd.min"], function(popup, sensors) {
]]></ac:plain-text-body></ac:structured-macro>
sensors.init({
server_url: '...',
use_client_time:true,
send_type:'beacon',
heatmap:{
clickmap: 'default',
scroll_notice_map: 'not_collect'
}
});
sensors.quick('autoTrack');
sensors.use('Popup', {
api_base_url: ''
});
})

ES6 模块化引入

import popup from './popup.esm.js';
import sensors from './sensorsdata.es6.min.js';
sensors.init({
server_url: '...',
heatmap_url: "在 GitHub 下载新版本的 heatmap.min.js ",
use_client_time:true,
send_type:'beacon',
heatmap: {
clickmap:'default',
scroll_notice_map:'not_collect'
}
});
sensors.quick('autoTrack'); //用于采集 $pageview 事件
sensors.use('Popup', {
api_base_url: ''
});

注意：
1、弹框插件根据屏幕宽度区分 H5 和 PC，屏幕宽度小于等于 1024 为 H5 端，否则为 PC 端。
2、弹框插件依赖 localStorage，浏览器必须支持 localStorage 才能使用弹框插件。
具体场景：

例如在 IE8 以下等不支持 localStorage 的浏览器中，不会获取弹框计划，不会触发弹框。

3、清除 localStorage 会导致弹窗的计划失效。
具体场景：

页面在手机上 App 中打开，清除手机 App 的清除缓存会清空保存在 localStorage 中的弹窗计划数据；
页面在浏览器中打开，清空浏览器的缓存也会导致清空保存在 localStorage 中的弹窗计划数据。

4、H5 页面和内嵌 iframe 页面都集成弹框，则只有一个页面弹框，弹框页面按照代码加载顺序决定。
具体场景：

H5 页面中有一个内嵌的 iframe 页面，H5 页面先加载弹框插件，则只会执行 H5 页面的弹框；
iframe 页面先加载弹框插件，iframe 页面满足弹框触发条件，则会在 H5 页面中弹框；
H5 页面非同域名下的 iframe 页面，不受以上逻辑限制，H5 页面弹框后，iframe 满足条件会在 iframe 中弹框。

5、在 SF 后台使用背景图片的模版，弹框插件需要 v0.2.3 及以上版本。

弹框初始化

初始化 init(arg)

使用 sensors.use('Popup') 进行Web 弹窗的初始化，参考代码如下：

// 初始化弹框插件
sensors.use('Popup', {
api_base_url: ''
});

参数配置：

- api_base_url：字符串类型，弹窗请求服务端的接口地址。
- popup_listener：对象类型，弹窗的回调监听和 URL 链接跳转模式设置。
  - openlink：设置弹窗按钮行为是 "URL 链接"的跳转方式，设置为 "auto" 点击按钮会自动跳转，跳转方式为当前页面跳转。设置为 "customize" 点击按钮不会进行跳转，跳转行为需要在 onClick 函数中进行设置，默认是 "customize"。
  - onClick(planId,action): 弹窗元素点击的回调函数，参数有 planId: 计划 id、action: 按钮的行为描述信息。
  - onLoadSuccess(planId): 弹窗加载成功的回调函数，参数有 planId: 计划 id。
  - onLoadFailed(planId, code, message): 弹窗加载失败的回调函数，参数有 planId: 计划 id、code:错误码、message: 错误码对应的描述信息。
  - onClose(planId): 弹窗关闭的回调函数，参数有 planId: 计划 id。
- popup_campaign_listener：对象类型，设置弹窗触达回调监听。
  - shouldStart(SFCampaign)：返回值决定弹窗是否可以触达，返回 true 可以触达，false 不触达。
  - onStart(SFCampaign): 触达开始回调函数。
  - onEnd(SFCampaign): 触达结束回调函数。
  - onFailed(SFCampaign,errorCode,errorMessage)：触达失败回调函数。

设置弹框回调

通过设置 popup_listener 接口，代码示例如下：

popup_listener: {
/**
* 弹框中元素点击事件
* @param {string} planId 计划ID
* @param {Object} action 点击按钮的行为参数
*/
onClick: function(planId, action) {
// do something...
},
/**
* 弹框加载成功
* @param {string} planId 计划ID
*/
onLoadSuccess: function(planId) {
// do something...
},
/**
* 弹框加载失败
* @param {string} planId 计划ID
* @param {number} code 错误码
* @param {string} message 错误码对应的描述信息
*/
onLoadFailed: function(planId, code, message) {
// do something...
},
/**
* 弹框关闭
* @param {string} planId 计划ID
*/
onClose: function(planId) {
// do something...
}
}

设置弹框点击回调

弹窗点击时，会触发 popup_listener.onClick(planId, action) 回调，其中 planId 为计划 id，action 为行为描述，action 的格式如下：

{
"type": "customize",
"value": "",
"extra":{city:"北京"}
}

type：操作类型，支持的操作类型有三种：openlink(跳转链接)、customize(自定义链接)、close(关闭弹窗)。
value：跳转地址，type为 "openlink"，value 字段会返回跳转的链接地址。
extra：自定义的参数信息，type为"customize"，extra 字段会返回自定义的参数信息。

设置弹框成功回调

弹框成功时会触发 popup_listener.onLoadSuccess(planId) 回调函数，其中 planId 为计划 id。

设置弹框失败回调

弹框渲染失败会触发 popup_listener.onLoadFailed(planId, code, message) 回调函数，其中 planId 为计划 id，errorCode 为错误码，errorMessage 为错误信息。具体错误码对应信息如下：

错误码	描述信息
1000	图片加载失败
1001	预览信息解析失败，请检查计划配置

设置弹框关闭回调

弹框关闭时会触发 popup_listener.onClose(planId) 回调函数，其中 planId 为计划 id。

App 内嵌 H5

当 H5 页面内嵌到 App 中，并且开启 App 和 H5 的打通。
App 打通 H5 参考文档：https://manual.sensorsdata.cn/sa/latest/tech_sdk_client_link-7551956.html
App 内嵌 H5 弹框规则：

Web JS SDK 和 App 打通成功，创建 App 内嵌 H5 计划，埋点事件发给 App，由 App 进行弹框。

Web JS SDK 和 App 打通失败，H5 页面无法拉取 App 内嵌 H5 的计划，无法触发 App 内嵌 H5 计划的弹框。

弹窗 SDK 插件需要在 v0.2.3 及以上版本
Web JS SDK 需要在 v1.15.25 及以上版本
iOS SDK 需要在 v2.1.6 及以上版本
Android SDK 需要满足 v4.4.5 及以上版本
神策智能运营后台私有化部署在 v2.3 及以上版本
神策智能运营后台 SAAS 版在 v3.0 及以上版本

自定义触达

名词解释

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

API 使用

版本要求
H5 弹窗 SDK v0.4.0 及以上版本
Web JS SDK v1.17.2 及以上版本

新增 popup_campaign_listener 接口，代码示例如下：

popup_campaign_listener:{
/*
* 由返回值决定弹窗是否可以触达，返回 true 可以触达，false 不触达
* @param SFCampaign
*/
shouldStart:function(SFCampaign){
// do something...
},
/*
* 触达开始回调函数
* @param SFCampaign
*/
onStart:function(SFCampaign){
// do something...
},
/*
* 触达结束回调函数
* @param SFCampaign
*/
onEnd:function(SFCampaign){
// do something...
},
/*
* 触达失败回调函数
* @param SFCampaign
*/
onFailed:function(SFCampaign,errorCode,errorMessage){
// do something...
}
}

设置是否触达回调

通过 shouldStar 函数返回值，可以控制弹窗是否可以触达，返回 true 可以触达，返回 fasle 则表示不会触达。

/*
* 由返回值决定弹窗是否可以触达，返回 true 可以触达，false 不触达
* @param SFCampaign
*/
shouldStart:function(SFCampaign){
// do something...
}

设置触达开始回调

自定义触达依赖 popup_campaign_listener 参数的 onStart 回调，触达开始会执行 onStart 回调函数。

onStart:function(SFCampaign){
if(SFCampaign.type === 'CUSTOMIZED'){
console('自定义弹窗触达',SFCampaign.name);
}else{
console('预制弹窗触达',SFCampaign.name);
}
}

设置触达结束回调

触达结束 SDK 会调用 onEnd 回调函数，自定义触达结束不受 SDK 控制，所以自定义触达不执行 onEnd 回调函数。

onEnd:function(SFCampaign){
// do something...
}

设置触达失败回调

触达失败会执行 onFailed 回调函数，并且将错误码和错误信息作为参数传入回调函数中。

onFailed:function(SFCampaign,errorCode,errorMessage){
// do something...
}

回调参数说明

SFCampaign 是回调函数的参数，其类型是 Object ，具体格式：

{
planId: 'xx',// 计划 ID，为下发字段的 plan_id 获取，对于测试弹窗该字段为 undefined
name:'xx',// 计划名称，为下发字段的 cname 获取，对于测试弹窗该字段为 undefined
content:"{}" // 计划内容，为下发计划字段的 popup_window_content.content，为 JSON 字符串
type: 'xx' // 触达类型，为下发字段的 popup_window_content.popup_type，CUSTOMIZED 表示自定义触达，PRESET 表示预制弹窗。
}

onFailed 回调函数除 SFCampaign 参数外还有 errorCode 、errorMessage 参数，errorCode 错误码，errorMessage 错误信息。具体错误码对应信息如下：

错误码	错误信息
1001	预览信息解析失败，请检查计划配置
1003	对照组
1004	campaignShouldStart 接口返回 false
1005	计划下发 is_trigger 为 false
1006	自定义触达计划未实现弹窗生命周期回调

场景说明

预制弹窗会触发 popup_listener 的回调函数和 popup_campaign_listener 的回调函数。
自定义触达依赖 popup_campaign_listener 接口，必须实现 popup_campaign_listener.onStart，且自定义触达只触发 popup_campaign_listener 的回调函数。
自定义触达和预制弹窗都受 popup_campaign_listener 接口的 shouldStart 控制，shouldStart 返回 fasle 则只发送埋点、触发触达失败的回调函数，测试弹窗不受 campaignShouldStart 控制。
自定义触达关闭不受SDK控制，所以不会执行 popup_campaign_listener.onEnd 回调函数，预制弹窗关闭会执行 popup_campaign_listener.onEnd。

测试弹框

创建运营计划并测试弹窗

在神策智能运营中创建运营计划，并在配置好触达配置后，点击右侧的 "测试弹窗" 按钮。

扫二维码

输入框中输入页面地址，然后扫左侧的二维码

测试弹框效果

扫码后，会在浏览器中打开页面，并在页面内弹出弹窗。
弹窗后的关闭弹窗、点击按钮等效果与创建的运营计划一致。