# iOS SDK API 接口文档 ## 启动信鸽推送服务 **说明** * 通过使用在信鸽官网注册的应用的信息，启动信鸽推送服务 **接口** ``` - (void)startXGWithAppID:(uint32_t)appID appKey:(nonnull NSString *)appKey delegate:(nullable id)delegate ; ``` **参数说明** * appID：通过前台申请的应用 ID, 即 Access ID * appKey： 通过前台申请的 appKey，即 Access Key * delegate：回调对象 ***注意：接口所需参数必须要正确填写，反之信鸽服务将不能正确为应用推送消息*** **示例** ``` [[XGPush defaultManager] startXGWithAppID: <#your access ID#>appKey:<#your access key#> delegate:<#your delegate#>]; ``` ## 终止信鸽推送服务 **说明** * 终止信鸽推送服务以后，将无法通过信鸽推送服务向设备推送消息，如果再次需要接收信鸽服务的消息推送，则必须需要再次调用 `startXGWithAppID:appKey:delegate:` 方法重启信鸽推送服务 **接口** ``` - (void)stopXGNotification; ``` **示例** ``` [[XGPush defaultManager] stopXGNotification]; ``` ## 自定义通知栏消息行为 ### 创建消息支持的行为 **说明** 在通知消息中创建一个可以点击的事件行为 **接口** ``` + (nullable id)actionWithIdentifier:(nonnull NSString *)identifier title:(nonnull NSString *)title options:(XGNotificationActionOptions)options; ``` **参数说明** * identifier：行为唯一标识 * title：行为名称 * options：行为支持的选项 **示例** ``` XGNotificationAction *action1 = [XGNotificationAction actionWithIdentifier:@"xgaction001" title:@"xgAction1" options:XGNotificationActionOptionNone]; ``` ***注意：通知栏带有点击事件的特性，只有在 iOS8.0 + 以上支持，iOS 7.x or earlier的版本，此方法返回空*** ### 创建分类对象 **说明** 创建分类对象，用以管理通知栏的Action对象 **接口** ``` + (nullable id)categoryWithIdentifier:(nonnull NSString *)identifier actions:(nullable NSArray *)actions intentIdentifiers:(nullable NSArray *)intentIdentifiers options:(XGNotificationCategoryOptions)options; ``` **参数说明** * identifier：分类对象的标识 * actions：当前分类拥有的行为对象组 * intentIdentifiers：用以表明可以通过Siri识别的标识 * options：分类的特性 ***注意：通知栏带有点击事件的特性，只有在iOS8+以上支持，iOS 8 or earlier的版本，此方法返回空*** **示例** ``` XGNotificationCategory *category = [XGNotificationCategory categoryWithIdentifier:@"xgCategory" actions:@[action1, action2] intentIdentifiers:@[] options:XGNotificationCategoryOptionNone]; ``` ### 创建配置类 管理推送消息通知栏的样式和特性 **接口** ``` + (nullable instancetype)configureNotificationWithCategories:(nullable NSSet *)categories types:(XGUserNotificationTypes)types; ``` **参数说明** * categories：通知栏中支持的分类集合 * types：注册通知的样式 **示例** ``` XGNotificationConfigure *configure = [XGNotificationConfigure configureNotificationWithCategories:[NSSet setWithObject:category] types:XGUserNotificationTypeAlert|XGUserNotificationTypeBadge|XGUserNotificationTypeSound]; ``` ## 上报地理位置 **说明** * 上报地理位置信息，后续可以使用信鸽针对位置进行精准推送 **接口** ``` - (void)reportLocationWithLatitude:(double)latitude longitude:(double)longitude; ``` **参数说明** * latitude：纬度 * longitude：经度 **示例** ``` [[XGPush defaultManager] reportLocationWithLatitude:20.0 longitude:19.0]; ``` ## 角标自动加1 **说明** * 调用此接口上报当前 App 角标数到信鸽服务器,客户端配置完成即可使用「iOS角标自动加1」的功能，此功能在管理台位置（创建推送→通知栏消息→常用设置→角标数字） **接口** ``` - (void)setBadge:(NSInteger)badgeNumber; ``` **参数说明** * badgeNumber 应用的角标数 **注意：**\ **1.此接口必须本地调用，否则管理台使用「iOS角标自动加1」功能时，角标会默认不变**\ **2.此接口仅适用于「SDK版本3.1.0及以上」，低于此版本管理台使用「iOS角标自动加1」功能，角标会默认不变** **示例** ``` [[XGPush defaultManager] setBadge:7]; ``` ## 管理应用角标 **说明** * 管理 App 显示的角标数量 **接口** ``` @property (nonatomic) NSInteger xgApplicationBadgeNumber; ``` **示例** ``` // 设置应用角标 [[XGPush defaultManager] setXgApplicationBadgeNumber:0]; // 获取应用角标 NSInteger number = [[XGPush defaultManager] xgApplicationBadgeNumber]; ``` ## 统计推送效果 **说明** * 为了更好的了解每一条推送消息的运营效果，需要将用户对消息的行为上报 需要调用上报数据的接口\ **接口** ``` - (void)reportXGNotificationInfo:(nonnull NSDictionary *)info; ``` **示例** ``` - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [[XGPush defaultManager] reportXGNotificationInfo:launchOptions]; return YES; } ``` * **iOS 9.x** 及以前，需要在 `UIApplicationDelegate` 的回调方法(如下)中调用上报数据的接口 ``` - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { } ``` **示例** ``` - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { [[XGPush defaultManager] reportXGNotificationInfo:userInfo]; completionHandler(UIBackgroundFetchResultNewData); } ``` * **iOS 10.0 +** ，需要在 `XGPushDelegate` 的回调方法(如下)中调用上报数据的接口 **示例** ``` - (void)xgPushUserNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)())completionHandler { [[XGPush defaultManager] reportXGNotificationResponse:response]; completionHandler(); } ``` 如果需要实现应用在前台时，也可以展示推送消息，需要实现以下方法，并在其中调用上报接口 **接口** ``` - (void)xgPushUserNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler; ``` **示例** ``` - (void)xgPushUserNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler { [[XGPush defaultManager] reportXGNotificationInfo:notification.request.content.userInfo]; completionHandler(UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionAlert); } ``` ## 管理设备 Token ### 查询设备 Token **说明** * 查询当前应用从 APNs 获取的 Token 字符串 **接口** ``` @property (copy, nonatomic, nullable, readonly) NSString *deviceTokenString; ``` **示例** ``` NSString *token = [[XGPushTokenManager defaultTokenManager] deviceTokenString]; ``` ### 查询 APNs 注册结果 **说明** * 如果注册成功，则应用会调用 `UIApplicationDelegate` 代理对象的回调方法(如下)， **接口** ``` - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken; ``` ### 查询信鸽注册结果 **说明** * SDK 的启动方法自动注册设备从 APNs 获取的 Token 到信鸽服务器，注册结果会在 `XGPushDelegate` (以下)的回调方法返回 **接口** ``` - (void)xgPushDidRegisteredDeviceToken:(NSString *)deviceToken error:(NSError *)error; ``` ***注意：此回调方法在注册成功之后调用，当前的 Token 已经注册过之后，SDK 将缓存注册信息，此方法将不会再调用*** ### 绑定/解绑 标签和账号 **说明** * 开发者可以针对不同的用户绑定标签,然后对该标签推送.对标签推送会让该标签下的所有设备都收到推送.一个设备可以绑定多个标签. **单操作接口** ``` - (void)bindWithIdentifier:(nullable NSString *)identifier type:(XGPushTokenBindType)type; - (void)unbindWithIdentifer:(nullable NSString *)identifier type:(XGPushTokenBindType)type; ``` **参数说明** * identifier:标签或账号 * type:绑定类型 **示例** ``` //绑定标签： [[XGPushTokenManager defaultTokenManager] bindWithIdentifier:@"your tag" type:XGPushTokenBindTypeTag]; //解绑标签 [[XGPushTokenManager defaultTokenManager] unbindWithIdentifer:@"your tag" type:XGPushTokenBindTypeTag]; //绑定账号： [[XGPushTokenManager defaultTokenManager] bindWithIdentifier:@"your account" type:XGPushTokenBindTypeAccount]; //解绑账号： [[XGPushTokenManager defaultTokenManager] unbindWithIdentifer:@"your account" type:XGPushTokenBindTypeAccount]; ``` **批量操作接口** ``` - (void)bindWithIdentifiers:(nonnull NSArray *)identifiers type:(XGPushTokenBindType)type - (void)unbindWithIdentifers:(nonnull NSArray *)identifiers type:(XGPushTokenBindType)type; ``` **参数说明** * identifiers:标签或账号列表 * type:绑定类型 **注意** * XG SDK 3.2.0+ * 暂不支持账号类型，标签字符串不允许有空格或者是tab字符 ### 批量更新标签/账号 **接口** ``` - (void)updateBindedIdentifiers:(nonnull NSArray *)identifiers bindType:(XGPushTokenBindType)type; ``` **参数说明** * identifiers:标签标识字符串数组，标签字符串不允许有空格或者是tab字符 * type:标识类型 **注意** * XG SDK 3.2.0+ * 若指定为标签类型，此接口会将当前 Token 对应的旧有的标签全部替换为当前的标签；若指定账号类型，此接口仅取 identifiers 列表中第一个 ### 清除全部标签/账号 **接口** ``` - (void)clearAllIdentifiers:(XGPushTokenBindType)type; ``` **参数说明** * type:标识类型 **注意** * XG SDK 3.2.0+ ### 查询绑定的标签和账号 **说明** * 根据指定类型查询当前 Token 对象绑定的标识 **接口** ``` - (nullable NSArray *)identifiersWithType:(XGPushTokenBindType)type; ``` **示例** ``` // 查询标签 [[XGPushTokenManager defaultTokenManager] identifiersWithType:XGPushTokenBindTypeTag]; // 查询账号 [[XGPushTokenManager defaultTokenManager] identifiersWithType:XGPushTokenBindTypeAccount]; ``` ## 查询设备通知权限 **说明** * 查询设备通知权限是否被用户允许 **接口** ``` - (void)deviceNotificationIsAllowed:(nonnull void (^)(BOOL isAllowed))handler; ``` **参数说明** * handler：查询结果的返回方法 **示例** ``` [[XGPush defaultManager] deviceNotificationIsAllowed:^(BOOL isAllowed) { <#code#> }]; ``` ## 查询 SDK 版本 **说明** * 查询当前 SDK 的版本 **接口** ``` - (nonnull NSString *)sdkVersion; ``` **示例** ``` [[XGPush defaultManager] sdkVersion]; ``` ## 本地推送 本地推送相关功能请参考[苹果开发者文档](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/SchedulingandHandlingLocalNotifications.html#//apple_ref/doc/uid/TP40008194-CH5-SW1). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://dtsupport.gitbook.io/xg-docs/ios_access/ios_api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.