> ## Documentation Index > Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt > Use this file to discover all available pages before exploring further. # 移动 SDK 参考 > OneSignal 移动 SDK 的综合 API 参考，包括初始化、用户身份、订阅、标签、权限、应用内消息、Live Activities 等。支持 Android、iOS、Unity、React Native、Flutter 和 Cordova/Ionic 平台。 ## 设置和调试 这些方法是将 OneSignal SDK 集成到您的应用程序中的参考。有关完整的特定平台设置说明，请参阅[移动 SDK 设置](./mobile-sdk-setup)。 ### `initialize()` 初始化 OneSignal SDK。这应该在应用程序启动期间调用。`ONESIGNAL_APP_ID` 可以在[密钥和 ID](./keys-and-ids) 中找到。 如果您想延迟 OneSignal SDK 的初始化，我们建议使用我们的[隐私方法](#privacy)。 ```kotlin Kotlin theme={null} OneSignal.initWithContext(this, ONESIGNAL_APP_ID) ``` ```java Java theme={null} OneSignal.initWithContext(this, ONESIGNAL_APP_ID); ``` ```swift Swift theme={null} import OneSignalFramework OneSignal.initialize("ONESIGNAL_APP_ID", withLaunchOptions: launchOptions) ``` ```objectivec Objective-C theme={null} #import [OneSignal initialize:@"ONESIGNAL_APP_ID" withLaunchOptions:launchOptions]; ``` ```csharp C# theme={null} OneSignal.Initialize("ONESIGNAL_APP_ID"); ``` ```javascript React Native theme={null} OneSignal.initialize("ONESIGNAL_APP_ID"); ``` ```dart Flutter theme={null} OneSignal.initialize("ONESIGNAL_APP_ID"); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.initialize("ONESIGNAL_APP_ID"); // Cordova window.plugins.OneSignal.initialize("ONESIGNAL_APP_ID"); ``` ### `setLogLevel()` 设置日志记录以向 Android LogCat 或 Xcode 日志打印额外日志。 在初始化 OneSignal *之前*调用此方法。有关更多详情，请参阅[获取调试日志](./capturing-a-debug-log)。 ```kotlin Kotlin theme={null} // LogLevel: .None | .Fatal | .Error | .Warn | .Info | .Debug | .Verbose OneSignal.Debug.logLevel = LogLevel.Verbose ``` ```java Java theme={null} // LogLevel: NONE | FATAL | ERROR | WARN | INFO | DEBUG | VERBOSE OneSignal.getDebug().setLogLevel(OneSignal.LOG_LEVEL.VERBOSE); ``` ```swift Swift theme={null} // LogLevel: ONE_S_LL_NONE | ONE_S_LL_FATAL | ONE_S_LL_ERROR | ONE_S_LL_WARN | ONE_S_LL_INFO | ONE_S_LL_DEBUG | ONE_S_LL_VERBOSE OneSignal.Debug.setLogLevel(.LL_VERBOSE) ``` ```objc Objective-C theme={null} // LogLevel: ONE_S_LL_NONE | ONE_S_LL_FATAL | ONE_S_LL_ERROR | ONE_S_LL_WARN | ONE_S_LL_INFO | ONE_S_LL_DEBUG | ONE_S_LL_VERBOSE [OneSignal.Debug setLogLevel:ONE_S_LL_VERBOSE]; ``` ```csharp C# theme={null} // LogLevel: None | Fatal | Error | Warn | Info | Debug | Verbose OneSignal.Debug.LogLevel = LogLevel.Verbose; ``` ```javascript React Native theme={null} OneSignal.Debug.setLogLevel(LogLevel.Verbose); ``` ```dart Flutter theme={null} OneSignal.Debug.setLogLevel(OSLogLevel.verbose); ``` ```javascript Cordova/Ionic theme={null} // Ionic // 0 = None, 1 = Fatal, 2 = Errors, 3 = Warnings, 4 = Info, 5 = Debug, 6 = Verbose OneSignal.Debug.setLogLevel(6); // Cordova // 0 = None, 1 = Fatal, 2 = Errors, 3 = Warnings, 4 = Info, 5 = Debug, 6 = Verbose window.plugins.OneSignal.Debug.setLogLevel(6); ``` ### `setAlertLevel()` 设置日志级别以在您的应用中显示为警报对话框。确保在提交到应用商店之前移除此设置。 ```kotlin Kotlin theme={null} OneSignal.Debug.alertLevel = LogLevel.Exception ``` ```java Java theme={null} OneSignal.getDebug.setAlertLevel(LogLevel.Exception); ``` ```swift Swift theme={null} OneSignal.Debug.setAlertLevel(.LL_NONE) ``` ```objc Objective-C theme={null} [OneSignal.Debug setAlertLevel:ONE_S_LL_NONE]; ``` ```csharp C# theme={null} // LogLevel: None | Fatal | Error | Warn | Info | Debug | Verbose OneSignal.Debug.AlertLevel = LogLevel.None; ``` ```javascript React Native theme={null} OneSignal.Debug.setAlertLevel(LogLevel.Verbose); ``` ```dart Flutter theme={null} OneSignal.Debug.setAlertLevel(OSLogLevel.none); ``` ```javascript Cordova/Ionic theme={null} // Ionic // 0 = None, 1 = Fatal, 2 = Errors, 3 = Warnings, 4 = Info, 5 = Debug, 6 = Verbose OneSignal.Debug.setAlertLevel(0); // Cordova // 0 = None, 1 = Fatal, 2 = Errors, 3 = Warnings, 4 = Info, 5 = Debug, 6 = Verbose window.plugins.OneSignal.Debug.setAlertLevel(0); ``` ## 用户身份和属性 当用户打开您的应用时，OneSignal 自动创建一个 OneSignal ID（用户级别）和一个订阅 ID（设备级别）。您可以通过使用您的唯一用户标识符调用 `login()` 将多个订阅（如设备、电子邮件、电话号码）与单个用户关联。 有关更多详情，请参阅[用户](./users)和[别名](./aliases)。 ### `login(external_id)` 将用户上下文设置为提供的 `external_id`。确保与此 `external_id` 相关联的所有订阅和属性在单个 `onesignal_id` 下统一。有关更多详情，请参阅[用户](./users)。 **关键行为：** * 如果 `external_id` 已存在，SDK 将切换到该用户。登录前收集的匿名数据不会合并，将被丢弃。 * 如果 `external_id` 不存在，本地状态将保存在当前 `onesignal_id` 下。用户匿名时收集的任何数据将被保留。 * SDK 在网络故障或服务器错误时自动重试。 每次用户打开应用时调用此方法，以确保设置外部 ID 并将订阅链接到用户。 ```kotlin Kotlin theme={null} OneSignal.login("external_id") ``` ```java Java theme={null} OneSignal.login("external_id"); ``` ```swift Swift theme={null} OneSignal.login("external_id") ``` ```objc Objective-C theme={null} [OneSignal login:@"external_id"]; ``` ```csharp C# theme={null} OneSignal.Login("external_id"); ``` ```javascript React Native theme={null} OneSignal.login("external_id"); ``` ```dart Flutter theme={null} OneSignal.login("external_id"); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.login("external_id"); // Cordova window.plugins.OneSignal.login("external_id"); ``` ### `logout()` 将当前用户与订阅取消链接。 * 从当前推送订阅中移除 `external_id`。 * 将 OneSignal ID 重置为新的匿名用户。 * 任何新数据（如标签、订阅、会话数据等）现在将设置在新的匿名用户上，直到通过 `login` 方法识别他们。 当用户退出您的应用且您希望将订阅设置为新的匿名用户时使用此方法。 ```kotlin Kotlin theme={null} OneSignal.logout() ``` ```java Java theme={null} OneSignal.logout(); ``` ```swift Swift theme={null} OneSignal.logout() ``` ```objc Objective-C theme={null} [OneSignal logout] ``` ```csharp C# theme={null} OneSignal.Logout(); ``` ```javascript React Native theme={null} OneSignal.logout(); ``` ```dart Flutter theme={null} OneSignal.logout(); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.logout(); // Cordova window.plugins.OneSignal.logout(); ``` ### `getOnesignalId()` Retrieve the current OneSignal ID. May be `null` if called before user state is initialized. Instead, use [User State `addObserver()`](#addobserver-user-state) to listen for user state changes. ```kotlin Kotlin theme={null} val id = OneSignal.User.onesignalId ``` ```java Java theme={null} String id = OneSignal.getUser().getOnesignalId(); ``` ```swift Swift theme={null} let id = OneSignal.User.onesignalId //Example func getOneSignalId() async { if let id = OneSignal.User.onesignalId { print("OneSignal ID:", id) } else { print("OneSignal ID not available, try again.") } } ``` ```objc Objective-C theme={null} NSString* id = OneSignal.User.onesignalId ``` ```csharp C# theme={null} OneSignal.User.OneSignalId; ``` ```javascript React Native theme={null} await OneSignal.User.getOnesignalId(); //Example const getOneSignalId = async () => { try { const id = await OneSignal.User.getOnesignalId(); console.log('OneSignal ID:', id); Alert.alert('OneSignal ID', id || 'No ID available'); } catch (error) { console.error('Error getting OneSignal ID:', error); Alert.alert('Error', 'Failed to get OneSignal ID'); } }; ``` ```dart Flutter theme={null} await OneSignal.User.getOnesignalId(); ``` ```javascript Cordova/Ionic theme={null} // Ionic await OneSignal.User.getOnesignalId(); // Cordova await window.plugins.OneSignal.User.getOnesignalId(); ``` ### `getExternalId()` Retrieve the current External ID. May be `null` if not set or called before user state is initialized. Instead, use [User State `addObserver()`](#addobserver-user-state) to listen for user state changes. ```kotlin Kotlin theme={null} val id = OneSignal.User.externalId ``` ```java Java theme={null} String id = OneSignal.getUser().getExternalId(); ``` ```swift Swift theme={null} let id: String? = OneSignal.User.externalId ``` ```objc Objective-C theme={null} NSString* id = OneSignal.User.externalId ``` ```csharp C# theme={null} OneSignal.User.ExternalId ``` ```javascript React Native theme={null} await OneSignal.User.getExternalId(); //Example const getExternalId = async () => { try { const id = await OneSignal.User.getExternalId(); console.log('External ID:', id); Alert.alert('External ID', id || 'No ID available'); } catch (error) { console.error('Error getting External ID:', error); Alert.alert('Error', 'Failed to get External ID'); } }; ``` ```dart Flutter theme={null} await OneSignal.User.getExternalId(); ``` ```javascript Cordova/Ionic theme={null} // Ionic await OneSignal.User.getExternalId(); // Cordova await window.plugins.OneSignal.User.getExternalId(); ``` ### `addObserver()` *user state* 监听用户上下文的变化（如登录、注销、ID 分配）。 ```kotlin Kotlin theme={null} OneSignal.User.addObserver(object : IUserStateObserver { override fun onUserStateChange(state: UserChangedState) { println("User State Changed: onesignalId=${state.current.onesignalId}, externalId=${state.current.externalId}") } }) ``` ```java Java theme={null} OneSignal.getUser().addObserver(userChangedState -> { Log.d("User State Changed", String.valueof(userChangedState.toJSONObject())); }); ``` ```swift Swift theme={null} // AppDelegate.swift // Add OSUserStateObserver after UIApplicationDelegate class AppDelegate: UIResponder, UIApplicationDelegate, OSUserStateObserver { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { // 将您的 AppDelegate 添加为观察者 OneSignal.User.addObserver(self) } // 添加此新方法 func onUserStateDidChange(state: OSUserChangedState) { // prints out all properties print("OSUserChangedState: \n\(state.jsonRepresentation())") print(state.current.externalId) print(state.current.onesignalId) } } // Remove the observer OneSignal.User.removeObserver(self) ``` ```objc Objective-C theme={null} // AppDelegate.h // Add OSUserStateObserver after UIApplicationDelegate @interface AppDelegate : UIResponder @end // AppDelegate.m @implementation AppDelegate - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // 将您的 AppDelegate 添加为观察者 [OneSignal.User addObserver:self]; } // 添加这个新方法 - (void)onUserStateDidChangeWithState:(OSUserChangedState * _Nonnull)state { // prints out all properties NSLog(@"OSUserChangedState:\n%@", [state jsonRepresentation]); NSLog(@"current externalId: %@", state.current.externalId); NSLog(@"current onesignalId: %@", state.current.onesignalId); } @end // Remove the observer [OneSignal.User removeObserver:self]; ``` ```csharp C# theme={null} OneSignal.User.Changed += _userStateChanged; private void _userStateChanged(object sender, UserStateChangedEventArgs e) { ... } ``` ```javascript React Native theme={null} const listener = (event: UserChangedState) => { console.log("User changed: " + (event)); }; OneSignal.User.addEventListener("change", listener); // Remove the listener OneSignal.User.removeEventListener("change", listener); ``` ```dart Flutter theme={null} OneSignal.User.addObserver((state) { var userState = state.jsonRepresentation(); print('OneSignal user changed: $userState'); }); /// 移除之前添加的用户状态观察者。 OneSignal.User.removeObserver(observer); ``` ```javascript Cordova/Ionic theme={null} // Ionic const listener = (event: UserChangedState) => { console.log("User changed: " + (event)); }; OneSignal.User.addEventListener("change", listener); // Remove the listener OneSignal.User.removeEventListener("change", listener); // Cordova window.plugins.OneSignal.User.addEventListener("change", listener); window.plugins.OneSignal.User.removeEventListener("change", listener); ``` ### `addAlias()`, `addAliases()`, `removeAlias()`, `removeAliases()` 别名是替代标识符（如用户名或 CRM ID）。 * 在添加别名之前使用 `login()` 设置 `external_id`。添加到没有 `external_id` 的订阅的别名不会在多个订阅间同步。 * 详情请参阅[别名](./aliases)。 ```kotlin Kotlin theme={null} // 添加单个别名 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"]) ``` ```java Java theme={null} // 添加单个别名 OneSignal.getUser().addAlias("ALIAS_LABEL", "ALIAS_ID"); // 添加多个别名 HashMap aliases = new HashMap(); aliases.put("ALIAS_LABEL_01", "ALIAS_ID_01"); aliases.put("ALIAS_LABEL_02", "ALIAS_ID_02"); OneSignal.getUser().addAliases(aliases); // 移除单个别名 OneSignal.getUser().removeAlias("ALIAS_LABEL") // 移除多个别名 HashSet labels = new HashSet(); labels.add("ALIAS_LABEL_01"); labels.add("ALIAS_LABEL_02"); OneSignal.getUser().removeAliases(labels); ``` ```swift Swift theme={null} // 添加单个别名 OneSignal.User.addAlias(label: "ALIAS_LABEL", id: "ALIAS_ID") // 添加多个别名 OneSignal.User.addAliases(["ALIAS_LABEL_01": "ALIAS_ID_01", "ALIAS_LABEL_02": "ALIAS_ID_02"]) // 移除单个别名 OneSignal.User.removeAlias("ALIAS_LABEL") // 移除多个别名 OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]) ``` ```objc Objective-C theme={null} // 添加单个别名 [OneSignal.User addAliasWithLabel:@"ALIAS_LABEL" id:@"ALIAS_ID"]; // 添加多个别名 [OneSignal.User addAliases:@{@"ALIAS_LABEL_01": @"ALIAS_ID_01", @"ALIAS_LABEL_02": @"ALIAS_ID_02"}] // 移除单个别名 [OneSignal.User removeAlias:@"ALIAS_LABEL"] // 移除多个别名 [OneSignal.User removeAliases:@[@"ALIAS_LABEL_01", @"ALIAS_LABEL_02"]] ``` ```csharp C# theme={null} // 添加单个别名 OneSignal.User.AddAlias("ALIAS_LABEL", "ALIAS_ID"); // 添加多个别名 OneSignal.User.AddAliases(new Dictionary { { "ALIAS_LABEL_01", "ALIAS_ID_01" }, { "ALIAS_LABEL_02", "ALIAS_ID_02" } }); // 移除单个别名 OneSignal.User.RemoveAlias("ALIAS_LABEL"); // 移除多个别名 OneSignal.User.RemoveAliases(new[] {"ALIAS_LABEL_01", "ALIAS_LABEL_02"}); ``` ```javascript React Native theme={null} // 添加单个别名 OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID"); // 添加多个别名 OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"}); // 移除单个别名 OneSignal.User.removeAlias("ALIAS_LABEL"); // 移除多个别名 OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]); ``` ```dart Flutter theme={null} // 添加单个别名 OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID"); // 添加多个别名 var aliases = { "alias_key_1": "alias_id_1", "alias_key_2": "alias_id_2" }; OneSignal.User.addAliases(aliases); // 移除单个别名 OneSignal.User.removeAlias("ALIAS_LABEL"); // 移除多个别名 var aliases = ["alias_key_1", "alias_key_2"]; OneSignal.User.removeAliases(aliases); ``` ```javascript Cordova/Ionic theme={null} // 添加单个别名 - Ionic OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID"); // 添加单个别名 - Cordova window.plugins.OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID"); // 添加多个别名 - Ionic OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"}); // 添加多个别名 - Cordova window.plugins.OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"}); // 移除单个别名 - Ionic OneSignal.User.removeAlias("ALIAS_LABEL"); // 移除单个别名 - Cordova window.plugins.OneSignal.User.removeAlias("ALIAS_LABEL"); // 移除多个别名 - Ionic OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]); // 移除多个别名 - Cordova window.plugins.OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]); ``` ### `setLanguage()` 覆盖用户的自动检测语言。使用 [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes?useskin=vector) 语言代码。 ```kotlin Kotlin theme={null} OneSignal.User.setLanguage("en") ``` ```java Java theme={null} OneSignal.getUser().setLanguage("en"); ``` ```swift Swift theme={null} OneSignal.User.setLanguage("en") ``` ```objc Objective-C theme={null} [OneSignal.User setLanguage:@"en"] ``` ```csharp C# theme={null} OneSignal.User.Language = "en"; ``` ```javascript React Native theme={null} OneSignal.User.setLanguage("en"); ``` ```dart Flutter theme={null} OneSignal.User.setLanguage("en"); ``` ```javascript Cordova/Ionic theme={null} window.plugins.OneSignal.User.setLanguage("en"); ``` *** ## 自定义事件 使用相关属性追踪用户操作。有关更多信息，请参阅[自定义事件](./custom-events)。 自定义事件需要以下最低 SDK 版本：iOS `5.4.0`，Android `5.6.1`，React Native `5.3.0`，Flutter `5.4.0`，Unity `5.2.0`。 跟踪并发送当前用户执行的自定义事件。 * `name` - **必需。** 事件名称作为字符串。 * `properties` - **可选。** 要添加到事件的键值对。属性字典或映射必须可序列化为有效的 JSON 对象。 SDK 自动将应用特定数据包含到属性负载中的保留键 `os_sdk` 下，以供使用。例如，要按设备类型定向事件，您将访问 `os_data.device_type`。 ```json json theme={null} { "os_sdk": { "sdk": "050213", "device_os": "18.5", "type": "iOSPush", "device_model": "iPhone14,4", "device_type": "ios", "app_version": "5.4.0" } } ``` ### `trackEvent()` ```kotlin Kotlin theme={null} 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") ``` ```java Java theme={null} Map additionalData = new HashMap<>(); additionalData.put("signed_up_with_email", true); additionalData.put("products_viewed_count", 15); additionalData.put("names", Map.of("a", Map.of("b", 5.2))); Map properties = new HashMap<>(); properties.put("promo_code", "NEW50"); properties.put("additional_data", additionalData); OneSignal.getUser().trackEvent("started_free_trial", properties); // 您也可以按名称跟踪事件，无需关联的额外属性 OneSignal.getUser().trackEvent("my_event_name", null); ``` ```swift Swift theme={null} // 属性字典必须可序列化为有效的 JSON 对象。 let myProperties = [ "promo_code": "NEW50", "additional_data": [ "signed_up_with_email": true, "products_viewed_count": 15 ] ] OneSignal.User.trackEvent(name: "started_free_trial", properties: myProperties) // 您也可以按名称跟踪事件，无需关联的额外属性 OneSignal.User.trackEvent(name: "my_event_name", properties: nil) ``` ```objc Objective-C theme={null} // 属性字典必须可序列化为有效的 JSON 对象。 NSDictionary *myProperties = @{ @"promo_code" : @"NEW50", @"additional_data" : @{ @"signed_up_with_email" : @true, @"products_viewed_count" : @15 } }; [OneSignal.User trackEventWithName:@"started_free_trial" properties:myProperties]; // 您也可以按名称跟踪事件，无需关联的额外属性 [OneSignal.User trackEventWithName:@"my_event_name" properties:nil]; ``` ```csharp Unity C# theme={null} COMING SOON ``` ```javascript React Native theme={null} COMING SOON ``` ```dart Flutter theme={null} COMING SOON ``` ```javascript Cordova/Ionic theme={null} COMING SOON ``` ## 数据标签 标签是您基于事件或用户属性在用户上设置的自定义 `key : value` 字符串数据对。有关更多详情，请参阅[数据标签](./add-user-data-tags)。 ### `addTag()`, `addTags()` 在当前用户上设置单个或多个标签。 * 如果键已存在，值将被替换。 * 超过您计划的标签限制将导致操作静默失败。 ```kotlin Kotlin theme={null} OneSignal.User.addTag("KEY", "VALUE") OneSignal.User.addTags(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02")) ``` ```java Java theme={null} OneSignal.getUser().addTag("KEY", "VALUE"); OneSignal.getUser().addTags(new HashMap() {{ put("KEY_01", "VALUE_01"); put("KEY_02", "VALUE_02"); }}); ``` ```swift Swift theme={null} OneSignal.User.addTag(key: "KEY", value: "VALUE") OneSignal.User.addTags(["KEY_01": "VALUE_01", "KEY_02": "VALUE_02"]) ``` ```objc Objective-C theme={null} [OneSignal.User addTag:@"KEY" value:@"VALUE"]; [OneSignal.User addTags:@{@""KEY_01"": @""VALUE_01"", @""KEY_02"": @""VALUE_02""}]; ``` ```csharp C# theme={null} OneSignal.User.AddTag("KEY", "VALUE"); OneSignal.User.AddTags(new Dictionary { { "KEY_01", "VALUE_01" }, { "KEY_02", "VALUE_02" } }); ``` ```javascript React Native theme={null} OneSignal.User.addTag('KEY', 'VALUE'); OneSignal.User.addTags({my_tag1: 'my_value', my_tag2: 'my_value2'}); ``` ```dart Flutter theme={null} OneSignal.User.addTagWithKey("KEY", "VALUE"); var tags = {'test': 'value', 'test2': 'value2'}; OneSignal.User.addTags(tags); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.User.addTag("KEY", "VALUE"); OneSignal.User.addTags({"KEY_01": "VALUE_01", "KEY_02": "VALUE_02"}); // Cordova window.plugins.OneSignal.User.addTag("KEY", "VALUE"); window.plugins.OneSignal.User.addTags({"KEY_01": "VALUE_01", "KEY_02": "VALUE_02"}); ``` ### `removeTag()`, `removeTags()` 从当前用户删除单个或多个标签。 ```kotlin Kotlin theme={null} OneSignal.User.removeTag("KEY") OneSignal.User.removeTags(listOf("KEY_01", "KEY_02")) ``` ```java Java theme={null} OneSignal.getUser().removeTag("KEY"); OneSignal.getUser().removeTags(Arrays.asList("KEY_01", "KEY_02")); ``` ```swift Swift theme={null} OneSignal.User.removeTag("KEY") OneSignal.User.removeTags(["KEY_01", "KEY_02"]) ``` ```objc Objective-C theme={null} [OneSignal.User removeTag:@"KEY"]; [OneSignal.User removeTags:@[@""KEY_01"", @""KEY_02""]] ``` ```csharp C# theme={null} OneSignal.User.RemoveTag("KEY"); OneSignal.User.RemoveTags(new string[] { "KEY_01", "KEY_02" }); ``` ```javascript React Native theme={null} OneSignal.User.removeTag('my_tag1'); OneSignal.User.removeTags(['my_tag1', 'my_tag2']); ``` ```dart Flutter theme={null} OneSignal.User.removeTag("test"); OneSignal.User.removeTags(["test", "test2"]); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.User.removeTag("KEY"); OneSignal.User.removeTags(["KEY_01", "KEY_02"]); // Cordova window.plugins.OneSignal.User.removeTag("KEY"); window.plugins.OneSignal.User.removeTags(["KEY_01", "KEY_02"]); ``` ### `getTags()` 返回用户标签的本地副本。标签在 `login()` 或新应用会话期间从服务器更新。 ```kotlin Kotlin theme={null} val tags: Map = OneSignal.User.getTags() ``` ```java Java theme={null} Map tags = OneSignal.getUser().getTags(); ``` ```swift Swift theme={null} let tags = OneSignal.User.getTags() ``` ```objc Objective-C theme={null} NSDictionary *tags = [OneSignal.User getTags] ``` ```csharp C# theme={null} Dictionary tags = OneSignal.User.GetTags(); ``` ```javascript React Native theme={null} const getTags = async () => { const tags = await OneSignal.User.getTags(); console.log('Tags:', tags); }; ``` ```dart Flutter theme={null} const getTags = async () async { final tags = await OneSignal.User.getTags(); print('Tags: $tags'); }; ``` ```javascript Cordova/Ionic theme={null} // Ionic const getTags = async () => { const tags = await OneSignal.User.getTags(); console.log('Tags:', tags); }; // Cordova const getTags = async () => { const tags = await window.plugins.OneSignal.User.getTags(); console.log('Tags:', tags); }; ``` *** ## 隐私 ### `setConsentRequired()` 在数据收集开始前强制执行用户同意。必须在**初始化 SDK 之前**调用。 ```kotlin Kotlin theme={null} OneSignal.consentRequired = true ``` ```java Java theme={null} OneSignal.setConsentRequired(true); ``` ```swift Swift theme={null} OneSignal.setConsentRequired(true) ``` ```objc Objective-C theme={null} [OneSignal setConsentRequired:true]; ``` ```csharp C# theme={null} OneSignal.ConsentRequired = true; ``` ```javascript React Native theme={null} OneSignal.setConsentRequired(true); ``` ```dart Flutter theme={null} OneSignal.consentRequired(true); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.setConsentRequired(true); // Cordova window.plugins.OneSignal.setConsentRequired(true); ``` ### `setConsentGiven()` 授予或撤销用户对数据收集的同意。没有同意，不会向 OneSignal 发送数据，也不会创建订阅。 * 如果 [`setConsentRequired()`](#setconsentrequired) 为 `true`，我们的 SDK 将不会完全启用，直到使用 `true` 调用 `setConsentGiven`。 * 如果 `setConsentGiven` 设置为 `true` 并创建了订阅，然后将其设置为 `false`，该订阅将不再接收更新。该订阅的当前数据保持不变，直到 `setConsentGiven` 再次设置为 `true`。 * 如果您想删除用户和/或订阅数据，请使用我们的[删除用户](/reference/delete-user)或[删除订阅](/reference/delete-subscription) API。 ```kotlin Kotlin theme={null} OneSignal.consentGiven = true ``` ```java Java theme={null} OneSignal.setConsentGiven(true); ``` ```swift Swift theme={null} OneSignal.setConsentGiven(true) ``` ```objc Objective-C theme={null} [OneSignal setConsentGiven:true]; ``` ```csharp C# theme={null} OneSignal.ConsentGiven = true; ``` ```javascript React Native theme={null} OneSignal.setConsentGiven(true); ``` ```dart Flutter theme={null} OneSignal.consentGiven(true); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.setConsentGiven(true); // Cordova window.plugins.OneSignal.setConsentGiven(true); ``` *** ## 位置 跟踪位置点需要 3 个步骤： 1. 向您的应用添加位置跟踪权限和依赖项。 * **iOS**: [选择要请求的位置服务授权开发者指南](https://developer.apple.com/documentation/bundleresources/choosing-the-location-services-authorization-to-request) * **Android**: [请求位置权限开发者指南](https://developer.android.com/develop/sensors-and-location/location/permissions) 您可能会遇到以下错误： > LocationManager.startGetLocation: not possible, no location dependency found 检查您应用的依赖项。常见解决方案是在您的 `app/build.gradle` 中添加：`implementation 'com.google.android.gms:play-services-location:21.0.1'` 2. 使用 `Location.setShared()` 方法启用您的应用与 OneSignal 共享位置。 3. 使用 `Location.requestPermission` 方法或[使用应用内消息](./location-opt-in-prompt)向用户请求位置跟踪权限。 ### `setShared()` *location* 使用此方法允许我们的 SDK 开始跟踪订阅的纬度和经度。确保您首先在应用中设置了正确的[位置权限](#location)。 ```kotlin Kotlin theme={null} // 启用您的应用与 OneSignal 共享位置 OneSignal.Location.isShared = true // 如果您的应用与 OneSignal 共享位置，则返回 true var isShared: Boolean = OneSignal.isShared ``` ```java Java theme={null} // 启用您的应用与 OneSignal 共享位置 OneSignal.getLocation().setShared(true); // 如果您的应用与 OneSignal 共享位置，则返回 true boolean isShared = OneSignal.Location.isShared(); ``` ```swift Swift theme={null} // 启用您的应用与 OneSignal 共享位置 OneSignal.Location.isShared = true // 如果您的应用与 OneSignal 共享位置，则返回 true let locationShared = OneSignal.Location.isShared ``` ```objc Objective-C theme={null} // 启用您的应用与 OneSignal 共享位置 [OneSignal.Location setShared:true]4 // 如果您的应用与 OneSignal 共享位置，则返回 true BOOL locationShared = [OneSignal isLocationShared]; ``` ```csharp C# theme={null} // 启用您的应用与 OneSignal 共享位置 OneSignal.Location.IsShared = true; // 如果您的应用与 OneSignal 共享位置，则返回 true bool isShared = OneSignal.Location.IsShared; ``` ```javascript React Native theme={null} // 启用您的应用与 OneSignal 共享位置 OneSignal.Location.setShared(true); // 如果您的应用与 OneSignal 共享位置，则返回 true OneSignal.Location.isShared(); ``` ```dart Flutter theme={null} // 启用您的应用与 OneSignal 共享位置 OneSignal.Location.setShared(true); // 如果您的应用与 OneSignal 共享位置，则返回 true OneSignal.Location.isShared(); ``` ```javascript Cordova/Ionic theme={null} // Ionic // 启用您的应用与 OneSignal 共享位置 OneSignal.Location.setShared(true); // 如果您的应用与 OneSignal 共享位置，则返回 true OneSignal.Location.isShared(isShared => { console.log("Location shared: ", isShared); }); // Cordova // 启用您的应用与 OneSignal 共享位置 window.plugins.OneSignal.Location.setShared(true); // 如果您的应用与 OneSignal 共享位置，则返回 true window.plugins.OneSignal.Location.isShared(isShared => { ``` ### `requestPermission()` *location* 使用此方法向您的用户显示系统级位置权限提示，或者[使用应用内消息](./location-opt-in-prompt)。确保您在应用中设置了正确的[位置权限](#location)并启用了您的应用与 OneSignal 共享位置。 ```kotlin Kotlin theme={null} // 请求位置跟踪权限 OneSignal.Location.requestPermission(true) ``` ```java Java theme={null} // 请求位置跟踪权限 OneSignal.getLocation().requestPermission(Continue.none()); ``` ```swift Swift theme={null} // 请求位置跟踪权限 OneSignal.Location.requestPermission() ``` ```objc Objective-C theme={null} // 请求位置跟踪权限 [OneSignal.Location requestPermission]; ``` ```csharp C# theme={null} // 请求位置跟踪权限 OneSignal.Location.RequestPermission(); ``` ```javascript React Native theme={null} // 请求位置跟踪权限 OneSignal.Location.requestPermission(); ``` ```dart Flutter theme={null} // 请求位置跟踪权限 OneSignal.Location.requestPermission(); ``` ```javascript Cordova/Ionic theme={null} // Ionic // 请求位置跟踪权限 OneSignal.Location.requestPermission(); // Cordova // 请求位置跟踪权限 window.plugins.OneSignal.Location.requestPermission(); ``` *** ## 订阅 有关更多详细信息，请参阅[订阅](./subscriptions)。 ### `User.pushSubscription.id` 返回当前推送订阅 ID。如果调用过早可能返回 `null`。建议在[订阅观察者](#addobserver-push-subscription-changes)中获取此数据以响应变化。 ```kotlin Kotlin theme={null} val id = OneSignal.User.pushSubscription.id ``` ```java Java theme={null} String id = OneSignal.getUser().getPushSubscription().getId(); ``` ```swift Swift theme={null} let id: String? = OneSignal.User.pushSubscription.id ``` ```objc Objective-C theme={null} NSString* id = OneSignal.User.pushSubscription.id ``` ```csharp C# theme={null} OneSignal.User.PushSubscription.Id; ``` ```javascript React Native theme={null} await OneSignal.User.pushSubscription.getIdAsync(); //Example const getPushId = async () => { try { const id = await OneSignal.User.pushSubscription.getIdAsync(); console.log('Push Subscription ID:', id); Alert.alert('Push Subscription ID', id || 'No ID available'); } catch (error) { console.error('Error getting push ID:', error); Alert.alert('错误', '获取推送订阅 ID 失败'); } }; ``` ```dart Flutter theme={null} OneSignal.User.pushSubscription.id; ``` ```javascript Cordova/Ionic theme={null} // Ionic await OneSignal.User.pushSubscription.getIdAsync(); // Cordova await window.plugins.OneSignal.User.pushSubscription.getIdAsync(); ``` ### `User.pushSubscription.token` 返回当前推送订阅令牌。如果调用过早可能返回 `null`。建议在[订阅观察者](#addobserver-push-subscription-changes)中获取此数据以响应变化。 ```kotlin Kotlin theme={null} val pushToken = OneSignal.User.pushSubscription.token ``` ```java Java theme={null} String pushToken = OneSignal.getUser().getPushSubscription().getToken(); ``` ```swift Swift theme={null} let token: String? = OneSignal.User.pushSubscription.token ``` ```objc Objective-C theme={null} NSString* token = OneSignal.User.pushSubscription.token ``` ```csharp C# theme={null} OneSignal.User.PushSubscription.Token; ``` ```javascript React Native theme={null} await OneSignal.User.pushSubscription.getTokenAsync(); ``` ```dart Flutter theme={null} OneSignal.User.pushSubscription.token; ``` ```javascript Cordova/Ionic theme={null} // Ionic await OneSignal.User.pushSubscription.getTokenAsync(); // Cordova await window.plugins.OneSignal.User.pushSubscription.getTokenAsync(); ``` ### `addObserver()` *push subscription changes* 使用此方法响应推送订阅变化，如： * 设备从 Google (FCM) 或 Apple (APNs) 接收新的推送令牌 * OneSignal 分配订阅 ID * `optedIn` 值发生变化（如调用 `optIn()` 或 `optOut()`） * 用户在系统设置中切换推送权限，然后打开应用 当这种情况发生时，SDK 触发 `onPushSubscriptionChange` 事件。您的监听器接收具有 `previous` 和 `current` 值的状态对象，因此您可以准确检测发生了什么变化。 要停止监听更新，请调用相关的 `removeObserver()` 或 `removeEventListener()` 方法。 ```kotlin Kotlin theme={null} 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) ``` ```java Java theme={null} //Add the IPushSubscriptionObserver public class MainActivity extends Activity implements IPushSubscriptionObserver { protected void onCreate(Bundle savedInstanceState) { //Add the addObserver method OneSignal.getUser().getPushSubscription().addObserver(this); } // 当订阅属性发生变化时将触发此方法 @Override public void onPushSubscriptionChange(@NotNull PushSubscriptionChangedState pushSubscriptionChangedState) { //获取订阅 ID 的示例 Log.i("OneSignal", "current subscription ID: " + pushSubscriptionChangedState.getCurrent().getId() ); } } // Remove the observer OneSignal.getUser().getPushSubscription().removeObserver(this); ``` ```swift Swift theme={null} // AppDelegate.swift // Add OSPushSubscriptionObserver after UIApplicationDelegate class AppDelegate: UIResponder, UIApplicationDelegate, OSPushSubscriptionObserver { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { // 将您的 AppDelegate 添加为观察者 OneSignal.User.pushSubscription.addObserver(self) } // 添加此新方法，当订阅属性发生变化时将触发 func onPushSubscriptionDidChange(state: OSPushSubscriptionChangedState) { // respond to state change } } // Remove the observer OneSignal.User.pushSubscription.removeObserver(self) ``` ```objc Objective-C theme={null} // AppDelegate.h // Add OSPushSubscriptionObserver after UIApplicationDelegate @interface AppDelegate : UIResponder @end // AppDelegate.m @implementation AppDelegate - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // 将您的 AppDelegate 添加为观察者 [OneSignal.User.pushSubscription addObserver:self]; } // 添加这个新方法，当订阅属性发生变化时将触发此方法 - (void)onPushSubscriptionDidChangeWithState:(OSPushSubscriptionChangedState *)state { // respond to new state } @end // Remove the observer [OneSignal.User.pushSubscription removeObserver:self]; ``` ```csharp C# theme={null} OneSignal.User.PushSubscription.Changed += (sender, e) => { if (e.State.Current.Id != e.State.Previous.Id) { // OneSignal Subscription id changed. } }; ``` ```javascript React Native theme={null} OneSignal.User.pushSubscription.addEventListener('change', (subscription) => { console.log('OneSignal: subscription changed:', subscription); }); // 移除之前添加的监听器 OneSignal.User.pushSubscription.removeEventListener('change', myListener); ``` ```dart Flutter theme={null} OneSignal.User.pushSubscription.addObserver((state) { if (state.current.optedIn) { /// respond to new state } }); // 移除之前添加的观察者 OneSignal.User.pushSubscription.removeObserver(myObserver); ``` ```javascript Cordova/Ionic theme={null} const listener = (event: PushSubscriptionChangedState) => { console.log("Push subscription changed: " + (event)); }; // Add the listener - Ionic OneSignal.User.pushSubscription.addEventListener("change", listener); // Remove the listener - Ionic OneSignal.User.pushSubscription.removeEventListener("change", listener); // Add the listener - Cordova window.plugins.OneSignal.User.pushSubscription.addEventListener("change", listener); // Remove the listener - Cordova window.plugins.OneSignal.User.pushSubscription.removeEventListener("change", listener); ``` ### `optOut()`, `optIn()`, `optedIn` 控制当前推送订阅的订阅状态（`subscribed` 或 `unsubscribed`）。使用这些方法在您的应用内控制推送订阅状态。常见用例：1）防止向注销的用户发送推送。2）在您的应用内实现通知偏好中心。 * `optOut()`：将当前推送订阅状态设置为未订阅（即使用户有有效的推送令牌）。 * `optIn()`：执行以下三个操作之一： 1. 如果订阅有有效的推送令牌，它将当前推送订阅状态设置为 `subscribed`。 2. 如果订阅没有有效的推送令牌，它显示推送权限提示。 3. 如果推送权限提示已显示超过操作系统的限制（iOS 一次，Android 两次），它显示回退提示。 * `optedIn`：如果当前推送订阅状态为已订阅，则返回 `true`，否则返回 `false`。如果推送令牌有效但调用了 `optOut()`，这将返回 `false`。 ```kotlin Kotlin theme={null} OneSignal.User.pushSubscription.optOut() OneSignal.User.pushSubscription.optIn() val optedIn = OneSignal.User.pushSubscription.optedIn ``` ```java Java theme={null} OneSignal.getUser().getPushSubscription().optOut(); OneSignal.getUser().getPushSubscription().optIn(); Boolean optedIn = OneSignal.getUser().getPushSubscription().getOptedIn(); ``` ```swift Swift theme={null} OneSignal.User.pushSubscription.optOut() OneSignal.User.pushSubscription.optIn() let optedIn: Bool = OneSignal.User.pushSubscription.optedIn ``` ```objc Objective-C theme={null} [OneSignal.User.pushSubscription optOut]; [OneSignal.User.pushSubscription optIn]; Boolean optedIn = OneSignal.User.subscriptions.push.optedIn; ``` ```csharp C# theme={null} OneSignal.User.PushSubscription.OptOut(); OneSignal.User.PushSubscription.OptIn(); OneSignal.User.PushSubscription.OptedIn; ``` ```javascript React Native theme={null} OneSignal.User.pushSubscription.optOut(); OneSignal.User.pushSubscription.optIn(); await OneSignal.User.pushSubscription.getOptedInAsync(); ``` ```dart Flutter theme={null} OneSignal.User.pushSubscription.optOut(); OneSignal.User.pushSubscription.optIn(); OneSignal.User.pushSubscription.optedIn; ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.User.pushSubscription.optOut(); OneSignal.User.pushSubscription.optIn(); await OneSignal.User.pushSubscription.getOptedInAsync(); // Cordova window.plugins.OneSignal.User.pushSubscription.optOut(); window.plugins.OneSignal.User.pushSubscription.optIn(); await window.plugins.OneSignal.User.pushSubscription.getOptedInAsync(); ``` ### `addEmail()`, `removeEmail()` 向当前用户添加或移除电子邮件订阅（电子邮件地址）。在 `login()` 后调用 `addEmail` 以设置正确的用户上下文。与[身份验证](./identity-verification)兼容。 ```kotlin Kotlin theme={null} OneSignal.User.addEmail("example@email.com") OneSignal.User.removeEmail("example@email.com") ``` ```java Java theme={null} OneSignal.getUser().addEmail("example@email.com") OneSignal.getUser().removeEmail("example@email.com") ``` ```swift Swift theme={null} OneSignal.User.addEmail("example@email.com") OneSignal.User.removeEmail("example@email.com") ``` ```objc Objective-C theme={null} [OneSignal.User addEmail:@"example@email.com"]; [OneSignal.User removeEmail:@"example@email.com"]; ``` ```csharp C# theme={null} OneSignal.User.AddEmail("example@email.com"); OneSignal.User.RemoveEmail("example@email.com"); ``` ```javascript React Native theme={null} OneSignal.User.addEmail("example@email.com"); OneSignal.User.removeEmail("example@email.com"); ``` ```dart Flutter theme={null} OneSignal.User.addEmail("example@email.com"); OneSignal.User.removeEmail("example@email.com"); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.User.addEmail("example@email.com"); OneSignal.User.removeEmail("example@email.com"); // Cordova window.plugins.OneSignal.User.addEmail("example@email.com"); window.plugins.OneSignal.User.removeEmail("example@email.com"); ``` ### `addSms()`, `removeSms()` 向当前用户添加或移除短信订阅（电话号码）。需要 [E.164 格式](https://www.twilio.com/docs/glossary/what-e164)。在 `login()` 后调用 `addSms` 以设置正确的用户上下文。与[身份验证](./identity-verification)兼容。 ```kotlin Kotlin theme={null} OneSignal.User.addSms("+15558675309") OneSignal.User.removeSms("+15558675309") ``` ```java Java theme={null} OneSignal.getUser().addSms("+15558675309") OneSignal.getUser().removeSms("+15558675309") ``` ```swift Swift theme={null} OneSignal.User.addSms("+15558675309") OneSignal.User.removeSms("+15558675309") ``` ```objc Objective-C theme={null} [OneSignal.User addSms:@"+15558675309"]; [OneSignal.User removeSms:@"+15558675309"]; ``` ```csharp C# theme={null} OneSignal.User.AddSms("+15558675309"); OneSignal.User.RemoveSms("+15558675309"); ``` ```javascript React Native theme={null} OneSignal.User.addSms("+15558675309"); OneSignal.User.removeSms("+15558675309"); ``` ```dart Flutter theme={null} OneSignal.User.addSms("+15558675309"); OneSignal.User.removeSms("+15558675309"); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.User.addSms("+15558675309"); OneSignal.User.removeSms("+15558675309"); // Cordova window.plugins.OneSignal.User.addSms("+15558675309"); window.plugins.OneSignal.User.removeSms("+15558675309"); ``` *** ## 推送权限 ### `requestPermission(fallbackToSettings)` *push* 显示原生系统提示，要求用户授予推送通知权限。可选启用链接到设置应用的回退提示。 * `fallbackToSettings`：如果为 `true`，当用户拒绝推送权限超过操作系统限制（iOS 一次，Android 两次）时，将显示回退提示。 有关更多信息，请参阅[推送权限提示](./prompt-for-push-permissions)。 ```kotlin Kotlin theme={null} // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 OneSignal.Notifications.requestPermission(true) ``` ```java Java theme={null} // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 OneSignal.getNotifications().requestPermission(Continue.with(r -> { if (r.isSuccess()) { if (r.getData()) { // `requestPermission` completed successfully and the user has accepted permission } else { // `requestPermission` completed successfully but the user has rejected permission } } else { // `requestPermission` completed unsuccessfully, check `r.getThrowable()` for more info on the failure reason } })); ``` ```swift Swift theme={null} // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 OneSignal.Notifications.requestPermission({ accepted in print("User accepted notifications: \(accepted)") }, fallbackToSettings: true) ``` ```objc Objective-C theme={null} // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 [OneSignal.Notifications requestPermission:^(BOOL accepted) { NSLog(@"User accepted notifications: %d", accepted); } fallbackToSettings:true]; ``` ```csharp C# theme={null} // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 var result = await OneSignal.Notifications.RequestPermissionAsync(true); if (result) { // 通知权限已被接受。 } else { // 通知权限被拒绝。 } ``` ```javascript React Native theme={null} // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 OneSignal.Notifications.requestPermission(true); ``` ```dart Flutter theme={null} // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 OneSignal.Notifications.requestPermission(true); ``` ```javascript Cordova/Ionic theme={null} // Ionic // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 OneSignal.Notifications.requestPermission(true).then((accepted) => { console.log("User accepted notifications: " + accepted); }); // Cordova // 我们建议在测试后移除此方法，改用应用内消息提示通知权限。 // 传递 true 将在用户拒绝推送权限时退回到设置提示 window.plugins.OneSignal.Notifications.requestPermission(true).then((accepted) => { console.log("User accepted notifications: " + accepted); }); ``` ### `addPermissionObserver()` *push* 使用此方法跟踪推送权限变化，如： * 向用户显示通知权限提示。 * 用户接受或拒绝权限提示。 * 用户在设备的应用设置中启用或禁用您应用的通知，然后返回到您的应用。 当这种情况发生时，SDK 触发 `onOSPermissionChanged` 事件。您的监听器接收具有 `from` 和 `to` 值的状态对象，因此您可以准确检测发生了什么变化。 要停止监听更新，请调用相关的 `removePermissionObserver()` 方法。 ```kotlin Kotlin theme={null} class MyObserver : IPermissionObserver { init { OneSignal.Notifications.addPermissionObserver(this) } override fun onNotificationPermissionChange(granted: Boolean) { if (granted) { // 通知现在已启用 } } fun cleanup() { OneSignal.Notifications.removePermissionObserver(this) } } ``` ```java Java theme={null} public class MainActivity extends Activity implements IPermissionObserver { protected void onCreate(Bundle savedInstanceState) { OneSignal.getNotifications().addPermissionObserver(this); } @Override public void onNotificationPermissionChange(boolean granted) { if (granted) { // 通知现在已启用 } } @Override protected void onDestroy() { OneSignal.getNotifications().removePermissionObserver(this); super.onDestroy(); } } ``` ```swift Swift theme={null} class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationPermissionObserver { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { OneSignal.Notifications.addPermissionObserver(self) return true } func onNotificationPermissionDidChange(_ granted: Bool) { print("Notification permission changed: \(granted)") } func cleanup() { OneSignal.Notifications.removePermissionObserver(self) } } ``` ```objc Objective-C theme={null} // AppDelegate.h @interface AppDelegate : UIResponder @end // AppDelegate.m @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [OneSignal.Notifications addPermissionObserver:self]; return YES; } - (void)onNotificationPermissionDidChange:(BOOL)granted { NSLog(@"Permission changed: %d", granted); } - (void)cleanup { [OneSignal.Notifications removePermissionObserver:self]; } @end ``` ```csharp C# theme={null} OneSignal.Notifications.PermissionChanged += (sender, e) => { // 响应权限变化 }; ``` ```javascript React Native theme={null} const onPermissionChange = (granted) => { console.log('Permission changed:', granted); }; OneSignal.Notifications.addEventListener('permissionChange', onPermissionChange); // 如需要稍后移除 OneSignal.Notifications.removeEventListener('permissionChange', onPermissionChange); ``` ```dart Flutter theme={null} final observer = (bool hasPermission) { print("Notification permission: $hasPermission"); }; OneSignal.Notifications.addPermissionObserver(observer); // 如需要稍后移除 OneSignal.Notifications.removePermissionObserver(observer); ``` ```javascript Cordova/Ionic theme={null} const listener = (granted) => { console.log("Push permission changed:", granted); }; // Ionic OneSignal.Notifications.addEventListener("permissionChange", listener); // 如需要稍后移除 OneSignal.Notifications.removeEventListener("permissionChange", listener); // Cordova window.plugins.OneSignal.Notifications.addEventListener("permissionChange", listener); // 如需要稍后移除 window.plugins.OneSignal.Notifications.removeEventListener("permissionChange", listener); ``` ### `getPermission()`, `getCanRequestPermission()` `getPermission()` 返回应用级别的当前推送权限状态。如果您通过 `optOut()` 或用户和订阅 API 中的 `enabled` 参数更改了权限状态，它不会考虑 OneSignal 级别的订阅状态。我们建议使用[推送权限观察者](#addpermissionobserver-push)在应用运行时跟踪设备通知权限状态的变化，或使用[推送订阅观察者](#addobserver-push-subscription-changes)跟踪推送订阅状态的变化，而不是使用 `getPermission()`。 `getCanRequestPermission()` 返回尝试请求权限是否会导致向用户显示提示。如果为 `false`，用户已经拒绝了权限，可以显示回退提示或根本不显示提示。有关更多信息，请参阅[提示推送权限](./prompt-for-push-permissions)。 ```kotlin Kotlin theme={null} // 如果应用有权限显示通知，则为 true OneSignal.Notifications.permission // 如果设备可以显示系统通知权限提示，则为 true val canRequest: Boolean = OneSignal.Notifications.canRequestPermission ``` ```java Java theme={null} // 如果应用有权限显示通知，则为 true OneSignal.getNotifications().getPermission(); // 如果设备可以显示系统通知权限提示，则为 true OneSignal.getNotifications().getCanRequestPermission(); ``` ```swift Swift theme={null} // 如果应用有权限显示通知，则为 true OneSignal.Notifications.permission // 如果设备可以显示系统通知权限提示，则为 true OneSignal.Notifications.canRequestPermission ``` ```objc Objective-C theme={null} // 如果应用有权限显示通知，则为 true [OneSignal.Notifications permission]; // 如果设备可以显示系统通知权限提示，则为 true [OneSignal.Notifications canRequestPermission]; ``` ```csharp C# theme={null} // 如果应用有权限显示通知，则为 true bool permission = OneSignal.Notifications.Permission; // 如果设备可以显示系统通知权限提示，则为 true bool canRequest = OneSignal.Notifications.CanRequestPermission; ``` ```javascript React Native theme={null} // 如果应用有权限显示通知，则为 true await OneSignal.Notifications.getPermissionAsync(); // 如果设备可以显示系统通知权限提示，则为 true await OneSignal.Notifications.canRequestPermissionAsync(); ``` ```dart Flutter theme={null} // 如果应用有权限显示通知，则为 true var permission = OneSignal.Notifications.permission; // 如果设备可以显示系统通知权限提示，则为 true var canRequest = OneSignal.Notifications.canRequestPermission; ``` ```javascript Cordova/Ionic theme={null} // Ionic // 如果应用有权限显示通知，则为 true await OneSignal.Notifications.getPermissionAsync(); // 如果设备可以显示系统通知权限提示，则为 true await OneSignal.Notifications.canRequestPermissionAsync(); // Cordova // 如果应用有权限显示通知，则为 true await window.plugins.OneSignal.Notifications.getPermissionAsync(); // 如果设备可以显示系统通知权限提示，则为 true await window.plugins.OneSignal.Notifications.canRequestPermissionAsync(); ``` #### `permissionNative` *iOS* 返回 iOS 设备原生权限的枚举。它将是以下之一： * `0` = NotDetermined * `1` = Denied * `2` = Authorized * `3` = Provisional (only available in iOS 12+) * `4` = Ephemeral (only available in iOS 14+) ```swift Swift theme={null} let permissionNative: OSNotificationPermission = OneSignal.Notifications.permissionNative.rawValue ``` ```objectivec Objective-C theme={null} OSNotificationPermission permissionNative = [OneSignal.Notifications permissionNative] ``` ```csharp C# theme={null} NotificationPermission PermissionNative ``` ```javascript React Native theme={null} await OneSignal.Notifications.permissionNative() ``` ```dart Flutter theme={null} var permissionNative = await OneSignal.Notifications.permissionNative() ``` ```javascript Cordova/Ionic theme={null} // Ionic await OneSignal.Notifications.permissionNative() // Cordova await window.plugins.OneSignal.Notifications.permissionNative() ``` ## 推送通知事件 ### `addClickListener()` *push* 设置当用户点击打开应用的推送通知时运行的回调。 当此事件触发时，应用的活动或场景已经启动。使用此处理程序执行任何自定义逻辑——不要手动重新启动或重复应用导航。 对于 Flutter 应用，如果应用被强制关闭并且您点击通知，应用将不会打开，点击监听器在 `Debug` 模式下不会注册。要解决此问题，您可以： * 通过 Flutter 使用发布构建，例如 `flutter run --release`（需要物理设备） * 将 Xcode scheme 更新为 `Release` 而不是 `Debug` 当不再需要处理程序时，使用 `removeClickListener()` 或 `removeEventListener()` 停止监听。 ```kotlin Kotlin theme={null} val clickListener = object : INotificationClickListener { override fun onClick(event: INotificationClickEvent) { Log.d("OneSignal", "Notification clicked: ${event.notification.title}") } } OneSignal.Notifications.addClickListener(clickListener) ``` ```java Java theme={null} OneSignal.getNotifications().addClickListener(event -> { Log.v(Tag.LOG_TAG, "INotificationClickListener.onClick fired" + " with event: " + event); }); ``` ```swift Swift theme={null} class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationClickListener { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { OneSignal.Notifications.addClickListener(self) return true } func onClick(event: OSNotificationClickEvent) { print("Notification clicked: \(event.jsonRepresentation())") } } ``` ```objc Objective-C theme={null} // AppDelegate.h @interface AppDelegate : UIResponder @end // AppDelegate.m @implementation AppDelegate - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [OneSignal.Notifications addClickListener:self]; return YES; } - (void)onClickNotification:(OSNotificationClickEvent *)event { NSLog(@"Notification clicked: %@", [event jsonRepresentation]); } @end ``` ```csharp C# theme={null} OneSignal.Notifications.Clicked += (sender, e) => { var RawPayload = e.Notification.RawPayload; Console.WriteLine("Notification clicked: " + RawPayload); }; ``` ```javascript React Native theme={null} OneSignal.Notifications.addEventListener('click', (event) => { console.log('OneSignal: notification clicked:', event); }); ``` ```dart Flutter theme={null} OneSignal.Notifications.addClickListener((event) { print('Notification clicked: ${event}'); }); ``` ```javascript Cordova/Ionic theme={null} const myClickListener = (event) => { console.log("Notification clicked:", JSON.stringify(event)); }; // Ionic OneSignal.Notifications.addEventListener("click", myClickListener); // Cordova window.plugins.OneSignal.Notifications.addEventListener("click", myClickListener); ``` ### `addForegroundLifecycleListener()` *push* 允许您拦截和控制应用在前台时通知的行为。 默认情况下，OneSignal 自动显示通知。您可以使用 `event.preventDefault()` 覆盖此行为以： * 抑制通知 * 自定义它 * 为异步逻辑延迟显示（如获取用户状态、记录事件） 调用 `event.notification.display()` 稍后手动显示它。 这在[通知服务扩展](./service-extensions)**之后**运行，后者在显示前修改负载。 当不再需要处理程序时，使用 `removeForegroundLifecycleListener()` 或 `removeEventListener()` 停止监听。 ```kotlin Kotlin theme={null} val lifecycleListener = object : INotificationLifecycleListener { override fun onWillDisplay(event: INotificationWillDisplayEvent) { Log.d("OneSignal", "Foreground notification: ${event.notification.title}") // 取消注释以防止通知在前台时显示 // event.preventDefault() } } OneSignal.Notifications.addForegroundLifecycleListener(lifecycleListener) ``` ```java Java theme={null} OneSignal.getNotifications().addForegroundLifecycleListener(new INotificationLifecycleListener() { @Override public void onWillDisplay(@NonNull INotificationWillDisplayEvent event) { Log.d("OneSignal", "Foreground notification received: " + event.getNotification().getTitle()); // 取消注释以防止通知在前台时显示 // event.preventDefault(); } }); ``` ```swift Swift theme={null} class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationLifecycleListener { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { OneSignal.Notifications.addForegroundLifecycleListener(self) return true } func onWillDisplay(event: OSNotificationWillDisplayEvent) { print("Foreground notification: \(event.notification.title ?? "No Title")") // 取消注释以防止通知在前台时显示 // event.preventDefault() } } ``` ```objc Objective-C theme={null} @implementation AppDelegate - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [OneSignal.Notifications addForegroundLifecycleListener:self]; return YES; } - (void)onWillDisplayNotification:(OSNotificationWillDisplayEvent *)event { NSLog(@"Foreground notification: %@", event.notification.title); // 取消注释以防止通知在前台时显示 // [event preventDefault]; } @end ``` ```csharp C# theme={null} OneSignal.Notifications.ForegroundWillDisplay += (sender, e) => { Console.WriteLine("Foreground notification: " + e.Notification.RawPayload); // 取消注释以防止通知在前台时显示 // e.PreventDefault(); }; ``` ```javascript React Native theme={null} OneSignal.Notifications.addEventListener('foregroundWillDisplay', (event) => { console.log("Foreground notification:", event.getNotification().title); // 取消注释以防止通知在前台时显示 // event.preventDefault(); }); ``` ```dart Flutter theme={null} OneSignal.Notifications.addForegroundWillDisplayListener((event) { print("Foreground notification: ${event.notification.title}"); // 取消注释以防止通知在前台时显示 // event.preventDefault(); }); ``` ```javascript Cordova/Ionic theme={null} const myLifecyleListener = function(event) { console.log("Foreground notification:", event.notification.title); // 取消注释以防止通知在前台时显示 // event.preventDefault(); }; // Ionic OneSignal.Notifications.addEventListener("foregroundWillDisplay", myLifecyleListener); // Cordova window.plugins.OneSignal.Notifications.addEventListener("foregroundWillDisplay", myLifecyleListener); ``` ### `clearAllNotifications()` 从通知栏中移除所有 OneSignal 通知。使用此方法而不是 Android 的 `android.app.NotificationManager.cancel`。否则，当您的应用重启时，通知将被恢复。 ```kotlin Kotlin theme={null} OneSignal.Notifications.clearAllNotifications() ``` ```java Java theme={null} OneSignal.getNotifications.clearAllNotifications(); ``` ```swift Swift theme={null} OneSignal.Notifications.clearAll() ``` ```objc Objective-C theme={null} [OneSignal.Notifications clearAll]; ``` ```csharp C# theme={null} OneSignal.Notifications.ClearAllNotifications(); ``` ```javascript React Native theme={null} OneSignal.Notifications.clearAll(); ``` ```dart Flutter theme={null} OneSignal.Notifications.clearAll(); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.Notifications.clearAll(); // Cordova window.plugins.OneSignal.Notifications.clearAll(); ``` #### `removeNotification()` *Android* 基于其 Android 通知 ID 取消单个通知。 使用此方法而不是 Android 的 `android.app.NotificationManager.cancel`。否则，当您的应用重启时，通知将被恢复。 ```kotlin Kotlin theme={null} OneSignal.Notifications.removeNotification(id) ``` ```java Java theme={null} OneSignal.getNotifications().removeNotification(id); ``` ```csharp C# theme={null} OneSignal.Notifications.RemoveNotification(id); ``` ```javascript React Native theme={null} OneSignal.Notifications.removeNotification(id); ``` ```dart Flutter theme={null} OneSignal.Notifications.removeNotification(id); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.Notifications.removeNotification(id); // Cordova window.plugins.OneSignal.Notifications.removeNotification(id); ``` #### `removeGroupedNotifications()` *Android* 使用提供的组键取消一组 OneSignal 通知。分组通知是 OneSignal 概念。没有 `android.app.NotificationManager` 等价物。 ```kotlin Kotlin theme={null} OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY") ``` ```java Java theme={null} OneSignal.getNotifications().removeGroupedNotifications("GROUP_KEY"); ``` ```csharp C# theme={null} OneSignal.Notifications.RemoveGroupedNotifications("GROUP_KEY"); ``` ```javascript React Native theme={null} OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY"); ``` ```dart Flutter theme={null} OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY"); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY"); // Cordova window.plugins.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()` 基于单个或多个触发器决定何时显示应用内消息。有关更多信息，请参阅[触发器](./iam-triggers)。 触发器不会持久化到后端。它们只存在于本地设备上并适用于当前用户。 ```kotlin Kotlin theme={null} OneSignal.InAppMessages.addTrigger("KEY", "VALUE") OneSignal.InAppMessages.addTriggers(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02")) ``` ```java Java theme={null} OneSignal.getInAppMessages().addTrigger("KEY", "VALUE"); OneSignal.getInAppMessages().addTriggers(new HashMap() {{ put("KEY_01","VALUE_01"); put("KEY_02", "VALUE_02"); }}); ``` ```swift Swift theme={null} OneSignal.InAppMessages.addTrigger("KEY", withValue: "VALUE") OneSignal.InAppMessages.addTriggers(["KEY_01": "VALUE_01", "KEY_02": "VALUE_02"]) ``` ```objc Objective-C theme={null} [OneSignal.InAppMessages addTrigger:@"KEY" withValue:@"VALUE"]; [OneSignal.InAppMessages addTriggers:@{@"KEY_01": @"VALUE_01", @"KEY_02": @"VALUE_02"}]; ``` ```csharp C# theme={null} OneSignal.InAppMessages.AddTrigger("KEY", "VALUE"); OneSignal.InAppMessages.AddTriggers(new Dictionary { { "KEY_01", "VALUE_01" }, { "KEY_02", "VALUE_02" } }); ``` ```javascript React Native theme={null} OneSignal.InAppMessages.addTrigger("KEY", "VALUE"); OneSignal.InAppMessages.addTriggers({ "KEY_01": "VALUE_01", "KEY_02": "VALUE_02" }); ``` ```dart Flutter theme={null} OneSignal.InAppMessages.addTrigger("KEY", "VALUE"); OneSignal.InAppMessages.addTriggers({ "KEY_01": "VALUE_01", "KEY_02": "VALUE_02" }); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.InAppMessages.addTrigger("KEY", "VALUE"); OneSignal.InAppMessages.addTriggers({"KEY_01":"VALUE_01", "KEY_02":"VALUE_02"}); // Cordova window.plugins.OneSignal.InAppMessages.addTrigger("KEY", "VALUE"); window.plugins.OneSignal.InAppMessages.addTriggers({"KEY_01":"VALUE_01", "KEY_02":"VALUE_02"}); ``` ### `removeTrigger()`, `removeTriggers()`, `clearTriggers()` Remove a single, multiple, or all triggers with the provided key from the current user. ```kotlin Kotlin theme={null} OneSignal.InAppMessages.removeTrigger("KEY") OneSignal.InAppMessages.removeTriggers(setOf("KEY_01", "KEY_02")) OneSignal.InAppMessages.clearTriggers() ``` ```java Java theme={null} OneSignal.getInAppMessages().removeTrigger("KEY"); OneSignal.getInAppMessages().removeTriggers(Arrays.asList("KEY_01", "KEY_02")); OneSignal.getInAppMessages().clearTriggers(); ``` ```swift Swift theme={null} OneSignal.InAppMessages.removeTrigger("KEY") OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]) OneSignal.InAppMessages.clearTriggers() ``` ```objc Objective-C theme={null} [OneSignal.InAppMessages removeTrigger:@"KEY"]; [OneSignal.InAppMessages removeTriggers:@[@"KEY_01", @"KEY_02"]]; [OneSignal.InAppMessages clearTriggers]; ``` ```csharp C# theme={null} OneSignal.InAppMessages.RemoveTrigger("KEY"); OneSignal.InAppMessages.RemoveTriggers(new List { "KEY_01", "KEY_02" }); OneSignal.InAppMessages.ClearTriggers(); ``` ```javascript React Native theme={null} OneSignal.InAppMessages.removeTrigger("KEY"); OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]); OneSignal.InAppMessages.clearTriggers(); ``` ```dart Flutter theme={null} OneSignal.InAppMessages.removeTrigger("KEY"); OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]); OneSignal.InAppMessages.clearTriggers(); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.InAppMessages.removeTrigger("KEY"); OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]); OneSignal.InAppMessages.clearTriggers(); // Cordova window.plugins.OneSignal.InAppMessages.removeTrigger("KEY"); window.plugins.OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]); window.plugins.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. ```kotlin Kotlin theme={null} OneSignal.InAppMessages.paused = true ``` ```java Java theme={null} OneSignal.getInAppMessages().setPaused(true); ``` ```swift Swift theme={null} OneSignal.InAppMessages.paused = true // Get `paused` state let paused = OneSignal.InAppMessages.paused ``` ```objc Objective-C theme={null} [OneSignal.InAppMessages paused:true]; // Get `paused` state BOOL paused = [OneSignal.InAppMessages paused]; ``` ```csharp C# theme={null} OneSignal.InAppMessages.Paused = true; ``` ```javascript React Native theme={null} OneSignal.InAppMessages.setPaused(true); ``` ```dart Flutter theme={null} OneSignal.InAppMessages.paused(true); ``` ```javascript Cordova/Ionic theme={null} // Ionic OneSignal.InAppMessages.setPaused(true); // Cordova window.plugins.OneSignal.InAppMessages.setPaused(true); ``` ### `addLifecycleListener()` 响应或跟踪应用内消息的显示和解散。 ```kotlin Kotlin theme={null} 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) ``` ```java Java theme={null} OneSignal.getInAppMessages().addLifecycleListener(new IInAppMessageLifecycleListener() { @Override public void onWillDisplay(@NonNull IInAppMessageWillDisplayEvent event) { Log.v(Tag.LOG_TAG, "onWillDisplayInAppMessage"); } @Override public void onDidDisplay(@NonNull IInAppMessageDidDisplayEvent event) { Log.v(Tag.LOG_TAG, "onDidDisplayInAppMessage"); } @Override public void onWillDismiss(@NonNull IInAppMessageWillDismissEvent event) { Log.v(Tag.LOG_TAG, "onWillDismissInAppMessage"); } @Override public void onDidDismiss(@NonNull IInAppMessageDidDismissEvent event) { Log.v(Tag.LOG_TAG, "onDidDismissInAppMessage"); } }); ``` ```swift Swift theme={null} // AppDelegate.swift // 将 OSInAppMessageLifecycleListener 作为将处理应用内消息生命周期事件的类的实现协议添加。 class AppDelegate: UIResponder, UIApplicationDelegate, OSInAppMessageLifecycleListener { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { // 将您的实现类添加为监听器 OneSignal.InAppMessages.addLifecycleListener(self) } // 添加以下可选生命周期方法中的一个或多个 func onWillDisplay(event: OSInAppMessageWillDisplayEvent) { print("OSInAppMessageLifecycleListener: onWillDisplay Message: \(event.message.messageId)") } func onDidDisplay(event: OSInAppMessageDidDisplayEvent) { print("OSInAppMessageLifecycleListener: onDidDisplay Message: \(event.message.messageId)") } func onWillDismiss(event: OSInAppMessageWillDismissEvent) { print("OSInAppMessageLifecycleListener: onWillDismiss Message: \(event.message.messageId)") } func onDidDismiss(event: OSInAppMessageDidDisplayEvent) { print("OSInAppMessageLifecycleListener: onDidDismiss Message: \(event.message.messageId)") } } ``` ```objc Objective-C theme={null} // AppDelegate.h // 将 OSInAppMessageLifecycleListener 作为将处理应用内消息生命周期事件的类的实现协议添加。 @interface AppDelegate : UIResponder @end // AppDelegate.m @implementation AppDelegate - (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // 将您的实现类添加为监听器. [OneSignal.InAppMessages addLifecycleListener:self]; } // 添加以下一个或多个可选的生命周期方法 - (void)onWillDisplayInAppMessage:(OSInAppMessageWillDisplayEvent *)event { NSLog(@"OSInAppMessageLifecycleListener: onWillDisplay Message: %@", event.message.messageId); } - (void)onDidDisplayInAppMessage:(OSInAppMessageDidDisplayEvent *)event { NSLog(@"OSInAppMessageLifecycleListener: onDidDisplay Message: %@", event.message.messageId); } - (void)onWillDismissInAppMessage:(OSInAppMessageWillDismissEvent *)event { NSLog(@"OSInAppMessageLifecycleListener: onWillDismiss Message: %@", event.message.messageId); } - (void)onDidDismissInAppMessage:(OSInAppMessageDidDismissEvent *)event { NSLog(@"OSInAppMessageLifecycleListener: onDidDismiss Message: %@", event.message.messageId); } ``` ```csharp C# theme={null} OneSignal.InAppMessages.WillDisplay += (sender, e) => { // Access the in-app message with e.Message }; OneSignal.InAppMessages.DidDisplay += (sender, e) => { // Access the in-app message with e.Message }; OneSignal.InAppMessages.WillDismiss += (sender, e) => { // Access the in-app message with e.Message }; OneSignal.InAppMessages.DidDismiss += (sender, e) => { // Access the in-app message with e.Message }; ``` ```javascript React Native theme={null} OneSignal.InAppMessages.addEventListener('willDisplay', (event) => { console.log('OneSignal: will display IAM: ', event); }); OneSignal.InAppMessages.addEventListener('didDisplay', (event) => { console.log('OneSignal: did display IAM: ', event); }); OneSignal.InAppMessages.addEventListener('willDismiss', (event) => { console.log('OneSignal: will dismiss IAM: ', event); }); OneSignal.InAppMessages.addEventListener('didDismiss', (event) => { console.log('OneSignal: did dismiss IAM: ', event); }); ``` ```dart Flutter theme={null} OneSignal.InAppMessages.addWillDisplayListener((event) { print("ON WILL DISPLAY IN APP MESSAGE ${event.message.messageId}"); }); OneSignal.InAppMessages.addDidDisplayListener((event) { print("ON DID DISPLAY IN APP MESSAGE ${event.message.messageId}"); }); OneSignal.InAppMessages.addWillDismissListener((event) { print("ON WILL DISMISS IN APP MESSAGE ${event.message.messageId}"); }); OneSignal.InAppMessages.addDidDismissListener((event) { print("ON DID DISMISS IN APP MESSAGE ${event.message.messageId}"); }); ``` ```javascript Cordova/Ionic theme={null} // 定义生命周期监听器函数 let willDisplayListener = async function(event) { console.log("OneSignal: will display IAM: "+ event.messageId); }; let didDisplayListener = async function(event) { console.log("OneSignal: did display IAM: "+ event.messageId); }; let willDismissListener = async function(event) { console.log("OneSignal: will dismiss IAM: "+ event.messageId); }; let didDismissListener = async function(event) { console.log("OneSignal: did dismiss IAM: "+ event.messageId); }; // 为每个事件分别添加监听器 // Ionic OneSignal.InAppMessages.addEventListener("willDisplay", willDisplayListener); OneSignal.InAppMessages.addEventListener("didDisplay", didDisplayListener); OneSignal.InAppMessages.addEventListener("willDismiss", willDismissListener); OneSignal.InAppMessages.addEventListener("didDismiss", didDismissListener); // Cordova window.plugins.OneSignal.InAppMessages.addEventListener("willDisplay", willDisplayListener); window.plugins.OneSignal.InAppMessages.addEventListener("didDisplay", didDisplayListener); window.plugins.OneSignal.InAppMessages.addEventListener("willDismiss", willDismissListener); window.plugins.OneSignal.InAppMessages.addEventListener("didDismiss", didDismissListener); ``` ### `addClickListener()` *in-app* 响应应用内消息点击事件。事件包含以下[点击操作](./iam-click-actions)元数据： * `actionId`：您在元素上设置的自定义标识符。 * `urlTarget`：指定消息启动 URL 如何呈现的枚举。 * `url`：操作的启动 URL（如果有的话）。 * `closingMessage`：指示操作是否导致消息被关闭的布尔值。 ```kotlin Kotlin theme={null} val clickListener = object : IInAppMessageClickListener { override fun onClick(event: IInAppMessageClickEvent) { print(event.result.actionId) } } OneSignal.InAppMessages.addClickListener(clickListener) ``` ```java Java theme={null} OneSignal.getInAppMessages().addClickListener(new IInAppMessageClickListener() { @Override public void onClick(@Nullable IInAppMessageClickEvent event) { Log.v(Tag.LOG_TAG, "INotificationClickListener.inAppMessageClicked"); } }); ``` ```swift Swift theme={null} class MyInAppMessageClickListener : NSObject, OSInAppMessageClickListener { func onClick(event: OSInAppMessageClickEvent) { let messageId = event.message.messageId print("Message ID: \(messageId)") let result: OSInAppMessageClickResult = event.result let actionId = result.actionId print("Action ID: ",(actionId ?? "no actionId")) let url = result.url print("URL: ", (url ?? "No URL")) let urlTarget: OSInAppMessageActionUrlType = result.urlTarget print("URL Target: \(urlTarget)") let closingMessage = result.closingMessage print("Closing Message: \(closingMessage)") } } // 将您的对象添加为监听器 let myListener = MyInAppMessageClickListener() OneSignal.InAppMessages.addClickListener(myListener) ``` ```objc Objective-C theme={null} // 将此方法添加到实现 OSInAppMessageClickListener 协议的对象 - (void)onClickInAppMessage:(OSInAppMessageClickEvent * _Nonnull)event { NSLog(@"onClickInAppMessage event: %@", [event jsonRepresentation]); NSString *message = [NSString stringWithFormat:@"In App Message Click Occurred: messageId: %@ actionId: %@ url: %@ urlTarget: %@ closingMessage: %i", event.message.messageId, event.result.actionId, event.result.url, @(event.result.urlTarget), event.result.closingMessage]; } // 将您的对象添加为监听器 [OneSignal.InAppMessages addClickListener:self]; ``` ```csharp C# theme={null} OneSignal.InAppMessages.Clicked += (sender, e) => { // 使用 e.Message 访问应用内消息，使用 e.Result 访问点击结果 }; ``` ```javascript React Native theme={null} OneSignal.InAppMessages.addEventListener('click', (event) => { console.log('OneSignal IAM clicked:', event); }); ``` ```dart Flutter theme={null} OneSignal.InAppMessages.addClickListener((event) { print("In App Message Clicked: \n${event.result.jsonRepresentation().replaceAll("\\n", "\n")}"); }); ``` ```javascript Cordova/Ionic theme={null} let inAppClickListener = async function(event) { let clickData = JSON.stringify(event); console.log("In-App Message Clicked: "+ clickData); }; // Ionic OneSignal.InAppMessages.addEventListener("click", inAppClickListener); // Cordova window.plugins.OneSignal.InAppMessages.addEventListener("click", inAppClickListener); ``` *** ## Live Activity 应用程序应允许用户选择加入 Live Activities。例如，您的应用为用户提供使用按钮或呈现 IAM 在您的应用内启动 Live Activity 的选项。与通知权限或位置权限不同，您可以通过任何方法启动和更新 Live Activity 而无需明确提示。Live Activities 与 iOS 临时授权 UI 一起出现。Live Activities 必须在您的应用程序处于前台时启动。我们建议阅读 [Apple 的开发者指南](https://developer.apple.com/design/human-interface-guidelines/live-activities)以了解更多关于 Live Activities 的信息。 ### `setup()` 允许 OneSignal 代表应用程序管理 LiveActivity 的生命周期。这包括监听 pushToStart 令牌更新和 pushToUpdate 令牌更新。 ```swift Swift theme={null} //... your app's code OneSignal.LiveActivities.setup(MyWidgetAttributes.self); ``` ### `setupDefault()` 允许跨平台 SDK 通过消除客户应用程序定义和管理自己的 ActivityAttributes 的需要来管理 LiveActivity 的生命周期。有关更多详情，请参阅[跨平台设置](./cross-platform-live-activity-setup)。 ```csharp C# theme={null} using OneSignalSDK; //Push To Start OneSignal.LiveActivities.SetupDefault(); //从应用内启动 Live Activity（推送启动不需要） string activityId = "my_activity_id"; OneSignal.LiveActivities.StartDefault( activityId, new Dictionary() { { "title", "Welcome!" } }, new Dictionary() { { "message", new Dictionary() { { "en", "Hello World!"} }}, }); ``` ```javascript React Native theme={null} import { OneSignal } from 'react-native-onesignal' //Push To Start OneSignal.LiveActivities.setupDefault() //从应用内启动 Live Activity（推送启动不需要） const activityId = "my_activity_id" const attributes = { title: "Sample Title" } ; const content = { message: { en: "message" } }; OneSignal.LiveActivities.startDefault(activityId, attributes, content); ``` ```dart Flutter theme={null} import 'package:onesignal_flutter/onesignal_flutter.dart'; OneSignal.LiveActivities.setupDefault() //从应用内启动 Live Activity（推送启动不需要） const String activityId = "my_activity_id"; OneSignal.LiveActivities.startDefault(activityId!, { "title": "Welcome!" }, { "message": {"en": "Hello World!"}, }); ``` ```javascript Cordova/Ionic theme={null} //Ionic import OneSignal from "onesignal-cordova-plugin"; //Push To Start OneSignal.LiveActivities.setupDefault(); //从应用内启动 Live Activity（推送启动不需要） const activityId = "my_activity_id"; const attributes = { title: "Sample Title" }; const content = { message: { en: "message" } }; OneSignal.LiveActivities.startDefault(activityId, attributes, content); //Cordova //Push To Start window.plugins.OneSignal.LiveActivities.setupDefault(); //从应用内启动 Live Activity（推送启动不需要） const activityId = "my_activity_id"; const attributes = { title: "Sample Title" }; const content = { message: { en: "message" } }; window.plugins.OneSignal.LiveActivities.startDefault( activityId, attributes, content ); ``` ### `enter()` 进入 Live Activity 将 `activityId` 与我们服务器上的 Live Activity **临时推送令牌**关联。在使用[更新 Live Activities](/reference/update-live-activity-api) REST API 同时更新一个或多个 Live Activities 时指定此标识符。 ```swift Swift theme={null} // ... your app's code let activity = try Activity.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) } } ``` ```csharp C# theme={null} OneSignal.LiveActivities.EnterAsync("ACTIVITY_ID", token); ``` ```csharp .Net theme={null} var result = OneSignalSDK.DotNet.OneSignal.Default.EnterLiveActivity("ACTIVITY_ID", token); if(result) { Console.WriteLine("Success"); } ``` ```javascript React Native theme={null} OneSignal.LiveActivities.enter('ACTIVITY_ID', token, (result) => { console.log('进入 live activity 的结果: ', result); }); ``` ```dart Flutter theme={null} OneSignal.LiveActivities.enterLiveActivity("ACTIVITY_ID", token).then((result) { print("成功进入 live activity"); }).catchError((error) { print("进入 live activity 失败，错误：$error"); }); ``` ```javascript Cordova/Ionic theme={null} //Ionic OneSignal.LiveActivities.enter("ACTIVITY_ID", token, (result) => { console.log("进入 live activity 的结果: ", result); }); //Cordova window.plugins.OneSignal.LiveActivities.enter("ACTIVITY_ID", token, (result) => { console.log("进入 live activity 的结果: ", result); }); ``` ### `exit()` 退出 Live activity 删除活动标识符与我们服务器上的 Live Activity 推送令牌之间的关联。 ```swift Swift theme={null} OneSignal.LiveActivities.exit("ACTIVITY_ID") ``` ```csharp C# theme={null} OneSignal.LiveActivities.ExitAsync("ACTIVITY_ID"); ``` ```csharp .Net theme={null} OneSignalSDK.DotNet.OneSignal.Default.ExitLiveActivity("ACTIVITY_ID"); ``` ```javascript React Native theme={null} OneSignal.LiveActivities.exit('ACTIVITY_ID', (result) => { console.log('退出 live activity 的结果: ', result); }); ``` ```dart Flutter theme={null} OneSignal.LiveActivities.exit("ACTIVITY_ID").then((result) { print("成功退出 live activity"); }).catchError((error) { print("退出 live activity 失败：$error"); }); ``` ```javascript Cordova/Ionic theme={null} window.plugins.OneSignal.LiveActivities.exit("ACTIVITY_ID", (result) => { console.log("退出 live activity 的结果: ", result); }); ``` ### `setPushToStartToken()` 推送启动 live activities 的可选"低级"方法。在不更改 `ActivityAttribute` 结构的情况下，对 LiveActivity 启动和更新令牌提供细粒度控制。[此处提供更多详情](https://github.com/OneSignal/OneSignal-iOS-SDK/pull/1377#:~:text=Alternative%20\(low%20level\)%20method%20to%20setup%20Live%20Activities%20with%20OneSignal) ```swift Swift theme={null} if #available(iOS 17.2, *) { // 设置异步任务以监控并向 OneSignalSDK 发送 pushToStartToken 更新。 Task { for try await data in Activity.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.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 ```swift Swift theme={null} OneSignal.LiveActivities.removePushToStartToken(MyWidgetAttributes.self) ``` *** ## 结果 跟踪用户采取的操作并将其归因于消息。有关更多详情，请参阅[结果](./custom-outcomes)。 ### `addOutcome()` 添加具有提供名称的结果，针对当前会话捕获。 ```kotlin Kotlin theme={null} OneSignal.Session.addOutcome("OUTCOME_NAME") ``` ```java Java theme={null} OneSignal.getSession().addOutcome("OUTCOME_NAME"); ``` ```swift Swift theme={null} OneSignal.Session.addOutcome("OUTCOME_NAME") ``` ```objc Objective-C theme={null} [OneSignal.Session addOutcome:@"OUTCOME_NAME"]; ``` ```csharp C# theme={null} OneSignal.Session.AddOutcome("OUTCOME_NAME"); ``` ```javascript React Native theme={null} OneSignal.Session.addOutcome("OUTCOME_NAME"); ``` ```dart Flutter theme={null} OneSignal.Session.addOutcome("OUTCOME_NAME"); ``` ```javascript Cordova/Ionic theme={null} //Ionic OneSignal.Session.addOutcome("OUTCOME_NAME"); //Cordova window.plugins.OneSignal.Session.addOutcome("OUTCOME_NAME"); ``` ### `addUniqueOutcome()` 添加具有提供名称的唯一结果，针对当前会话捕获。 ```kotlin Kotlin theme={null} OneSignal.Session.addUniqueOutcome("OUTCOME_NAME") ``` ```java Java theme={null} OneSignal.getSession().addUniqueOutcome("OUTCOME_NAME"); ``` ```swift Swift theme={null} OneSignal.Session.addUniqueOutcome("OUTCOME_NAME") ``` ```objc Objective-C theme={null} [OneSignal.Session addUniqueOutcome:@"OUTCOME_NAME"]; ``` ```csharp C# theme={null} OneSignal.Session.AddUniqueOutcome("OUTCOME_NAME"); ``` ```javascript React Native theme={null} OneSignal.Session.addUniqueOutcome("OUTCOME_NAME"); ``` ```dart Flutter theme={null} OneSignal.Session.addUniqueOutcome("OUTCOME_NAME"); ``` ```javascript Cordova/Ionic theme={null} //Ionic OneSignal.Session.addUniqueOutcome("OUTCOME_NAME"); //Cordova window.plugins.OneSignal.Session.addUniqueOutcome("OUTCOME_NAME"); ``` ### `addOutcomeWithValue()` 添加具有提供名称和值的结果，针对当前会话捕获。 ```kotlin Kotlin theme={null} OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14) ``` ```java Java theme={null} OneSignal.getSession().addOutcomeWithValue("OUTCOME_NAME", 3.14); ``` ```swift Swift theme={null} OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14) ``` ```objc Objective-C theme={null} [OneSignal.Session addOutcomeWithValue:@"OUTCOME_NAME" value: 3.14]; ``` ```csharp C# theme={null} OneSignal.Session.AddOutcomeWithValue("OUTCOME_NAME", 3.14); ``` ```javascript React Native theme={null} OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14); ``` ```dart Flutter theme={null} OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14); ``` ```javascript Cordova/Ionic theme={null} //Ionic OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14); //Cordova window.plugins.OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14); ``` ***