设置和调试
您可能需要使用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