设置和调试
您可能需要将 OneSignal 调用封装在OneSignalDeferred.push(async function (OneSignal) { ... }) 中(当您不需要 await 时使用 function (OneSignal) { ... })。OneSignal 参数是本参考中通篇使用的 SDK 实例(例如 await OneSignal.init({ ... }))。
您可以推送多个回调,或将多条语句放在一个回调中。
OneSignal SDK 通过在您的页面上添加 defer 属性来加载。例如:
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
这样 SDK 会在文档解析完成后运行,不会阻塞渲染。较早运行的脚本仍然需要一个地方来排队任务,直到 SDK 就绪。请以以下内容开始:
window.OneSignalDeferred = window.OneSignalDeferred || [];
如果 OneSignalDeferred 不存在,这行代码会定义它。如果页面上较早的代码片段已经设置了它,则保持相同的引用;否则它以一个空数组 [] 开始,供您推送回调。
数组暴露了 .push() 方法,因此您可以使用 OneSignalDeferred.push(...) 将函数入队。当 SDK 加载后,它会处理队列并重新定义 .push(),使之后的推送立即运行(参见 Web SDK 源码)。
下面的大多数代码片段单独使用
OneSignal。请将其视为您的延迟回调中 await OneSignal.init({ ... }) 之后的实例,除非某节另有说明(例如在 init 之前的 setConsentRequired())。init()
初始化 OneSignal SDK。这应该在您网站每个页面的 <head> 标签中调用一次。ONESIGNAL_APP_ID 可以在密钥和 ID 中找到。
如果您想延迟 OneSignal SDK 的初始化,我们建议使用我们的隐私方法。
promptOptions parameters
使用 promptOptions 来本地化或自定义用户权限提示。所有字段都是可选的。
结构:promptOptions.slidedown.prompts 是一个数组;每个元素是一个提示配置。type、autoPrompt、delay、text 和 categories 字段属于 prompts 内的每个对象,而不是 init 中与 appId 并列的顶级键。
notifyButton parameters
配置页面上显示的订阅铃铛(通知按钮)。
welcomeNotification parameters
自定义首次订阅后发送的欢迎通知。
Example:
setLogLevel()
设置日志记录以在控制台打印额外的日志。更多详情请参见故障排除步骤。请在 init 之后从延迟回调中运行(与其他地方相同的 OneSignal 实例)。
JavaScript
'trace''debug''info''warn''error'
用户身份和属性
当用户在您的网站上订阅推送通知时,OneSignal 会自动创建一个 OneSignal ID(用户级 ID)和一个订阅 ID(设备级 ID)。您可以通过使用您的唯一用户标识符调用login(),将多个订阅(例如设备、电子邮件、电话号码)与单个用户关联。
login(external_id)
将当前用户上下文设置为提供的 external_id。这会将当前设备(网页推送订阅)与已知用户关联,并将所有未来数据统一在单个 onesignal_id 下。仅对已识别的用户使用此方法(例如登录或帐户恢复之后)。对于匿名用户,请勿调用 login。而应使用其自动分配的 onesignal_id 来追踪他们(参见 OneSignal.User.onesignalId)。
调用 login(external_id) 时会发生什么
SDK 的行为会因 external_id 是否已存在于 OneSignal 应用中而有所不同。
如果 external_id 已存在:
- SDK 会切换到该现有用户。
- 您可能会在浏览器网络日志或控制台中看到
409 Conflict。这表示该外部 ID 已存在于应用中;在此路径下这是预期的,通常不是您必须处理的 Promise 拒绝。
- 您可能会在浏览器网络日志或控制台中看到
- 当前
onesignal_id会被丢弃,并加载该用户现有的onesignal_id。 - 当前设备(网页推送订阅)会被关联到该现有用户。
- 登录前收集的匿名数据不会合并,将被丢弃。这包括标签、会话数据、电子邮件/SMS 订阅和其他本地用户属性。
external_id 不存在:
- 将使用当前
onesignal_id创建一个新用户。 - 用户匿名期间收集的所有数据都将保留。
- 设备(网页推送订阅)将与这个新用户关联。
- SDK 在网络故障或服务器错误时会自动重试登录请求。
- 您无需实现自己的重试逻辑。
- 一旦知道用户的 ID(例如登录或会话恢复之后),请在每次页面加载时调用
login(external_id)。 - 每当登录的用户发生变化(帐户切换)时,请再次调用它。
- 在拥有稳定、已知的用户标识符之前,不要调用
login。
JavaScript
logout()
取消当前用户与网页推送订阅的关联。
- 从当前网页推送订阅中删除
external_id。不会从其他订阅中删除external_id。 - 将
onesignal_id重置为新的匿名用户。 - 任何新数据(例如标签、订阅、会话数据等)现在都将在新的匿名用户上设置,直到他们通过
login方法被识别。
当用户从您的网站注销且您不想再向该浏览器发送定向的事务性消息时,请使用此方法。
JavaScript
OneSignal.User.onesignalId
检索本地存储在浏览器上的当前用户的 onesignal_id。此值代表活跃的用户上下文(OneSignal 的用户 ID),并且可能随时间变化——例如,当您调用 login(external_id) 或 SDK 初始化时。如果调用得太早,此方法可能返回 null。
此值不是订阅 ID,订阅 ID 用于标识浏览器(即网页推送订阅)(参见 User.PushSubscription.id)。
onesignal_id 何时可用:
- OneSignal SDK 完成初始化之后
- 通过
login(external_id)识别用户之后 - 切换用户或恢复会话之后
addEventListener('change', …),而不是轮询。
常见用例:
在大多数情况下,您会希望使用通过 login 方法设置的您自己的外部 ID。但在某些情况下,您可能希望直接使用 onesignal_id。
- 在设置外部 ID 之前追踪匿名用户
- 将 OneSignal ID 存储在您的后端以用于支持或调试
- 将 OneSignal 用户与内部日志关联
- 显示该 ID 以用于故障排除或 QA
JavaScript
OneSignal.User.externalId
检索本地保存在浏览器上的当前用户的外部 ID。如果未通过 login 方法设置或在用户状态初始化之前调用,可能为 null。请改用用户状态 addEventListener('change', …)来监听用户状态变更。
JavaScript
addEventListener() User State
监听用户上下文的变更(例如登录、退出、ID 分配)。
JavaScript
addAlias(), addAliases(), removeAlias(), removeAliases()
别名是替代标识符(如用户名或 CRM ID)。
- 在添加别名之前,请使用
login()设置external_id。添加到没有external_id的订阅的别名将不会在多个订阅中同步。 - 详情请参见别名。
JavaScript
getLanguage(), setLanguage()
获取和/或覆盖用户的自动检测语言。可用语言代码列表请参见多语言消息。
JavaScript
自定义事件
通过自定义事件触发旅程和 Wait Until 步骤激活。自定义事件需要 Web SDK
160500+。要追踪自定义事件,用户应该已登录。请在传入 OneSignalDeferred.push 的 OneSignal 实例上调用自定义事件 API(参见本页顶部的设置和调试),而不是在 window.OneSignal 上——页面 SDK 通过延迟队列初始化,该回调是访问 OneSignal.User 的受支持方式。name- 必需。 事件名称的字符串。properties- 可选。 要添加到事件的键值对。属性字典或映射必须可序列化为有效的 JSON 对象。支持嵌套值。
os_sdk 下将特定于应用的数据包含到属性负载中,供消费使用。例如,要按订阅类型定向事件,您可以访问 os_sdk.type。
json
trackEvent()
在 init() 完成后调用。此示例使用一个延迟回调,因此 init 总是在 trackEvent 之前运行:
JavaScript
在生产环境中,请将
trackEvent 添加到您已经 await OneSignal.init(...) 的延迟回调中。除非有意为之,否则不要注册第二个 init。标签
标签是您根据事件或用户属性在用户上设置的自定义key : value 字符串数据对。更多详情请参见标签。
addTag(), addTags()
在当前用户上设置单个或多个标签。
- 如果键已经存在,值将被替换。
- 超出您的计划标签限制将导致操作静默失败。
JavaScript
removeTag(), removeTags()
从当前用户中删除单个或多个标签。
JavaScript
getTags()
返回用户标签的本地副本。标签在 login() 或新应用会话期间从服务器更新。
JavaScript
隐私
setConsentRequired()
在开始数据收集之前强制用户同意。必须在 init() 运行之前调用(例如在第一个 OneSignalDeferred 回调的开头,await OneSignal.init(...) 之前)。
此方法与在 init 选项中添加 requiresUserPrivacyConsent: true 相同。
JavaScript
setConsentGiven()
授予或撤销用户对数据收集的同意。没有同意,不会向 OneSignal 发送数据,也不会创建订阅。
- 如果
setConsentRequired()或requiresUserPrivacyConsent设置为true,我们的 SDK 将不会完全启用,直到使用true调用setConsentGiven。 - 如果
setConsentGiven设置为true并创建了订阅,然后将其设置为false,该订阅将不再接收更新。该订阅的当前数据保持不变,直到setConsentGiven再次设置为true。 - 如果您想删除用户和/或订阅数据,请使用我们的删除用户或删除订阅 API。
JavaScript
订阅
订阅代表单个消息渠道实例(例如一个浏览器),并具有唯一的订阅 ID(OneSignal 的设备级 ID)。一个用户可以在多个设备和平台上拥有多个订阅。 更多详情请参见订阅。User.PushSubscription.id
检索当前浏览器的网页推送订阅 ID,由 SDK 本地存储。
此 ID 唯一标识此特定浏览器的推送渠道,而不是用户。它通常用于将设备或浏览器与您的后端关联,或调试送达问题。
如果在订阅创建或恢复之前调用,此值可能为 null。
要可靠地检测网页推送订阅 ID 何时可用或变更,请使用推送订阅监听器。
JavaScript
User.PushSubscription.token
返回当前推送订阅令牌。如果调用得太早,可能返回 null。建议在订阅观察器中获取此数据以响应变更。
JavaScript
addEventListener() Push Subscription Changes
使用此方法响应推送订阅变更,如:
- 设备从 Google (FCM) 或 Apple (APNs) 接收新推送令牌
- OneSignal 分配订阅 ID
optedIn值发生变更(例如调用了optIn()或optOut())- 用户在浏览器或操作系统设置中切换推送权限,然后返回您的网站
change 监听器,并传入一个包含 previous 和 current 的状态对象,以便您检测发生了什么变更。
当
autoResubscribe 为 true 时,回访用户可能会触发 change 事件且 previous 和 current 上的 optedIn 均为 true,因为浏览器权限没有变化——只是推送令牌被重新注册(例如清除站点数据或迁移之后)。对于应反映新订阅或重新订阅的分析或服务器端追踪,event.current.token && !event.previous.token 通常比单独比较 optedIn 更可靠。addEventListener() 的同一处理程序引用调用 removeEventListener()。
JavaScript
dataLayer 的 Google Analytics): 当推送令牌出现且之前没有令牌时触发自定义事件,这样即使 optedIn 未变化的重新注册也能被正确计数。订阅 ID 可能在同一回调中到达,也可能在稍后的 change 事件中到达,取决于时机:
JavaScript
optOut(), optIn(), optedIn
控制当前推送订阅的订阅状态(subscribed 或 unsubscribed)。使用这些方法来控制您网站上的推送订阅状态。常见用例:1)防止向注销的用户发送推送。2)在您的网站内实施通知偏好中心。
optOut():将当前推送订阅状态设置为取消订阅(即使用户有有效的推送令牌)。optIn():执行以下操作之一:- 如果订阅有有效的推送令牌,将当前推送订阅状态设置为
subscribed。 - 如果订阅没有有效的推送令牌,尝试显示推送权限提示。
- 如果订阅有有效的推送令牌,将当前推送订阅状态设置为
optedIn:如果当前推送订阅状态为已订阅,则返回true,否则返回false。如果推送令牌有效但调用了optOut(),将返回false。
JavaScript
addEmail(), removeEmail()
为当前用户添加或删除电子邮件订阅(电子邮件地址)。
这些方法与身份验证兼容。
调用 addEmail(email) 时:
- 该电子邮件地址成为当前用户的电子邮件订阅。
- 该电子邮件可能被创建或重新分配。
- 同一电子邮件地址不能在同一 OneSignal 应用中多次存在。如果您看到重复的电子邮件地址,请检查您的 REST API 请求,必要时联系支持。
调用
removeEmail(email) 时:
- 该电子邮件订阅从当前用户中移除。
- 当前外部 ID 从该电子邮件订阅中移除。
- 为该电子邮件订阅分配一个新的 OneSignal ID。
- 其他订阅(推送、SMS、其他电子邮件)不受影响。
- 先调用
login(),再调用addEmail()。否则,该电子邮件可能被附加到匿名用户。 - 使用稳定、已验证的电子邮件地址。
- 遵循电子邮件声誉最佳实践。
JavaScript
addSms(), removeSms()
为当前用户添加或删除 SMS 订阅(电话号码)。电话号码必须以 E.164 格式提供(例如 +15551234567)。
这些方法与身份验证兼容。
调用 addSms(phoneNumber) 时:
- 该电话号码成为当前用户的 SMS 订阅。
- 该号码可能被创建或重新分配。
- 同一电话号码不能在同一 OneSignal 应用中多次存在。如果您看到重复的电话号码,请检查您的 REST API 请求,必要时联系支持。
调用
removeSms(phoneNumber) 时:
- 该 SMS 订阅从当前用户中移除。
- 当前外部 ID 从该 SMS 订阅中移除。
- 为该 SMS 订阅分配一个新的 OneSignal ID。
- 其他订阅(推送、电子邮件、其他 SMS)不受影响。
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 或推送令牌。对于这些,请使用 User.PushSubscription(以及下面的相关方法)。
要监听权限变更,请使用 permissionChange 事件。
JavaScript
addEventListener() Notifications
您可以使用 addEventListener 接入通知生命周期。将第一个参数替换为事件名称,如 permissionChange、click 或 dismiss(参见下面的小节)。您可以为每个事件注册多个处理程序。
要停止监听,请使用相同的事件名称和处理程序引用调用 removeEventListener。
JavaScript
permissionChange
当用户点击允许或阻止或关闭浏览器的原生权限请求时,发生此事件。
JavaScript
permissionPromptDisplay
当浏览器的原生权限请求刚刚显示时,发生此事件。
JavaScript
click
当点击通知的主体/标题或操作按钮时,将触发此事件。
JavaScript
foregroundWillDisplay
此事件在通知显示之前发生。此事件在您的页面上触发。如果在您的网站上打开了多个浏览器标签页,此事件将在 OneSignal 活跃的所有页面上触发。
JavaScript
dismiss
此事件在以下情况下发生:
- 用户故意关闭通知而不点击通知主体或操作按钮
- 在 Android 上的 Chrome 中,用户关闭所有网页推送通知(此事件将为我们显示的每个网页推送通知触发)
- 通知自行过期并消失
如果用户点击通知主体或某个操作按钮,此事件不会发生。这被视为通知
click 事件。JavaScript
setDefaultUrl()
设置通知的默认 URL。
如果您未设置默认 URL,您的通知默认将打开到您网站的根目录。
JavaScript
setDefaultUrl();启动和图标行为遵循您的 Safari / Apple 配置(例如您 OneSignal Web 设置中的 Site URL)。请参阅站点设置。
setDefaultTitle()
设置在通知上显示的默认标题。
JavaScript
结果
结果方法位于OneSignal.Session 上。请在 init 之后使用与其他地方相同的延迟 OneSignal 实例。
sendOutcome()
触发可在 OneSignal 仪表板中查看的结果。接受结果名称(string,必需)和值(number,可选)。每次使用相同的结果名称调用 sendOutcome 方法时,结果计数将增加,并且结果值将按传入的量增加(如果包含)。更多详情请参见自定义结果。
JavaScript
sendUniqueOutcome()
触发可在 OneSignal 仪表板中查看的结果。仅接受结果名称(string,必需)。sendUniqueOutcome 将仅为每个用户将该结果的计数增加一次。更多详情请参见自定义结果。
JavaScript