1. SDK API说明
1.1. 启动信鸽推送服务
说明
- 通过使用在信鸽官网注册的应用的信息,启动信鸽推送服务
接口
- (void)startXGWithAppID:(uint32_t)appID appKey:(nonnull NSString *)appKey delegate:(nullable id<XGPushDelegate>)delegate ;
参数说明
- appID:通过前台申请的应用 ID, 即 Access ID
- appKey: 通过前台申请的 appKey,即 Access Key
- delegate:回调对象
注意:接口所需参数必须要正确填写,反之信鸽服务将不能正确为应用推送消息
示例
[[XGPush defaultManager] startXGWithAppID: <#your access ID#>appKey:<#your access key#> delegate:<#your delegate#>];
1.2. 终止信鸽推送服务
说明
- 终止信鸽推送服务以后,将无法通过信鸽推送服务向设备推送消息,如果再次需要接收信鸽服务的消息推送,则必须需要再次调用
startXGWithAppID:appKey:delegate:
方法重启信鸽推送服务
接口
- (void)stopXGNotification;
示例
[[XGPush defaultManager] stopXGNotification];
1.3. 自定义通知栏消息行为
1.3.1. 创建消息支持的行为
说明
在通知消息中创建一个可以点击的事件行为
接口
+ (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的版本,此方法返回空
1.3.2. 创建分类对象
说明
创建分类对象,用以管理通知栏的Action对象
接口
+ (nullable id)categoryWithIdentifier:(nonnull NSString *)identifier actions:(nullable NSArray<XGNotificationAction *> *)actions intentIdentifiers:(nullable NSArray<NSString *> *)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];
1.3.3. 创建配置类
管理推送消息通知栏的样式和特性
接口
+ (nullable instancetype)configureNotificationWithCategories:(nullable NSSet<XGNotificationCategory *> *)categories types:(XGUserNotificationTypes)types;
参数说明
- categories:通知栏中支持的分类集合
- types:注册通知的样式
示例
XGNotificationConfigure *configure = [XGNotificationConfigure configureNotificationWithCategories:[NSSet setWithObject:category] types:XGUserNotificationTypeAlert|XGUserNotificationTypeBadge|XGUserNotificationTypeSound];
1.4. 上报地理位置
说明
- 上报地理位置信息,后续可以使用信鸽针对位置进行精准推送
接口
- (void)reportLocationWithLatitude:(double)latitude longitude:(double)longitude;
参数说明
- latitude:纬度
- longitude:经度
示例
[[XGPush defaultManager] reportLocationWithLatitude:20.0 longitude:19.0];
1.5. 上报应用角标
说明
- 上报当前 App 角标数到信鸽服务器
接口
- (void)setBadge:(NSInteger)badgeNumber;
参数说明
- badgeNumber 应用的角标数
注意:(后台维护中) 此接口是为了实现角标+1的功能,服务器会在这个数值基础上进行角标数新增的操作,调用成功之后,会覆盖之前值
示例
[[XGPush defaultManager] setXgApplicationBadgeNumber:0];
1.6. 管理应用角标
说明
- 管理 App 显示的角标数量
接口
@property (nonatomic) NSInteger xgApplicationBadgeNumber;
示例
// 设置应用角标
[[XGPush defaultManager] setXgApplicationBadgeNumber:0];
// 获取应用角标
NSInteger number = [[XGPush defaultManager] xgApplicationBadgeNumber];
1.7. 统计推送效果
说明
- 为了更好的了解每一条推送消息的运营效果,需要将用户对消息的行为上报
需要调用上报数据的接口 接口
- (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]
reportXGNotificationInfo:response.notification.request.content.userInfo];
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);
}
1.8. 管理设备 Token
1.8.1. 查询设备 Token
说明
- 查询当前应用从 APNs 获取的 Token 字符串
接口
@property (copy, nonatomic, nullable, readonly) NSString *deviceTokenString;
示例
NSString *token = [[XGPushTokenManager defaultTokenManager] deviceTokenString];
1.8.2. 查询 APNs 注册结果
说明
- 如果注册成功,则应用会调用
UIApplicationDelegate
代理对象的回调方法(如下),
接口
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken;
1.8.3. 查询信鸽注册结果
说明
- SDK 的启动方法自动注册设备从 APNs 获取的 Token 到信鸽服务器,注册结果会在
XGPushDelegate
(以下)的回调方法返回
接口
- (void)xgPushDidRegisteredDeviceToken:(NSString *)deviceToken error:(NSError *)error;
注意:此回调方法在注册成功之后调用,当前的 Token 已经注册过之后,SDK 将缓存注册信息,此方法将不会再调用
1.8.4. 绑定/解绑 标签和账号
说明
- 开发者可以针对不同的用户绑定标签,然后对该标签推送.对标签推送会让该标签下的所有设备都收到推送.一个设备可以绑定多个标签.
接口
- (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];
1.8.5. 查询绑定的标签和账号
说明
- 根据指定类型查询当前 Token 对象绑定的标识
接口
- (nullable NSArray<NSString *> *)identifiersWithType:(XGPushTokenBindType)type;
示例
// 查询标签
[[XGPushTokenManager defaultTokenManager] identifiersWithType:XGPushTokenBindTypeTag];
// 查询账号
[[XGPushTokenManager defaultTokenManager] identifiersWithType:XGPushTokenBindTypeAccount];
1.9. 查询设备通知权限
说明
- 查询设备通知权限是否被用户允许
接口
- (void)deviceNotificationIsAllowed:(nonnull void (^)(BOOL isAllowed))handler;
参数说明
- handler:查询结果的返回方法
示例
[[XGPush defaultManager] deviceNotificationIsAllowed:^(BOOL isAllowed) {
<#code#>
}];
1.10. 查询 SDK 版本
说明
- 查询当前 SDK 的版本
接口
- (nonnull NSString *)sdkVersion;
示例
[[XGPush defaultManager] sdkVersion];
1.11. 本地推送
本地推送相关功能请参考苹果开发者文档.