集成 SDK 并初始化弹框插件
在使用弹窗插件前,请确保同步集成了 Web JS SDK,版本需要在 v1.15.25 及以上(弹窗 SDK v1.25.3 及以上,则 Web JS SDK 需要升级到 v1.17.2 及以上)详细集成步骤请参照 Web SDK 集成文档。
同步引入
<script src="在 github 下载新版本的 popup.min.js"></script>
<script charset='UTF-8' src="在 github 下载新版本的 sensorsdata.min.js"></script>
<script>
var sensors = window['sensorsDataAnalytic201505'];
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 模块化引入
requirejs(["./popup.amd","./sensorsdata.amd.min"], function(popup, sensors) {
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: ''
});
注意:
- 弹框插件根据屏幕宽度区分 H5 和 PC,屏幕宽度小于等于 1024 为 H5 端,否则为 PC 端。
- 弹框插件依赖 localStorage,浏览器必须支持 localStorage 才能使用弹框插件。
- 在 IE8 以下等不支持 localStorage 的浏览器中,不会获取弹框计划,不会触发弹框。
- 清除 localStorage 会导致弹窗的计划失效。
- 页面在手机上 App 中打开,清除手机 App 的清除缓存会清空保存在 localStorage 中的弹窗计划数据;
- 页面在浏览器中打开,清空浏览器的缓存也会导致清空保存在 localStorage 中的弹窗计划数据。
- H5 页面和内嵌 iframe 页面都集成弹框,则只有一个页面弹框,弹框页面按照代码加载顺序决定。
- H5 页面中有一个内嵌的 iframe 页面,H5 页面先加载弹框插件,则只会执行 H5 页面的弹框;
- iframe 页面先加载弹框插件,iframe 页面满足弹框触发条件,则会在 H5 页面中弹框;
- H5 页面非同域名下的 iframe 页面,不受以上逻辑限制,H5 页面弹框后,iframe 满足条件会在 iframe 中弹框。
- 在 SF 后台使用背景图片的模版,弹框插件需要 v0.2.3 及以上版本。
弹框初始化
初始化 init(arg)
使用 sensors.use('Popup') 进行Web 弹窗的初始化,参考代码如下:
// 初始化弹框插件
sensors.use('Popup', {
api_base_url: ''
});
参数配置:
- api_base_url:字符串类型,弹窗请求服务端的接口地址。
- popup_campaign_listener:对象类型,设置弹窗触达回调监听。
- shouldStart(SFCampaign):返回值决定弹窗是否可以触达,返回 true 可以触达,false 不触达。
- onStart(SFCampaign): 触达开始回调函数。
- onEnd(SFCampaign): 触达结束回调函数。
- onFailed(SFCampaign,errorCode,errorMessage): 触达失败回调函数。
- onClick(SFCampaign): 触达点击。
设置弹框回调
通过设置 popup_campaign_listener 接口,代码示例如下:
popup_campaign_listener: {
/*
* 由返回值决定弹窗是否可以触达,返回 true 可以触达,false 不触达
* @param SFCampaign
*/
shouldStart: function (SFCampaign) {
// do something...
},
/*
* 触达开始回调函数
* @param SFCampaign
*/
onStart: function (SFCampaign) {
// do something...
},
/*
* 触达点击
* @param SFCampaign 触达内容
*/
onClick: function (SFCampaign) {
// do something...
}, /*
* 触达结束回调函数
* @param SFCampaign
*/
onEnd: function (SFCampaign) {
// do something...
},
/*
* 触达失败回调函数
* @param SFCampaign
*/
onFailed: function (SFCampaign, errorCode, errorMessage) {
// do something...
}
}
设置弹窗是否触达回调
通过 shouldStart 函数返回值,可以控制弹窗是否可以触达,返回 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。
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 及以上版本
测试弹框
创建运营计划并测试弹窗
在神策智能运营中创建运营计划,并在配置好触达配置后,点击右侧的 “测试弹窗” 按钮。
扫二维码
输入框中输入页面地址,然后扫左侧的二维码
测试弹框效果
扫码后,会在浏览器中打开页面,并在页面内弹出弹窗。
弹窗后的关闭弹窗、点击按钮等效果与创建的运营计划一致。