设置和调试
您可能需要使用OneSignalDeferred.push(async function() { ... })
来封装您的 OneSignal 调用
您可以在 function()
中添加任意数量的方法。
OneSignal SDK 通过在您的页面上添加 defer
属性来加载。例如:
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
这意味着 OneSignal 代码将在 HTML 文档完全解析后执行,防止 OneSignal SDK 阻塞网站。然而,这会对依赖 OneSignalDeferred
变量存在的页面脚本产生问题。要解决这个问题,当您将 OneSignal 添加到您的网站时,应该以以下内容开始:
window.OneSignalDeferred = window.OneSignalDeferred || [];
这创建了一个 OneSignalDeferred
变量,如果 OneSignal 已经加载,则将其分配给已加载的实例。否则,OneSignal 变量等于一个空数组 - []
。
所有数组都有一个 .push() 函数
,因此在这一点上,OneSignalDeferred
变量只是我们推送函数到其中的一个函数数组。当 SDK 最终加载时,SDK 处理到目前为止推送的所有函数并重新定义 .push()。
init()
初始化 OneSignal SDK。这应该在您网站每个页面的 <head>
标签中调用一次。ONESIGNAL_APP_ID
可以在 密钥和ID 中找到。
如果您想延迟 OneSignal SDK 的初始化,我们建议使用我们的隐私方法。
初始化选项仅适用于自定义代码设置。否则,这些将在 OneSignal 仪表板中配置。
Parameter | Type | Description |
---|---|---|
appId | String | Required: Your OneSignal App ID found in Keys & IDs. |
requiresUserPrivacyConsent | Boolean | Delays SDK initialization until the user provides privacy consent. Must call setConsentGiven() to complete setup. |
safari_web_id | String | The Safari Web ID for your uploaded Safari .p12 certificate. Web Quickstart. |
promptOptions | Object | 自定义权限提示。下面的详细信息。 |
notifyButton | Object | 启用和配置订阅铃铛。下面的详细信息。 |
welcomeNotification | Object | 自定义或禁用欢迎通知。下面的详细信息。 |
persistNotification | Boolean | Chrome(仅限桌面)- true :通知持续存在直到点击,false :短时间后消失。Firefox/Safari 忽略此设置。 |
webhooks | Object | 配置事件回调。查看 Webhooks。 |
autoResubscribe | Boolean | 推荐: 自动为清除浏览器缓存或迁移到 OneSignal 的用户重新订阅。如果在代码中使用,会覆盖仪表板设置。 |
notificationClickHandlerMatch | String | "exact" (默认):聚焦具有精确URL匹配的标签页。"origin" :聚焦具有相同域的任何标签页。 |
notificationClickHandlerAction | String | "navigate" (默认):导航到 launchURL 。"focus" :聚焦现有标签页(仅与 "origin" 匹配一起使用)。 |
serviceWorkerParam | Object | 设置服务工作线程的 scope 。如果适用,必须与其他服务工作线程的范围不同。示例:{ scope: "/myPath/myCustomScope/" } |
serviceWorkerPath | String | 设置 OneSignal 服务工作线程文件的位置。示例:"myPath/OneSignalSDKWorker.js" |
promptOptions
parameters
使用 promptOptions
来本地化或自定义用户权限提示。所有字段都是可选的。
Parameter | Type | Description |
---|---|---|
slidedown | Object | 包含一个带有配置选项的 prompts 数组。 |
prompts | Array of Objects | 提示配置数组。示例:"slidedown": { "prompts": [{...}, {...}] } |
type | String | 提示类型:
|
autoPrompt | Boolean |
|
delay | Object | 控制何时显示自动提示:{ pageViews: 3, timeDelay: 20 } = 在第三次页面浏览和等待20秒后显示。 |
text | Object | 自定义文本选项:
|
categories | Array of Objects | 仅适用于 type: category 。每个对象包括:tag :内部键label :用户可见名称示例: [ {tag: "local_news", label: "Local News"} ] 。参见数据标签。 |
notifyButton
parameters
配置页面上显示的订阅铃铛(通知按钮)。
Parameter | Type | Description |
---|---|---|
enable | Boolean | Enables the Subscription Bell. Disabled by default. |
displayPredicate | Function | 返回 true 或 false 以显示/隐藏铃铛的自定义函数(或 Promise)。显示时评估一次。 |
size | String | 'small' 、'medium' 或 'large' 。订阅后缩小到 'small' 。 |
position | String | 'bottom-left' 或 'bottom-right' 。 |
offset | Object | CSS 像素偏移量:{ bottom: '50px', left: '10px' } |
prenotify | Boolean | 如果为 true ,显示”1 未读”图标和自定义悬停文本。 |
showCredit | Boolean | 设置为 false 可隐藏弹出窗口中的”Powered by OneSignal”。 |
text | Object | 铃铛 UI 的自定义文本。 |
welcomeNotification
parameters
自定义首次订阅后发送的欢迎通知。
Parameter | Type | Description |
---|---|---|
disable | Boolean | Disable welcome notification. |
message | String | 必需: 通知消息。如果为空,默认为 'Thanks for subscribing!' 。 |
title | String | 通知标题。默认为站点标题。使用 ' ' (空格)移除(不推荐)。 |
url | URL | 用户点击通知时打开的可选 URL。通常不需要。 |
Example:
setLogLevel()
设置日志记录以在控制台打印额外的日志。更多详情请参见使用浏览器开发工具调试。
JavaScript
'trace'
'debug'
'info'
'warn'
'error'
用户身份和属性
当您的用户在您的网站上订阅推送通知时,OneSignal 会自动创建一个 OneSignal ID(用户级)和一个订阅 ID(设备级)。您可以通过使用您的唯一用户标识符调用login()
来将多个订阅(例如设备、电子邮件、电话号码)与单个用户关联。
login(external_id)
将用户上下文设置为提供的 external_id
。确保与此 external_id
关联的所有订阅和属性在单个 onesignal_id
下统一。更多详情请参见用户。
Key behaviors:
- 如果
external_id
已经存在,SDK 会切换到该用户。登录前收集的匿名数据不会合并,将被丢弃。 - 如果
external_id
不存在,本地状态将在当前onesignal_id
下保存。用户匿名时收集的任何数据都将保留。 - SDK 在网络故障或服务器错误时会自动重试。
logout()
取消当前用户与订阅的关联。
- 从当前推送订阅中删除
external_id
。 - 将 OneSignal ID 重置为新的匿名用户。
- 任何新数据(例如标签、订阅、会话数据等)现在都将在新的匿名用户上设置,直到他们通过
login
方法被识别。
当用户从您的应用程序注销时,如果您想将订阅设置为新的匿名用户,请使用此方法。
JavaScript
OneSignal.User.onesignalId
检索当前的 OneSignal ID。如果在用户状态初始化之前调用,可能为 null
。请使用用户状态 addObserver()
来监听用户状态变更。
JavaScript
OneSignal.User.externalId
检索当前的外部 ID。如果未设置或在用户状态初始化之前调用,可能为 null
。请使用用户状态 addObserver()
来监听用户状态变更。
JavaScript
addEventListener()
User State
监听用户上下文的变更(例如登录、退出、ID 分配)。
JavaScript
addAlias()
, addAliases()
, removeAlias()
, removeAliases()
别名是替代标识符(如用户名或 CRM ID)。
- 在添加别名之前,请使用
login()
设置external_id
。添加到没有external_id
的订阅的别名将不会在多个订阅中同步。 - 详情请参见别名。
JavaScript
getLanguage()
, setLanguage()
获取和/或覆盖用户的自动检测语言。可用语言代码列表请参见多语言消息。
JavaScript
自定义事件
通过自定义事件触发旅程和等待步骤激活。自定义事件仍在测试阶段,需要以下版本的 SDK 从您的网站触发:
- Web SDK,从
160500
开始可用
name
- 必需。 事件名称的字符串。properties
- 可选。 要添加到事件的键值对。属性字典或映射必须可序列化为有效的 JSON 对象。
os_sdk
下将特定于应用的数据包含到属性负载中,供消费。例如,要按设备类型面向事件,您可以访问 os_data.device_type
。
json
trackEvent()
JavaScript
数据标签
标签是您根据事件或用户属性在用户上设置的自定义key : value
字符串数据对。更多详情请参见数据标签。
addTag()
, addTags()
在当前用户上设置单个或多个标签。
- 如果键已经存在,值将被替换。
- 超出您的计划标签限制将导致操作静默失败。
JavaScript
removeTag()
, removeTags()
从当前用户中删除单个或多个标签。
JavaScript
getTags()
返回用户标签的本地副本。标签在 login()
或新应用会话期间从服务器更新。
JavaScript
隐私
setConsentRequired()
在开始数据收集之前强制用户同意。必须在初始化 SDK 之前调用。
此方法与在 init
方法中添加 requiresUserPrivacyConsent: true
相同。
JavaScript
setConsentGiven()
授予或撤销用户对数据收集的同意。没有同意,不会向 OneSignal 发送数据,也不会创建订阅。
- 如果
setConsentRequired()
或requiresUserPrivacyConsent
设置为true
,我们的 SDK 将不会完全启用,直到使用true
调用setConsentGiven
。 - 如果
setConsentGiven
设置为true
并创建了订阅,然后将其设置为false
,该订阅将不再接收更新。该订阅的当前数据保持不变,直到setConsentGiven
再次设置为true
。 - 如果您想删除用户和/或订阅数据,请使用我们的删除用户或删除订阅 API。
JavaScript
订阅
更多详情请参见订阅。User.PushSubscription.id
返回当前推送订阅 ID。如果调用得太早,可能返回 null
。建议在订阅观察器中获取此数据以响应变更。
JavaScript
User.PushSubscription.token
返回当前推送订阅令牌。如果调用得太早,可能返回 null
。建议在订阅观察器中获取此数据以响应变更。
JavaScript
addEventListener()
push subscription changes
使用此方法响应推送订阅变更,如:
- 设备从 Google (FCM) 或 Apple (APNs) 接收新推送令牌
- OneSignal 分配订阅 ID
optedIn
值发生变更(例如调用optIn()
或optOut()
)- 用户在系统设置中切换推送权限,然后打开应用
onPushSubscriptionChange
事件。您的监听器会接收一个状态对象,包含 previous
和 current
值,因此您可以准确检测发生了什么变更。
要停止监听更新,请调用相关的 removeObserver()
或 removeEventListener()
方法。
JavaScript
optOut()
, optIn()
, optedIn
控制当前推送订阅的订阅状态(subscribed
或 unsubscribed
)。使用这些方法来控制您网站上的推送订阅状态。常见用例:1)防止向注销的用户发送推送。2)在您的网站内实施通知偏好中心。
optOut()
:将当前推送订阅状态设置为取消订阅(即使用户有有效的推送令牌)。optIn()
:执行三个操作之一:- 如果订阅有有效的推送令牌,将当前推送订阅状态设置为
subscribed
。 - 如果订阅没有有效的推送令牌,尝试显示推送权限提示。
- 如果订阅有有效的推送令牌,将当前推送订阅状态设置为
optedIn
:如果当前推送订阅状态为已订阅,则返回true
,否则返回false
。如果推送令牌有效但调用了optOut()
,将返回false
。
JavaScript
addEmail()
, removeEmail()
为当前用户添加或删除电子邮件订阅(电子邮件地址)。在 login()
之后调用 addEmail
以设置正确的用户上下文。与身份验证兼容。
JavaScript
addSms()
, removeSms()
为当前用户添加或删除 SMS 订阅(电话号码)。需要 E.164 格式。在 login()
之后调用 addSms
以设置正确的用户上下文。与身份验证兼容。
JavaScript
滑动提示
在您的网站上显示各种滑动提示。更多详情请参见网页权限提示。- 如果被关闭,未来的调用将在至少三天内被忽略。进一步拒绝将延长再次提示用户之前所需的时间。
- 要覆盖退让行为,请向方法传递
{force: true}
。然而,为了提供良好的用户体验,请将操作绑定到 UI 启动的事件(如按钮点击)。
这不会替换订阅所需的原生浏览器提示。您必须使用原生浏览器提示获得权限。
promptPush()
显示推送通知的常规滑动提示。
- 如果使用类别,请改为调用
promptPushCategories()
。 - 遵循 OneSignal 设置的退让逻辑。更多详情请参见网页权限提示。
JavaScript
promptPushCategories()
显示类别滑动提示,允许用户更新他们的标签。如果用户尚未授予权限,还会触发原生通知权限提示。
- 如果不使用类别,请改为调用
promptPush()
。 - 遵循 OneSignal 设置的退让逻辑。更多详情请参见网页权限提示。
JavaScript
promptSms()
显示 SMS 订阅提示。
- 遵循 OneSignal 设置的退让逻辑。更多详情请参见网页权限提示。
JavaScript
promptEmail()
显示电子邮件订阅提示。
- 遵循 OneSignal 设置的退让逻辑。更多详情请参见网页权限提示。
JavaScript
promptSmsAndEmail()
同时显示 SMS 和电子邮件订阅提示。
- 遵循 OneSignal 设置的退让逻辑。更多详情请参见网页权限提示。
JavaScript
addEventListener()
Slidedown
添加回调以检测滑动提示显示事件。
JavaScript
推送通知
requestPermission()
通过原生浏览器提示请求推送通知权限。遵循浏览器设置的退让逻辑。更多详情请参见网页权限提示。
JavaScript
isPushSupported()
如果当前浏览器支持网页推送,则返回 true
。
JavaScript
OneSignal.Notifications.permission
返回一个布尔值,指示网站当前显示通知的权限。
true
:用户已授予显示通知的权限。false
:用户已拒绝或尚未授予显示通知的权限。
optOut
状态或订阅 ID 和推送令牌的存在,请参见 OneSignal.User.PushSubscription
。
要监听权限变更,请使用 permissionChange
事件。
JavaScript
addEventListener()
notifications
您可以通过将事件处理程序附加到通知事件来接入通知生命周期。调用 addEventListener
允许您为通知事件添加任意数量的事件处理程序。
要停止监听事件,请调用相关的 removeEventListener()
方法。
JavaScript
permissionChange
当用户点击允许或阻止或关闭浏览器的原生权限请求时,发生此事件。
JavaScript
permissionPromptDisplay
当浏览器的原生权限请求刚刚显示时,发生此事件。
JavaScript
click
当点击通知的主体/标题或操作按钮时,将触发此事件。
JavaScript
foregroundWillDisplay
此事件在通知显示之前发生。此事件在您的页面上触发。如果在您的网站上打开了多个浏览器标签页,此事件将在 OneSignal 活跃的所有页面上触发。
JavaScript
dismiss
此事件在以下情况下发生:
- 用户故意关闭通知而不点击通知主体或操作按钮
- 在 Android 上的 Chrome 中,用户关闭所有网页推送通知(此事件将为我们显示的每个网页推送通知触发)
- 通知自行过期并消失
如果用户点击通知主体或某个操作按钮,此事件不会发生。这被视为通知
click
事件。JavaScript
setDefaultUrl()
设置通知的默认 URL。
如果您未设置默认 URL,您的通知默认将打开到您网站的根目录。
JavaScript
setDefaultTitle()
设置在通知上显示的默认标题。
JavaScript
结果
sendOutcome()
触发可在 OneSignal 仪表板中查看的结果。接受结果名称(string
,必需)和值(number
,可选)。每次使用相同的结果名称调用 sendOutcome
方法时,结果计数将增加,并且结果值将按传入的量增加(如果包含)。更多详情请参见自定义结果。
JavaScript
sendUniqueOutcome()
触发可在 OneSignal 仪表板中查看的结果。仅接受结果名称(string
,必需)。sendUniqueOutcome
将仅为每个用户将该结果的计数增加一次。更多详情请参见自定义结果。
JavaScript