Skip to main content

设置和调试

您可能需要使用 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 的初始化,我们建议使用我们的隐私方法
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "ONESIGNAL_APP_ID",
  });
});
初始化选项仅适用于自定义代码设置。否则,这些将在 OneSignal 仪表板中配置。
ParameterTypeDescription
appIdStringRequired: Your OneSignal App ID found in Keys & IDs.
requiresUserPrivacyConsentBooleanDelays SDK initialization until the user provides privacy consent. Must call setConsentGiven() to complete setup.
safari_web_idStringThe Safari Web ID for your uploaded Safari .p12 certificate. Web Quickstart.
promptOptionsObject自定义权限提示。下面的详细信息
notifyButtonObject启用和配置订阅铃铛。下面的详细信息
welcomeNotificationObject自定义或禁用欢迎通知。下面的详细信息
persistNotificationBooleanChrome(仅限桌面)- true:通知持续存在直到点击,false:短时间后消失。Firefox/Safari 忽略此设置。
webhooksObject配置事件回调。查看 Webhooks
autoResubscribeBoolean推荐: 自动为清除浏览器缓存或迁移到 OneSignal 的用户重新订阅。如果在代码中使用,会覆盖仪表板设置。
notificationClickHandlerMatchString"exact"(默认):聚焦具有精确URL匹配的标签页。"origin":聚焦具有相同域的任何标签页。
notificationClickHandlerActionString"navigate"(默认):导航到 launchURL"focus":聚焦现有标签页(仅与 "origin" 匹配一起使用)。
serviceWorkerParamObject设置服务工作线程的 scope。如果适用,必须与其他服务工作线程的范围不同。示例:
{ scope: "/myPath/myCustomScope/" }
serviceWorkerPathString设置 OneSignal 服务工作线程文件的位置。示例:
"myPath/OneSignalSDKWorker.js"

promptOptions parameters

使用 promptOptions 来本地化或自定义用户权限提示。所有字段都是可选的。
ParameterTypeDescription
slidedownObject包含一个带有配置选项的 prompts 数组。
promptsArray of Objects提示配置数组。示例:
"slidedown": { "prompts": [{...}, {...}] }
typeString提示类型:
  • push – 滑动提示(无类别)
  • category – 最多10个类别的滑动提示
  • email – 仅收集邮箱
  • sms – 仅收集电话号码
  • smsAndEmail – 同时收集两者
参见网页权限提示
autoPromptBoolean
  • true:根据 delay 显示。
  • false:仅通过滑动提示 API 手动显示提示。
delayObject控制何时显示自动提示:
{ pageViews: 3, timeDelay: 20 } = 在第三次页面浏览和等待20秒后显示。
textObject自定义文本选项:
  • actionMessage (最多90个字符)
  • acceptButton (最多15个字符)
  • cancelButton (最多15个字符)
  • emailLabelsmsLabelconfirmMessage
  • updateMessagepositiveUpdateButtonnegativeUpdateButton(用于更新类别或联系信息)
categoriesArray of Objects仅适用于 type: category。每个对象包括:
tag:内部键
label:用户可见名称
示例:[ {tag: "local_news", label: "Local News"} ]。参见数据标签

notifyButton parameters

配置页面上显示的订阅铃铛(通知按钮)。
ParameterTypeDescription
enableBooleanEnables the Subscription Bell. Disabled by default.
displayPredicateFunction返回 truefalse 以显示/隐藏铃铛的自定义函数(或 Promise)。显示时评估一次。
sizeString'small''medium''large'。订阅后缩小到 'small'
positionString'bottom-left''bottom-right'
offsetObjectCSS 像素偏移量:{ bottom: '50px', left: '10px' }
prenotifyBoolean如果为 true,显示”1 未读”图标和自定义悬停文本。
showCreditBoolean设置为 false 可隐藏弹出窗口中的”Powered by OneSignal”。
textObject铃铛 UI 的自定义文本。

welcomeNotification parameters

自定义首次订阅后发送的欢迎通知。
ParameterTypeDescription
disableBooleanDisable welcome notification.
messageString必需: 通知消息。如果为空,默认为 'Thanks for subscribing!'
titleString通知标题。默认为站点标题。使用 ' '(空格)移除(不推荐)。
urlURL用户点击通知时打开的可选 URL。通常不需要。

Example:
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "YOUR_APP_ID",
    safari_web_id: "YOUR_SAFARI_WEB_ID",
    notifyButton: {
      enable: true,
    },
    promptOptions: {
      slidedown: {
        prompts: [{
            type: "smsAndEmail",
            autoPrompt: false,
            text: {
              emailLabel: "Insert Email Address",
              smsLabel: "Insert Phone Number",
              acceptButton: "Submit",
              cancelButton: "No Thanks",
              actionMessage: "接收最新的新闻、更新和优惠信息。",
              updateMessage: "更新您的推送通知订阅偏好设置。",
              confirmMessage: "Thank You!",
              positiveUpdateButton: "Save Preferences",
              negativeUpdateButton: "Cancel",
            },
            delay: {
              pageViews: 1,
              timeDelay: 20
            },
          },
          {
            type: "category",
            autoPrompt: true,
            text: {
              actionMessage: "We'd like to show you notifications for the latest news and updates.",
              acceptButton: "Allow",
              cancelButton: "Cancel",

              /* 类别滑动提示特定文本 */
              negativeUpdateButton: "Cancel",
              positiveUpdateButton: "Save Preferences",
              updateMessage: "更新您的推送通知订阅偏好设置。",
            },
            delay: {
              pageViews: 3,
              timeDelay: 20
            },
            categories: [{
                tag: "politics",
                label: "Politics"
              },
              {
                tag: "local_news",
                label: "Local News"
              },
              {
                tag: "world_news",
                label: "World News",
              },
              {
                tag: "culture",
                label: "Culture"
              },
            ]
          }
        ]
      }
    }
  });
});
</script>

setLogLevel()

设置日志记录以在控制台打印额外的日志。更多详情请参见使用浏览器开发工具调试
JavaScript
  OneSignal.Debug.setLogLevel(“trace”);
Log levels:
  • '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 在网络故障或服务器错误时会自动重试。
每次用户打开网站或在订阅变更监听器中调用此方法,以确保设置外部 ID并将订阅链接到用户。
OneSignalDeferred.push(async function(OneSignal) {
   await OneSignal.login("external_id");
});

logout()

取消当前用户与订阅的关联。
  • 从当前推送订阅中删除 external_id
  • 将 OneSignal ID 重置为新的匿名用户。
  • 任何新数据(例如标签、订阅、会话数据等)现在都将在新的匿名用户上设置,直到他们通过 login 方法被识别。
当用户从您的应用程序注销时,如果您想将订阅设置为新的匿名用户,请使用此方法。
JavaScript
  OneSignalDeferred.push(async function(OneSignal) {
     await OneSignal.logout();
  });

OneSignal.User.onesignalId

检索当前的 OneSignal ID。如果在用户状态初始化之前调用,可能为 null。请使用用户状态 addObserver()来监听用户状态变更。
JavaScript
  OneSignal.User.onesignalId

OneSignal.User.externalId

检索当前的外部 ID。如果未设置或在用户状态初始化之前调用,可能为 null。请使用用户状态 addObserver()来监听用户状态变更。
JavaScript
  OneSignal.User.externalId

addEventListener() User State

监听用户上下文的变更(例如登录、退出、ID 分配)。
JavaScript
  OneSignalDeferred.push(function() {
    OneSignal.User.addEventListener('change', function (event) {
      console.log('change', { event });
    });
  });

addAlias(), addAliases(), removeAlias(), removeAliases()

别名是替代标识符(如用户名或 CRM ID)。
  • 在添加别名之前,请使用 login() 设置 external_id。添加到没有 external_id 的订阅的别名将不会在多个订阅中同步。
  • 详情请参见别名
JavaScript
  // 添加单个别名
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // 添加多个别名
  OneSignal.User.addAliases({
    ALIAS_LABEL_01: "ALIAS_ID_01",
    ALIAS_LABEL_02: "ALIAS_ID_02",
    ALIAS_LABEL_03: "ALIAS_ID_03",
  });

  // 删除单个别名
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // 删除多个别名
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02", "ALIAS_LABEL_03"]);

getLanguage(), setLanguage()

获取和/或覆盖用户的自动检测语言。可用语言代码列表请参见多语言消息
JavaScript
  // 获取当前登录用户的语言
  OneSignal.User.getLanguage()

  // 设置当前登录用户的语言
  OneSignal.User.setLanguage('en')

自定义事件

通过自定义事件触发旅程等待步骤激活
自定义事件仍在测试阶段,需要以下版本的 SDK 从您的网站触发:
  • Web SDK,从 160500 开始可用
要追踪自定义事件,用户应该已登录。
追踪并发送当前用户执行的自定义事件。
  • name - 必需。 事件名称的字符串。
  • properties - 可选。 要添加到事件的键值对。属性字典或映射必须可序列化为有效的 JSON 对象。
SDK 会自动在保留键 os_sdk 下将特定于应用的数据包含到属性负载中,供消费。例如,要按设备类型面向事件,您可以访问 os_data.device_type
json
{ 
  "os_sdk": {
    "device_os": "138",
    "type": "ChromePush",
    "device_model": "MacIntel",
    "sdk": "160500"
  }
}

trackEvent()

JavaScript
const properties = {
  "promo_code": "NEW50",
  "additional_data": {
     "signed_up_with_email": true,
     "products_viewed_count": 15,
  }
}
window.OneSignal.User.trackEvent('started_free_trial', properties);

// 您也可以按名称追踪事件,而不需要关联额外属性
window.OneSignal.User.trackEvent('my_event_name');

数据标签

标签是您根据事件或用户属性在用户上设置的自定义 key : value 字符串数据对。更多详情请参见数据标签

addTag(), addTags()

在当前用户上设置单个或多个标签。
  • 如果键已经存在,值将被替换。
  • 超出您的计划标签限制将导致操作静默失败。
JavaScript
  // 添加单个标签
  OneSignal.User.addTag('tag_key', 'tag_value');

  // 添加多个标签
  OneSignal.User.addTags({
   KEY_01: "VALUE_01",
   KEY_02: "VALUE_02",
   KEY_03: "VALUE_03"
  });

removeTag(), removeTags()

从当前用户中删除单个或多个标签。
JavaScript
  // 删除单个标签
  OneSignal.User.removeTag("KEY");

  OneSignal.User.removeTags(['KEY_01', 'KEY_02', 'KEY_03']);

getTags()

返回用户标签的本地副本。标签在 login() 或新应用会话期间从服务器更新。
JavaScript
  const tags = OneSignal.User.getTags()

隐私

setConsentRequired()

在开始数据收集之前强制用户同意。必须在初始化 SDK 之前调用。 此方法与在 init 方法中添加 requiresUserPrivacyConsent: true 相同。
JavaScript
  OneSignal.setConsentRequired(true);

setConsentGiven()

授予或撤销用户对数据收集的同意。没有同意,不会向 OneSignal 发送数据,也不会创建订阅。
  • 如果 setConsentRequired()requiresUserPrivacyConsent 设置为 true,我们的 SDK 将不会完全启用,直到使用 true 调用 setConsentGiven
  • 如果 setConsentGiven 设置为 true 并创建了订阅,然后将其设置为 false,该订阅将不再接收更新。该订阅的当前数据保持不变,直到 setConsentGiven 再次设置为 true
  • 如果您想删除用户和/或订阅数据,请使用我们的删除用户删除订阅 API。
JavaScript
  OneSignal.setConsentGiven(true);

订阅

更多详情请参见订阅

User.PushSubscription.id

返回当前推送订阅 ID。如果调用得太早,可能返回 null。建议在订阅观察器中获取此数据以响应变更。
JavaScript
  OneSignal.User.PushSubscription.id;

User.PushSubscription.token

返回当前推送订阅令牌。如果调用得太早,可能返回 null。建议在订阅观察器中获取此数据以响应变更。
JavaScript
  OneSignal.User.PushSubscription.token;

addEventListener() push subscription changes

使用此方法响应推送订阅变更,如:
  • 设备从 Google (FCM) 或 Apple (APNs) 接收新推送令牌
  • OneSignal 分配订阅 ID
  • optedIn 值发生变更(例如调用 optIn()optOut()
  • 用户在系统设置中切换推送权限,然后打开应用
当这种情况发生时,SDK 会触发 onPushSubscriptionChange 事件。您的监听器会接收一个状态对象,包含 previouscurrent 值,因此您可以准确检测发生了什么变更。 要停止监听更新,请调用相关的 removeObserver()removeEventListener() 方法。
JavaScript
  function pushSubscriptionChangeListener(event) {
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

optOut(), optIn(), optedIn

控制当前推送订阅的订阅状态(subscribedunsubscribed)。使用这些方法来控制您网站上的推送订阅状态。常见用例:1)防止向注销的用户发送推送。2)在您的网站内实施通知偏好中心。
  • optOut():将当前推送订阅状态设置为取消订阅(即使用户有有效的推送令牌)。
  • optIn():执行三个操作之一:
    1. 如果订阅有有效的推送令牌,将当前推送订阅状态设置为 subscribed
    2. 如果订阅没有有效的推送令牌,尝试显示推送权限提示。
  • optedIn:如果当前推送订阅状态为已订阅,则返回 true,否则返回 false。如果推送令牌有效但调用了 optOut(),将返回 false
JavaScript
  OneSignal.User.PushSubscription.optOut();

  OneSignal.User.PushSubscription.optIn();

  var optedIn = OneSignal.User.PushSubscription.optedIn;

addEmail(), removeEmail()

为当前用户添加或删除电子邮件订阅(电子邮件地址)。在 login() 之后调用 addEmail 以设置正确的用户上下文。与身份验证兼容。
JavaScript
  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");

addSms(), removeSms()

为当前用户添加或删除 SMS 订阅(电话号码)。需要 E.164 格式。在 login() 之后调用 addSms 以设置正确的用户上下文。与身份验证兼容。
JavaScript
  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");

滑动提示

在您的网站上显示各种滑动提示。更多详情请参见网页权限提示
  • 如果被关闭,未来的调用将在至少三天内被忽略。进一步拒绝将延长再次提示用户之前所需的时间。
  • 要覆盖退让行为,请向方法传递 {force: true}。然而,为了提供良好的用户体验,请将操作绑定到 UI 启动的事件(如按钮点击)。
这不会替换订阅所需的原生浏览器提示。您必须使用原生浏览器提示获得权限。

promptPush()

显示推送通知的常规滑动提示。
JavaScript
  OneSignal.Slidedown.promptPush();
  // 在测试时要绕过退让逻辑,请传递 {force: true}
  //OneSignal.Slidedown.promptPush({force: true});

promptPushCategories()

显示类别滑动提示,允许用户更新他们的标签。如果用户尚未授予权限,还会触发原生通知权限提示。
JavaScript
  OneSignal.Slidedown.promptPushCategories();
  // 在测试时要绕过退让逻辑,请传递 {force: true}
  //OneSignal.Slidedown.promptPushCategories({force: true});

promptSms()

显示 SMS 订阅提示。
JavaScript
  OneSignal.Slidedown.promptSms();
  // 在测试时要绕过退让逻辑,请传递 {force: true}
  //OneSignal.Slidedown.promptSms({force: true});

promptEmail()

显示电子邮件订阅提示。
JavaScript
  OneSignal.Slidedown.promptEmail();
  // 在测试时要绕过退让逻辑,请传递 {force: true}
  //OneSignal.Slidedown.promptEmail({force: true});

promptSmsAndEmail()

同时显示 SMS 和电子邮件订阅提示。
JavaScript
  OneSignal.Slidedown.promptSmsAndEmail();
  // 在测试时要绕过退让逻辑,请传递 {force: true}
  //OneSignal.Slidedown.promptSmsAndEmail({force: true});

addEventListener() Slidedown

添加回调以检测滑动提示显示事件。
JavaScript
  OneSignalDeferred.push(function(OneSignal) {

    OneSignal.Slidedown.addEventListener('slidedownShown', function (event) {
      console.log('slidedownShown', { event });
    });

  });

推送通知

requestPermission()

通过原生浏览器提示请求推送通知权限。遵循浏览器设置的退让逻辑。更多详情请参见网页权限提示
JavaScript
  OneSignal.Notifications.requestPermission();

isPushSupported()

如果当前浏览器支持网页推送,则返回 true
JavaScript
  const isSupported = OneSignal.Notifications.isPushSupported();

OneSignal.Notifications.permission

返回一个布尔值,指示网站当前显示通知的权限。
  • true:用户已授予显示通知的权限。
  • false:用户已拒绝或尚未授予显示通知的权限。
这只是网站的权限,不考虑 OneSignal 的 optOut 状态或订阅 ID 和推送令牌的存在,请参见 OneSignal.User.PushSubscription 要监听权限变更,请使用 permissionChange 事件。
JavaScript
  let permission = OneSignal.Notifications.permission;

addEventListener() notifications

您可以通过将事件处理程序附加到通知事件来接入通知生命周期。调用 addEventListener 允许您为通知事件添加任意数量的事件处理程序。 要停止监听事件,请调用相关的 removeEventListener() 方法。
JavaScript
  function eventListener(event) {
    console.log(`${event}`);
  }

  OneSignal.Notifications.addEventListener("event", eventListener);

  OneSignal.Notifications.removeEventListener("event", eventListener);

permissionChange

当用户点击允许或阻止或关闭浏览器的原生权限请求时,发生此事件。
JavaScript
  function permissionChangeListener(permission) {
    if (permission) {
      console.log(`权限已接受!`);
    }
  }

  OneSignal.Notifications.addEventListener("permissionChange", permissionChangeListener);

permissionPromptDisplay

当浏览器的原生权限请求刚刚显示时,发生此事件。
JavaScript
  function promptListener() {
    console.log(`权限提示显示事件: ${event}`);
  }

  OneSignal.Notifications.addEventListener("permissionPromptDisplay", promptListener);

click

当点击通知的主体/标题或操作按钮时,将触发此事件。
JavaScript
  function clickEventListener(event) {
    console.log(`点击事件: ${event}`);
  }

  OneSignal.Notifications.addEventListener("click", clickEventListener);

foregroundWillDisplay

此事件在通知显示之前发生。此事件在您的页面上触发。如果在您的网站上打开了多个浏览器标签页,此事件将在 OneSignal 活跃的所有页面上触发。
JavaScript
  function foregroundWillDisplayListener(event) {
    console.log(`通知将显示: ${notification}`);
  }

  OneSignal.Notifications.addEventListener("foregroundWillDisplay", foregroundWillDisplayListener);

dismiss

此事件在以下情况下发生:
  • 用户故意关闭通知而不点击通知主体或操作按钮
  • 在 Android 上的 Chrome 中,用户关闭所有网页推送通知(此事件将为我们显示的每个网页推送通知触发)
  • 通知自行过期并消失
如果用户点击通知主体或某个操作按钮,此事件不会发生。这被视为通知 click 事件。
JavaScript
  function notificationDismissedListener(event) {
    console.log(`关闭事件: ${event}`);
  }

  OneSignal.Notifications.addEventListener("dismiss", notificationDismissedListener);

setDefaultUrl()

设置通知的默认 URL。 如果您未设置默认 URL,您的通知默认将打开到您网站的根目录。
JavaScript
  OneSignal.Notifications.setDefaultUrl("https://onesignal.com");
要为通知设置默认 URL,请提供一个在点击通知时要启动的有效 URL。如果在创建通知时未指定其他 URL,将使用此默认 URL。如果您在创建通知时指定了 URL,默认 URL 将被覆盖。 对于 Safari,默认通知图标 URL 将设置为您在 Safari 设置中指定的网站 URL,因为此功能不可用。

setDefaultTitle()

设置在通知上显示的默认标题。
JavaScript
  OneSignal.Notifications.setDefaultTitle("Powered by OneSignal!");
如果创建通知时带有标题,指定的标题始终会覆盖此默认标题。 通知的标题默认为用户最后访问的页面标题。如果您的页面标题在页面之间有所不同,这种不一致性可能不可取。只要未指定通知标题,调用此方法可在通知中统一页面标题。

结果

sendOutcome()

触发可在 OneSignal 仪表板中查看的结果。接受结果名称(string,必需)和值(number,可选)。每次使用相同的结果名称调用 sendOutcome 方法时,结果计数将增加,并且结果值将按传入的量增加(如果包含)。更多详情请参见自定义结果
JavaScript
  OneSignal.Session.sendOutcome('outcome name', 19.84);

sendUniqueOutcome()

触发可在 OneSignal 仪表板中查看的结果。仅接受结果名称(string,必需)。sendUniqueOutcome 将仅为每个用户将该结果的计数增加一次。更多详情请参见自定义结果
JavaScript
  OneSignal.Session.sendUniqueOutcome('outcome name');

I