移动 SDK 参考 - OneSignal

设置和调试

这些方法是将 OneSignal SDK 集成到您的应用程序中的参考。有关完整的特定平台设置说明，请参阅移动 SDK 设置。

`initialize()`

初始化 OneSignal SDK。这应该在应用程序启动期间调用。ONESIGNAL_APP_ID 可以在密钥和 ID 中找到。

如果您想延迟 OneSignal SDK 的初始化，我们建议使用我们的隐私方法。

OneSignal.initWithContext(this, ONESIGNAL_APP_ID)

`setLogLevel()`

设置日志记录以向 Android LogCat 或 Xcode 日志打印额外日志。在初始化 OneSignal 之前调用此方法。有关更多详情，请参阅获取调试日志。

// LogLevel: .None | .Fatal | .Error | .Warn | .Info | .Debug | .Verbose
OneSignal.Debug.logLevel = LogLevel.Verbose

`setAlertLevel()`

设置日志级别以在您的应用中显示为警报对话框。确保在提交到应用商店之前移除此设置。

OneSignal.Debug.alertLevel = LogLevel.Exception

用户身份和属性

当用户打开您的应用时，OneSignal 自动创建一个 OneSignal ID（用户级别）和一个订阅 ID（设备级别）。您可以通过使用您的唯一用户标识符调用 login() 将多个订阅（如设备、电子邮件、电话号码）与单个用户关联。

有关更多详情，请参阅用户和别名。

将用户上下文设置为提供的 external_id。确保与此 external_id 相关联的所有订阅和属性在单个 onesignal_id 下统一。有关更多详情，请参阅用户。 关键行为：

如果 external_id 已存在，SDK 将切换到该用户。登录前收集的匿名数据不会合并，将被丢弃。
如果 external_id 不存在，本地状态将保存在当前 onesignal_id 下。用户匿名时收集的任何数据将被保留。
SDK 在网络故障或服务器错误时自动重试。

每次用户打开应用时调用此方法，以确保设置外部 ID 并将订阅链接到用户。

OneSignal.login("external_id")

`logout()`

将当前用户与订阅取消链接。

从当前推送订阅中移除 external_id。
将 OneSignal ID 重置为新的匿名用户。
任何新数据（如标签、订阅、会话数据等）现在将设置在新的匿名用户上，直到通过 login 方法识别他们。

当用户退出您的应用且您希望将订阅设置为新的匿名用户时使用此方法。

OneSignal.logout()

`getOnesignalId()`

Retrieve the current OneSignal ID. May be null if called before user state is initialized. Instead, use User State addObserver() to listen for user state changes.

val id = OneSignal.User.onesignalId

`getExternalId()`

Retrieve the current External ID. May be null if not set or called before user state is initialized. Instead, use User State addObserver() to listen for user state changes.

  val id = OneSignal.User.externalId

`addObserver()` user state

监听用户上下文的变化（如登录、注销、ID 分配）。

OneSignal.User.addObserver(object : IUserStateObserver {
    override fun onUserStateChange(state: UserChangedState) {
        println("User State Changed: onesignalId=${state.current.onesignalId}, externalId=${state.current.externalId}")
    }
})

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

别名是替代标识符（如用户名或 CRM ID）。

在添加别名之前使用 login() 设置 external_id。添加到没有 external_id 的订阅的别名不会在多个订阅间同步。
详情请参阅别名。

// 添加单个别名
OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID")

// 添加多个别名
var aliases = mapOf("ALIAS_LABEL_01" to "ALIAS_ID_01", "ALIAS_LABEL_02" to "ALIAS_ID_02")
OneSignal.User.addAliases(aliases)

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

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

`setLanguage()`

覆盖用户的自动检测语言。使用 ISO 639-1 语言代码。

OneSignal.User.setLanguage("en")

自定义事件

Trigger Journeys and Wait Until step activation via a custom event.

自定义事件仍处于测试阶段，需要以下版本的 SDK 才能从您的应用触发：

iOS native SDK, available starting 5.4.0-alpha-01
Android native SDK, available starting 5.3.0-alpha-01

跟踪并发送当前用户执行的自定义事件。

name - 必需。 事件名称作为字符串。
properties - 可选。 要添加到事件的键值对。属性字典或映射必须可序列化为有效的 JSON 对象。

SDK 自动将应用特定数据包含到属性负载中的保留键 os_sdk 下，以供使用。例如，要按设备类型定向事件，您将访问 os_data.device_type。

json

{ 
  "os_sdk": { 
    "sdk": "050213", 
    "device_os": "18.5", 
    "type": "iOSPush", 
    "device_model": "iPhone14,4", 
    "device_type": "ios", 
    "app_version": "5.4.0" 
  }
}

`trackEvent()`

OneSignal.User.trackEvent(
   name = "started_free_trial",
   properties = mapOf(
       "promo_code" to "NEW50",
       "additional_data" to mapOf(
           "signed_up_with_email" to true,
           "products_viewed_count" to 15
       )
   )
)

// 您也可以按名称跟踪事件，无需关联的额外属性
OneSignal.User.trackEvent("my_event_name")

数据标签

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

`addTag()`, `addTags()`

在当前用户上设置单个或多个标签。

如果键已存在，值将被替换。
超过您计划的标签限制将导致操作静默失败。

OneSignal.User.addTag("KEY", "VALUE")

OneSignal.User.addTags(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02"))

`removeTag()`, `removeTags()`

从当前用户删除单个或多个标签。

OneSignal.User.removeTag("KEY")

OneSignal.User.removeTags(listOf("KEY_01", "KEY_02"))

`getTags()`

返回用户标签的本地副本。标签在 login() 或新应用会话期间从服务器更新。

val tags: Map<String, String> = OneSignal.User.getTags()

隐私

`setConsentRequired()`

在数据收集开始前强制执行用户同意。必须在初始化 SDK 之前调用。

OneSignal.consentRequired = true

`setConsentGiven()`

授予或撤销用户对数据收集的同意。没有同意，不会向 OneSignal 发送数据，也不会创建订阅。

如果 setConsentRequired() 为 true，我们的 SDK 将不会完全启用，直到使用 true 调用 setConsentGiven。
如果 setConsentGiven 设置为 true 并创建了订阅，然后将其设置为 false，该订阅将不再接收更新。该订阅的当前数据保持不变，直到 setConsentGiven 再次设置为 true。
如果您想删除用户和/或订阅数据，请使用我们的删除用户或删除订阅 API。

OneSignal.consentGiven = true

位置

跟踪位置点需要 3 个步骤：

向您的应用添加位置跟踪权限和依赖项。

iOS: 选择要请求的位置服务授权开发者指南
Android: 请求位置权限开发者指南

您可能会遇到以下错误：

LocationManager.startGetLocation: not possible, no location dependency found

检查您应用的依赖项。常见解决方案是在您的 app/build.gradle 中添加：implementation 'com.google.android.gms:play-services-location:21.0.1'

使用 Location.setShared() 方法启用您的应用与 OneSignal 共享位置。
使用 Location.requestPermission 方法或使用应用内消息向用户请求位置跟踪权限。

`setShared()` location

使用此方法允许我们的 SDK 开始跟踪订阅的纬度和经度。确保您首先在应用中设置了正确的位置权限。

// 启用您的应用与 OneSignal 共享位置
OneSignal.Location.isShared = true

// 如果您的应用与 OneSignal 共享位置，则返回 true
var isShared: Boolean = OneSignal.isShared

`requestPermission()` location

使用此方法向您的用户显示系统级位置权限提示，或者使用应用内消息。确保您在应用中设置了正确的位置权限并启用了您的应用与 OneSignal 共享位置。

// 请求位置跟踪权限
OneSignal.Location.requestPermission(true)

class MyObserver : IPushSubscriptionObserver {
  init {
    OneSignal.User.pushSubscription.addObserver(this)
  }

  override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
    if (state.current.optedIn) {
      println("用户现在已选择加入，推送令牌为：${state.current.token}")
    }
  }
}

// Remove the observer
OneSignal.User.pushSubscription.removeObserver(this)

`optOut()`, `optIn()`, `optedIn`

控制当前推送订阅的订阅状态（subscribed 或 unsubscribed）。使用这些方法在您的应用内控制推送订阅状态。常见用例：1）防止向注销的用户发送推送。2）在您的应用内实现通知偏好中心。

optOut()：将当前推送订阅状态设置为未订阅（即使用户有有效的推送令牌）。
optIn()：执行以下三个操作之一：
1. 如果订阅有有效的推送令牌，它将当前推送订阅状态设置为 subscribed。
2. 如果订阅没有有效的推送令牌，它显示推送权限提示。
3. 如果推送权限提示已显示超过操作系统的限制（iOS 一次，Android 两次），它显示回退提示。

退回到设置提示

optedIn：如果当前推送订阅状态为已订阅，则返回 true，否则返回 false。如果推送令牌有效但调用了 optOut()，这将返回 false。

OneSignal.User.pushSubscription.optOut()

OneSignal.User.pushSubscription.optIn()

val optedIn = OneSignal.User.pushSubscription.optedIn

`addEmail()`, `removeEmail()`

向当前用户添加或移除电子邮件订阅（电子邮件地址）。在 login() 后调用 addEmail 以设置正确的用户上下文。与身份验证兼容。

OneSignal.User.addEmail("example@email.com")

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

`addSms()`, `removeSms()`

向当前用户添加或移除短信订阅（电话号码）。需要 E.164 格式。在 login() 后调用 addSms 以设置正确的用户上下文。与身份验证兼容。

OneSignal.User.addSms("+15558675309")

OneSignal.User.removeSms("+15558675309")

推送权限

`requestPermission(fallbackToSettings)` push

显示原生系统提示，要求用户授予推送通知权限。可选启用链接到设置应用的回退提示。

fallbackToSettings：如果为 true，当用户拒绝推送权限超过操作系统限制（iOS 一次，Android 两次）时，将显示回退提示。

权限被阻止时的退回设置提示

有关更多信息，请参阅推送权限提示。

// 我们建议在测试后移除此方法，改用应用内消息提示通知权限。
// 传递 true 将在用户拒绝推送权限时退回到设置提示
OneSignal.Notifications.requestPermission(true)

`addPermissionObserver()` push

使用此方法跟踪推送权限变化，如：

向用户显示通知权限提示。
用户接受或拒绝权限提示。
用户在设备的应用设置中启用或禁用您应用的通知，然后返回到您的应用。

当这种情况发生时，SDK 触发 onOSPermissionChanged 事件。您的监听器接收具有 from 和 to 值的状态对象，因此您可以准确检测发生了什么变化。要停止监听更新，请调用相关的 removePermissionObserver() 方法。

class MyObserver : IPermissionObserver {
  init {
    OneSignal.Notifications.addPermissionObserver(this)
  }

  override fun onNotificationPermissionChange(granted: Boolean) {
    if (granted) {
      // 通知现在已启用
    }
  }

  fun cleanup() {
    OneSignal.Notifications.removePermissionObserver(this)
  }
}

`getPermission()`, `getCanRequestPermission()`

getPermission() 返回应用级别的当前推送权限状态。如果您通过 optOut() 或用户和订阅 API 中的 enabled 参数更改了权限状态，它不会考虑 OneSignal 级别的订阅状态。我们建议使用推送权限观察者在应用运行时跟踪设备通知权限状态的变化，或使用推送订阅观察者跟踪推送订阅状态的变化，而不是使用 getPermission()。 getCanRequestPermission() 返回尝试请求权限是否会导致向用户显示提示。如果为 false，用户已经拒绝了权限，可以显示回退提示或根本不显示提示。有关更多信息，请参阅提示推送权限。

// 如果应用有权限显示通知，则为 true
OneSignal.Notifications.permission

// 如果设备可以显示系统通知权限提示，则为 true
val canRequest: Boolean = OneSignal.Notifications.canRequestPermission

`permissionNative` iOS

返回 iOS 设备原生权限的枚举。它将是以下之一：

0 = NotDetermined
1 = Denied
2 = Authorized
3 = Provisional (only available in iOS 12+)
4 = Ephemeral (only available in iOS 14+)

let permissionNative: OSNotificationPermission = OneSignal.Notifications.permissionNative.rawValue

推送通知事件

`addClickListener()` push

设置当用户点击打开应用的推送通知时运行的回调。当此事件触发时，应用的活动或场景已经启动。使用此处理程序执行任何自定义逻辑——不要手动重新启动或重复应用导航。当不再需要处理程序时，使用 removeClickListener() 或 removeEventListener() 停止监听。

val clickListener = object : INotificationClickListener {
  override fun onClick(event: INotificationClickEvent) {
    Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
  }
}
OneSignal.Notifications.addClickListener(clickListener)

`addForegroundLifecycleListener()` push

允许您拦截和控制应用在前台时通知的行为。默认情况下，OneSignal 自动显示通知。您可以使用 event.preventDefault() 覆盖此行为以：

抑制通知
自定义它
为异步逻辑延迟显示（如获取用户状态、记录事件）

调用 event.notification.display() 稍后手动显示它。

这在通知服务扩展之后运行，后者在显示前修改负载。

当不再需要处理程序时，使用 removeForegroundLifecycleListener() 或 removeEventListener() 停止监听。

val lifecycleListener = object : INotificationLifecycleListener {
  override fun onWillDisplay(event: INotificationWillDisplayEvent) {
    Log.d("OneSignal", "Foreground notification: ${event.notification.title}")
    // 取消注释以防止通知在前台时显示
    // event.preventDefault()
  }
}
OneSignal.Notifications.addForegroundLifecycleListener(lifecycleListener)

`clearAllNotifications()`

从通知栏中移除所有 OneSignal 通知。使用此方法而不是 Android 的 android.app.NotificationManager.cancel。否则，当您的应用重启时，通知将被恢复。

OneSignal.Notifications.clearAllNotifications()

`removeNotification()` Android

基于其 Android 通知 ID 取消单个通知。使用此方法而不是 Android 的 android.app.NotificationManager.cancel。否则，当您的应用重启时，通知将被恢复。

OneSignal.Notifications.removeNotification(id)

`removeGroupedNotifications()` Android

使用提供的组键取消一组 OneSignal 通知。分组通知是 OneSignal 概念。没有 android.app.NotificationManager 等价物。

OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY")

应用内消息

In-app messages do not require any code; however, the SDK enables you to customize when messages are presented and handle lifecycle events.

`addTrigger()`, `addTriggers()`

基于单个或多个触发器决定何时显示应用内消息。有关更多信息，请参阅触发器。触发器不会持久化到后端。它们只存在于本地设备上并适用于当前用户。

OneSignal.InAppMessages.addTrigger("KEY", "VALUE")

OneSignal.InAppMessages.addTriggers(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02"))

`removeTrigger()`, `removeTriggers()`, `clearTriggers()`

Remove a single, multiple, or all triggers with the provided key from the current user.

OneSignal.InAppMessages.removeTrigger("KEY")

OneSignal.InAppMessages.removeTriggers(setOf("KEY_01", "KEY_02"))

OneSignal.InAppMessages.clearTriggers()

`paused`

Prevent In-app messages from being displayed to the user. When set to true, no in-app messages will be presented. When set to false, any messages the user qualifies for will be presented to them at the appropriate time.

OneSignal.InAppMessages.paused = true

`addLifecycleListener()`

响应或跟踪应用内消息的显示和解散。

val lifecycleListener = object : IInAppMessageLifecycleListener {
  override fun onWillDisplay(event: IInAppMessageWillDisplayEvent) {
    print(event.message.messageId)
  }

  override fun onDidDisplay(event: IInAppMessageDidDisplayEvent) {
    print(event.message.messageId)
  }

  override fun onWillDismiss(event: IInAppMessageWillDismissEvent) {
    print(event.message.messageId)
  }

  override fun onDidDismiss(event: IInAppMessageDidDismissEvent) {
    print(event.message.messageId)
  }
}
OneSignal.InAppMessages.addLifecycleListener(lifecycleListener)
OneSignal.InAppMessages.removeLifecycleListener(lifecycleListener)

`addClickListener()` in-app

响应应用内消息点击事件。事件包含以下点击操作元数据：

actionId：您在元素上设置的自定义标识符。
urlTarget：指定消息启动 URL 如何呈现的枚举。
url：操作的启动 URL（如果有的话）。
closingMessage：指示操作是否导致消息被关闭的布尔值。

val clickListener = object : IInAppMessageClickListener {
  override fun onClick(event: IInAppMessageClickEvent) {
    print(event.result.actionId)
  }
}
OneSignal.InAppMessages.addClickListener(clickListener)

Live Activity

应用程序应允许用户选择加入 Live Activities。例如，您的应用为用户提供使用按钮或呈现 IAM 在您的应用内启动 Live Activity 的选项。与通知权限或位置权限不同，您可以通过任何方法启动和更新 Live Activity 而无需明确提示。Live Activities 与 iOS 临时授权 UI 一起出现。Live Activities 必须在您的应用程序处于前台时启动。我们建议阅读 Apple 的开发者指南以了解更多关于 Live Activities 的信息。

`setup()`

允许 OneSignal 代表应用程序管理 LiveActivity 的生命周期。这包括监听 pushToStart 令牌更新和 pushToUpdate 令牌更新。

//... your app's code
OneSignal.LiveActivities.setup(MyWidgetAttributes.self);

`setupDefault()`

允许跨平台 SDK 通过消除客户应用程序定义和管理自己的 ActivityAttributes 的需要来管理 LiveActivity 的生命周期。有关更多详情，请参阅跨平台设置。

using OneSignalSDK;

//Push To Start
OneSignal.LiveActivities.SetupDefault();

//从应用内启动 Live Activity（推送启动不需要）
string activityId = "my_activity_id";

OneSignal.LiveActivities.StartDefault(
  activityId,
  new Dictionary<string, object>() {
      { "title", "Welcome!" }
  },
  new Dictionary<string, object>() {
      { "message", new Dictionary<string, object>() {
          { "en", "Hello World!"}
      }},
  });

`enter()`

进入 Live Activity 将 activityId 与我们服务器上的 Live Activity 临时推送令牌关联。在使用更新 Live Activities REST API 同时更新一个或多个 Live Activities 时指定此标识符。

// ... your app's code
let activity = try Activity<MyWidgetAttributes>.request(
  attributes: attributes,
  contentState: contentState,
  pushType: .token)
Task {
  for await data in activity.pushTokenUpdates {
      let token = data.map {String(format: "%02x", $0)}.joined()
      // ... required code for entering a live activity
      // Activity ID cannot contain "/" characters
      OneSignal.LiveActivities.enter("ACTIVITY_ID", withToken: token)
  }
}

`exit()`

退出 Live activity 删除活动标识符与我们服务器上的 Live Activity 推送令牌之间的关联。

OneSignal.LiveActivities.exit("ACTIVITY_ID")

`setPushToStartToken()`

推送启动 live activities 的可选”低级”方法。在不更改 ActivityAttribute 结构的情况下，对 LiveActivity 启动和更新令牌提供细粒度控制。此处提供更多详情

if #available(iOS 17.2, *) {
  // 设置异步任务以监控并向 OneSignalSDK 发送 pushToStartToken 更新。
  Task {
      for try await data in Activity<MyWidgetAttributes>.pushToStartTokenUpdates {
          let token = data.map {String(format: "%02x", $0)}.joined()
          OneSignal.LiveActivities.setPushToStartToken(MyWidgetAttributes.self, withToken: token)
      }
  }
  // 设置异步任务以监控活动的启动，对于每个已启动的活动我们
  // can then set up an async task to monitor and send updateToken updates to OneSignalSDK.
  Task {
      for await activity in Activity<MyWidgetAttributes>.activityUpdates {
        Task {
            for await pushToken in activity.pushTokenUpdates {
                let token = pushToken.map {String(format: "%02x", $0)}.joined()
                OneSignal.LiveActivities.enter("my-activity-id", withToken: token)
            }
        }
      }
  }
}

`removePushToStartToken()`

Called per-activity-type whenever that activity type should no longer be registered against the current subscription

OneSignal.LiveActivities.removePushToStartToken(MyWidgetAttributes.self)

结果

跟踪用户采取的操作并将其归因于消息。有关更多详情，请参阅结果。

`addOutcome()`

添加具有提供名称的结果，针对当前会话捕获。

OneSignal.Session.addOutcome("OUTCOME_NAME")

`addUniqueOutcome()`

添加具有提供名称的唯一结果，针对当前会话捕获。

OneSignal.Session.addUniqueOutcome("OUTCOME_NAME")

`addOutcomeWithValue()`

添加具有提供名称和值的结果，针对当前会话捕获。

OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14)

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

旧版 SDK 参考

​设置和调试

​initialize()

​setLogLevel()

​setAlertLevel()

​用户身份和属性

​login(external_id)

​logout()

​getOnesignalId()

​getExternalId()

​addObserver() user state

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

​setLanguage()

​自定义事件

​trackEvent()

​数据标签

​addTag(), addTags()

​removeTag(), removeTags()

​getTags()

​隐私

​setConsentRequired()

​setConsentGiven()

​位置

​setShared() location

​requestPermission() location

​订阅

​User.pushSubscription.id

​User.pushSubscription.token

​addObserver() push subscription changes

​optOut(), optIn(), optedIn

​addEmail(), removeEmail()

​addSms(), removeSms()

​推送权限

​requestPermission(fallbackToSettings) push

​addPermissionObserver() push

​getPermission(), getCanRequestPermission()

​permissionNative iOS

​推送通知事件

​addClickListener() push

​addForegroundLifecycleListener() push

​clearAllNotifications()

​removeNotification() Android

​removeGroupedNotifications() Android

​应用内消息

​addTrigger(), addTriggers()

​removeTrigger(), removeTriggers(), clearTriggers()

​paused

​addLifecycleListener()

​addClickListener() in-app

​Live Activity

​setup()

​setupDefault()

​enter()

​exit()

​setPushToStartToken()

​removePushToStartToken()

​结果

​addOutcome()

​addUniqueOutcome()

​addOutcomeWithValue()

设置和调试

`initialize()`

`setLogLevel()`

`setAlertLevel()`

用户身份和属性

`login(external_id)`

`logout()`

`getOnesignalId()`

`getExternalId()`

`addObserver()` user state

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

`setLanguage()`

自定义事件

`trackEvent()`

数据标签

`addTag()`, `addTags()`

`removeTag()`, `removeTags()`

`getTags()`

隐私

`setConsentRequired()`

`setConsentGiven()`

位置

`setShared()` location

`requestPermission()` location

订阅

`User.pushSubscription.id`

`User.pushSubscription.token`

`addObserver()` push subscription changes

`optOut()`, `optIn()`, `optedIn`

`addEmail()`, `removeEmail()`

`addSms()`, `removeSms()`

推送权限

`requestPermission(fallbackToSettings)` push

`addPermissionObserver()` push

`getPermission()`, `getCanRequestPermission()`

`permissionNative` iOS

推送通知事件

`addClickListener()` push

`addForegroundLifecycleListener()` push

`clearAllNotifications()`

`removeNotification()` Android

`removeGroupedNotifications()` Android

应用内消息

`addTrigger()`, `addTriggers()`

`removeTrigger()`, `removeTriggers()`, `clearTriggers()`

`paused`

`addLifecycleListener()`

`addClickListener()` in-app

Live Activity

`setup()`

`setupDefault()`

`enter()`

`exit()`

`setPushToStartToken()`

`removePushToStartToken()`

结果

`addOutcome()`

`addUniqueOutcome()`

`addOutcomeWithValue()`