1. 信鸽 iOS SDK 开发指南

1.1. 简介


信鸽iOS SDK是一个能够提供Push服务的开发平台,提供给开发者简便、易用的API接口,方便快速接入。

1.2. 接入方法


(1)获取 AppId 和 AppKey

(2)工程配置

1.2.1. 获取 AppId 和 AppKey

前往http://xg.qq.com注册并获取AppKey

1.2.2. 工程配置

(1)下载信鸽 SDK, 解压缩。注:使用CocoaPods的用户可以通过如下名称管理信鸽:

pod 'QQ_XGPush'

(2)将 XGSetting.h、XGPush.h、libXG-SDK.a 添加到工程 注意: 3.0+以上版本中没有XGSetting.h文件

(3)添加以下库/framework 的引用 CoreTelephony.framework, SystemConfiguration.framework, UserNotifications.framework, libXG-SDK.a 以及 libz.tbd.添加完成以后,库的引用如下

library

(4)在工程配置和后台模式中打开推送,如下图

projcfg

(5)参考 Demo, 添加相关代码

1.3. API 接口

1.3.1. 开启 Debug

打开 Debug 模式以后可以在终端看到详细的信鸽 Debug 信息.方便定位问题

示例

//打开debug开关
XGSetting *setting = [XGSetting getInstance];
[setting enableDebug:YES];
//查看debug开关是否打开
BOOL debugEnabled = [setting isEnableDebug];

1.3.2. 初始化信鸽

在使用信鸽之前,需要先在UIApplicationDelegate中的

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;

回调中调用信鸽的初始化方法才能正常使用信鸽

(1)接口

/**
初始化信鸽

@param appId 通过前台申请的应用ID
@param appKey 通过前台申请的appKey
*/
+(void)startApp:(uint32_t)appId appKey:(nonnull NSString *)appKey;

(2)示例

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[XGPush startApp:1234567890 appKey:@"ABCDEFGHIJKLMN"];
}

1.3.3. 注册苹果推送服务

使用推送前,需要先向苹果注册推送服务. 请参考 Demo 向苹果注册推送服务.

示例

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// 详细代码参考 Demo 中 registerAPNS 的实现
[self registerAPNS];
}

注: 在 iOS 10 中也可以可以使用 iOS 10 之前的注册方法来注册推送,但是对应的,也要使用 iOS 10 之前的方法来接收推送

1.3.4. 注册信鸽

向苹果注册完成推送服务以后,还需要向信鸽注册推送.在UIApplicationDelegate的

- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken;

回调中调用信鸽的 registerDevice 方法即可完成信鸽注册

(1)接口

/**
注册设备

@param deviceToken 通过appdelegate的didRegisterForRemoteNotificationsWithDeviceToken
回调的获取
@param successCallback 成功回调
@param errorCallback 失败回调
@return 获取的 deviceToken 字符串
*/
+(nullable NSString *)registerDevice:(nonnull NSData *)deviceToken
successCallback:(nullable void (^)(void)) successCallback
errorCallback:(nullable void (^)(void)) errorCallback;

/**
注册设备并且设置账号

@param deviceToken 通过appDelegate的didRegisterForRemoteNotificationsWithDeviceToken
回调的获取
@param account 需要设置的账号,长度为2个字节以上,不要使用"test","123456"这种过于简单的字符串,
若不想设置账号,请传入nil
@param successCallback 成功回调
@param errorCallback 失败回调
@return 获取的 deviceToken 字符串
*/
+(nullable NSString *)registerDevice:(nonnull NSData *)deviceToken
account:(nullable NSString *)account
successCallback:(nullable void (^)(void)) successCallback
errorCallback:(nullable void (^)(void)) errorCallback;

/**
注册设备并且设置账号, 字符串 token 版本

@param deviceToken NSString *类型的 token
@param account 需要设置的账号,若不想设置账号,请传入 nil
@param successCallback 成功回调
@param errorCallback 失败回调
@return 获取的 deviceToken 字符串
*/
+(nullable NSString *)registerDeviceStr:(nonnull NSString *)deviceToken
account:(nullable NSString *) account
successCallback:(nullable void(^)(void)) successCallback
errorCallback:(nullable void(^)(void))errorCallback;

(2)示例

- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

NSString *deviceTokenStr = [XGPush registerDevice:deviceToken
account:nil
successCallback:^{
NSLog(@"[XGPush Demo] register push success");
} errorCallback:^{
NSLog(@"[XGPush Demo] register push error");
}];
NSLog(@"[XGPush Demo] device token is %@", deviceTokenStr);
}

注意:account是需要设置的账号,视业务需求自定义,可以是用户的名称或者ID等,长度为2个字节以上,不要使用"myAccount"或者"test","123456"这种过于简单的字符串,若不想设置账号,请传入nil

1.3.5. 设置/删除标签

开发者可以针对不同的用户设置标签,然后对该标签推送.对标签推送会让该标签下的所有设备都收到推送.一个设备可以设置多个标签.

(1)接口

/**
设置 tag

@param tag 需要设置的 tag
@param successCallback 成功回调
@param errorCallback 失败回调
*/
+(void)setTag:(nonnull NSString *)tag
successCallback:(nullable void (^)(void)) successCallback
errorCallback:(nullable void (^)(void)) errorCallback;


/**
删除tag

@param tag 需要删除的 tag
@param successCallback 成功回调
@param errorCallback 失败回调
*/
+(void)delTag:(nonnull NSString *)tag
successCallback:(nullable void (^)(void)) successCallback
errorCallback:(nullable void (^)(void)) errorCallback;

(2)示例

- (void)setTag:(NSString *)tag {
[XGPush setTag:@"myTag" successCallback:^{
NSLog(@"[XGDemo] Set tag success");
} errorCallback:^{
NSLog(@"[XGDemo] Set tag error");
}];
}


- (void)delTag:(NSString *)tag {
[XGPush delTag:@"myTag" successCallback:^{
NSLog(@"[XGDemo] Del tag success");
} errorCallback:^{
NSLog(@"[XGDemo] Del tag error");
}];
}

1.3.6. 设置/删除账号

开发者可以针对不同的用户设置账号,然后对账号推送.对账号推送会让该账号下的所有设备都收到推送.

注1: 一个账号最多绑定15台设备,超过之后会随机解绑一台设备,然后再进行注册.

注2: 老版本不带回调的接口要求设置/删除账号后再调用一次注册设备的方法,但是新版带回调的接口不需要再调用注册设备的方法

(1)接口

/**
设置设备的帐号. 设置账号前需要调用一次registerDevice

@param account 需要设置的账号,长度为2个字节以上,不要使用"test","123456"这种过于简单的字符串
@param successCallback 成功回调
@param errorCallback 失败回调
*/
+(void)setAccount:(nonnull NSString *)account
successCallback:(nullable void(^)(void)) successCallback
errorCallback:(nullable void(^)(void)) errorCallback;


/**
删除已经设置的账号. 删除账号前需要调用一次registerDevice

@param successCallback 成功回调
@param errorCallback 失败回调
*/
+(void)delAccount:(nullable void(^)(void)) successCallback
errorCallback:(nullable void(^)(void)) errorCallback;

(2)示例

- (void)setAccount:(NSString *)account {
[XGPush setAccount:@"myAccount" successCallback:^{
NSLog(@"[XGDemo] Set account success");
} errorCallback:^{
NSLog(@"[XGDemo] Set account error");
}];
}

- (void)delAccount {
[XGPush delAccount:^{
NSLog(@"[XGDemo] Del account success");
} errorCallback:^{
NSLog(@"[XGDemo] Del account error");
}];
}

1.3.7. 注销设备

注销设备以后,可以让该设备不再接收推送.

(1)接口

/**
注销设备,设备不再进行推送
@param successCallback 成功回调
@param errorCallback 失败回调
*/
+(void)unRegisterDevice:(nullable void (^)(void)) successCallback
errorCallback:(nullable void (^)(void)) errorCallback;

(2)示例

[XGPush unRegisterDevice:^{
NSLog(@"[XGDemo] unregister success");
} errorCallback:^{
NSLog(@"[XGDemo] unregister error");
}];

注意:重新开启推送功能需要再次调用registerAPNS和registerDevice接口。

1.4. 推送效果统计

如果需要统计由信鸽推送的点击或者打开.

1.4.1. 统计打开

对于统计打开需要开发者在UIApplicationDelegate中的

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;

调用 handleLaunching 方法

(1)接口

/**
在didFinishLaunchingWithOptions中调用,用于推送反馈.(app没有运行时,点击推送启动时)

@param launchOptions didFinishLaunchingWithOptions中的userinfo参数
@param successCallback 成功回调
@param errorCallback 失败回调
*/
+(void)handleLaunching:(nonnull NSDictionary *)launchOptions
successCallback:(nullable void (^)(void)) successCallback
errorCallback:(nullable void (^)(void)) errorCallback;

(2)示例

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

[XGPush handleLaunching:launchOptions successCallback:^{
NSLog(@"[XGDemo] Handle launching success");
} errorCallback:^{
NSLog(@"[XGDemo] Handle launching error");
}];
}

1.4.2. 统计点击

  • iOS 10 以前的系统版本

对于 iOS 10 以前的系统版本,需要在 UIApplicationDelegate 中的

- (void)application:(UIApplication *)application
didReceiveRemoteNotification:(NSDictionary *)userInfo;

中调用 handleReceiveNotification 方法

(1)接口

/**
在didReceiveRemoteNotification中调用,用于推送反馈。(app在运行时)

@param userInfo 苹果 apns 的推送信息

@param successCallback 成功回调

@param errorCallback 失败回调
*/
+(void)handleReceiveNotification:(nonnull NSDictionary *)userInfo
successCallback:(nullable void (^)(void)) successCallback
errorCallback:(nullable void (^)(void)) errorCallback;

(2)示例

- (void)application:(UIApplication *)application
didReceiveRemoteNotification:(NSDictionary *)userInfo {

NSLog(@"[XGPush Demo] receive Notification");
[XGPush handleReceiveNotification:userInfo
successCallback:^{
NSLog(@"[XGDemo] Handle receive success");
} errorCallback:^{
NSLog(@"[XGDemo] Handle receive error");
}];
}
  • iOS 10 对于 iOS 10, 需要在 UNUserNotificationCenterDelegate 的
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
didReceiveNotificationResponse:(UNNotificationResponse *)response
withCompletionHandler:(void(^)())completionHandler;

中调用 handleReceiveNotification 方法

(1)接口

/**
在didReceiveRemoteNotification中调用,用于推送反馈。(app在运行时)

@param userInfo 苹果 apns 的推送信息
@param successCallback 成功回调
@param errorCallback 失败回调
*/
+(void)handleReceiveNotification:(nonnull NSDictionary *)userInfo
successCallback:(nullable void (^)(void)) successCallback
errorCallback:(nullable void (^)(void)) errorCallback;

(2)示例

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
didReceiveNotificationResponse:(UNNotificationResponse *)response
withCompletionHandler:(void(^)())completionHandler {

[XGPush handleReceiveNotification:response.notification
.request.content.userInfo
successCallback:^{
NSLog(@"[XGDemo] Handle receive success");
} errorCallback:^{
NSLog(@"[XGDemo] Handle receive error");
}];

completionHandler()
}

1.5. 本地推送

本地推送相关功能请参考苹果开发者文档.

results matching ""

    No results matching ""