> For the complete documentation index, see [llms.txt](https://dtsupport.gitbook.io/xg-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dtsupport.gitbook.io/xg-docs/ios_access/ios_api.md). # 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).