iOS 信鸽SDK完整接入

iOS 信鸽SDK完整接入

简介

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

注意：请按照指南进行SDK配置，以免引起不必要的错误。

运行环境

iOS 5.0 及以上版本。在程序启动时注册通知，参考以下代码：

- (void) registerNofitication {
[[UIApplication sharedApplication] registerForRemoteNotificationTypes:(UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound)];
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[self registerNofitication];
return YES;
}

功能

获取Access ID和Access Key

前往信鸽官网 http://xg.qq.com ，用QQ号登录，添加应用基本信息并注册，之后可获取Access ID和Access Key。

工程配置

1、 下载信鸽SDK压缩包到本地并解压；

2、 创建或打开Xcode iOS工程；

3、 将XGSetting.h 和 XGPush.h 和 libXG-SDK.a添加到Xcode工程；

4、 添加对以下libraries的引用。包括CFNetwork.framework , SystemConfiguration.framework , CoreTelephony.framework , libz.dylib , libXG-SDK.a，Security.framework, libsqlite3.0.tbd（官网上的流程缺了这个，博主就是漏了这个，一直有错误提示）

API接口

类名：XGPush

说明：Push服务，推送效果

注意：在Console(控制台)里会看到“[xgpush]Disconnected.”为正常现象，在调用信鸽接口时候，如果服务器响应超时或者已经成功收到服务器的返回数据，手机会断开和服务器的连接。

注册苹果推送服务

在Demo中可以看到具体实现，对iOS8和之前的版本做了区分。

示例

//注册Push服务，注册后才能收到推送

//iOS8注册push方法

#if __IPHONE_OS_VERSION_MAX_ALLOWED >= _IPHONE80_
[self registerPushForIOS8]; //具体实现参考Demo
#else
//iOS8之前注册push方法
[[UIApplication sharedApplication] registerForRemoteNotificationTypes:(UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound)];
#endif

注册设备信息

在application: didRegisterForRemoteNotificationsWithDeviceToken中调用。

注意:设备的deviceToken由苹果下发，可能会产生变化。同一设备在开发环境和生产环境是不相同的。

发起注册条件

未注册

account变更

距离上次注册成功超过15小时。达到以上条件才能向后台进行网络请求，以及触发回调函数。

函数原型

+(NSString*)registerDevice:(NSData *)deviceToken;
+(NSString *)registerDeviceStr:(NSString *)deviceToken;
//字符串版

参数说明

deviceToken：函数didRegisterForRemoteNotificationsWithDeviceToken的参数。

返回值

NSString：获取到的deviceToken字符串

示例

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
//注册设备
NSString * deviceTokenStr = [XGPush registerDevice: deviceToken];

//打印获取的deviceToken的字符串
NSLog(@"deviceTokenStr is %@",deviceTokenStr);
}

初始化push信息

在application: didFinishLaunchingWithOptions中调用startWithAppkey接口，初始化。

函数原型

+(void)startApp:(uint32_t)appId appKey:(NSString *)appKey;

参数说明

Access Id: 通过xg.qq.com注册app时得到的Access Id。

Access key：通过xg.qq.com注册app时得到的Access key。

返回值

无

示例

[XGPush startApp:101 appKey:@"akey"];

设置帐号

上报用户的帐号，以便支持按帐号推送。

使用指定的账号（一个账号可能在多个设备登陆）注册APP，这样可以通过后台向指定的账号发送推送消息。

注意：这里的帐号可以是邮箱、QQ号、手机号、用户名等任意类别的业务帐号。

在初始化信鸽后，注册设备之前调用。

函数原型

+(void)setAccount:(NSString *)account;

参数说明

account: 用户的别名(帐号)

返回值

无

示例

[XGPush setAccount:@"123456"];

设置标签

开发者可以针对不同的用户设置标签。标签如性别、年龄、学历、爱好等，app业务本身均可以通过自己的数据定制。

函数原型

+(void)setTag:(NSString*)tag;

参数说明

tag：字符串

返回值

无

示例

NSString* tag= @"age:10";

[XGPush setTag: tag];

删除标签

开发者可以删除设置过的标签。

函数原型

+(void)delTag:(NSString *)tag;

参数说明

tag：字符串

返回值

无

示例

NSDictionary* tag= @"age:10";

[XGPush delTag: tag];

打开效果统计

如果需要统计由信鸽推送的点击或者打开，需要开发者在didReceiveRemoteNotification(如果没有则按照下面的示例手动添加)中调用handleReceiveNotification , 然后在didFinishLaunchingWithOptions中调用handleLaunching。

注意：

如果app在前台运行时，不会收到弹窗。

但是通过userInfo可以取到推送的信息（包括内容，角标，自定义参数等）

如果需要弹窗，则需要自行编码。

函数原型

+(void)handleReceiveNotification:(NSDictionary *)userInfo;
//app在运行时
+(void)handleLaunching:(NSDictionary *)launchOptions;
//app不在运行时，点击推送激活时

参数说明

事件本身默认的参数名

返回值

无

示例

- (void)application:(UIApplication*)application didReceiveRemoteNotification:(NSDictionary*)userInfo
{
[XGPush handleReceiveNotification:userInfo];
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[XGPush handleLaunching: launchOptions];
}

注销设备

注销设备,此台设备不接收推送。

函数原型

+(void)unRegisterDevice;

示例

[XGPush unRegisterDevice];

注销后再注册

如果注销设备后，需要重新注册设备，需要先调用以下函数。

函数原型

+(void)initForReregister:(void (^)(void)) successCallback;

示例

[XGPush startApp:2200022728 appKey:@"IMJ34Y25JN4I"];

void (^successCallback)(void) = ^(void){
//中间部分参考Demo中的代码
};
[XGPush initForReregister:successCallback];

本地推送通知

一般本地推送

在指定时间进行本地推送。常用于定时提醒如领取体力，每日记录或签到等场景。

函数原型

+(void)localNotification:(NSDate *)fireDate alertBody:(NSString *)alertBody badge:(int)badge alertAction:(NSString *)alertAction userInfo:(NSDictionary *)userInfo;

参数说明

fireDate: 推送触发的时间

alertBody: 推送的内容

badge: 改变App的角标，如果为-1，则不改变。

alertAction: 推送的右侧按钮的文字，默认为“启动”。

userInfo: 自定义的一组key/value信息

示例

[XGPush localNotification:fireDate alertBody:@"测试本地推送" badge:2 alertAction:@"确定" userInfo:userInfo];

App在前端运行时响应本地推送

App在前台运行时，苹果的推送默认不弹窗。通过此接口可进行弹窗。

函数原型

+(void)localNotificationAtFrontEnd:(UILocalNotification *)notification userInfoKey:(NSString *)userInfoKey userInfoValue:(NSString *)userInfoValue;

参数说明

userInfoKey: 标识本地推送的Key

userInfoValue: 标识本地推送的Value

示例

[XGPush localNotificationAtFrontEnd:notification userInfoKey:@"clockID" userInfoValue:@"myid"];

删除本地推送【方法一】

iOS最多允许一个App存储64个本地推送。以下函数可以进行删除。

函数原型

+(void)delLocationNotification:(NSString *)userInfoKey userInfoValue:(NSString *)userInfoValue;

参数说明

userInfoKey: 标识本地推送的Key

userInfoValue: 标识本地推送的Value

返回值

无

示例

[XGPush delLocationNotification:@"clockID" userInfoValue:@"myid"];

删除本地推送【方法二】

iOS最多允许一个App存储64个本地推送。以下函数可以进行删除。

函数原型

+(void)delLocationNotification:(UILocalNotification *)myUILocalNotification;

参数说明

myUILocalNotification: 本地推送对象

返回值

无

示例

[XGPush delLocationNotification:notification];

清空所有本地推送

iOS最多允许一个App存储64个本地推送。以下函数可以进行清空。

函数原型

[XGPush clearLocalNotifications];

参数说明

无

返回值

无

示例

[XGPush clearLocalNotifications];

回调函数说明

从2.1.0(含)版本之后，带有网络请求的接口都增加了回调函数，包括成功时的回调successCallback和失败时的回调errorCallback

2.1.0之前的版本可以通过Console里的rspCode判断结果，为0代表成功。

函数原型

succussCallback:(void (^)(void)) successCallBack
errorCallback:(void (^)(void)) errorCallback

返回值

无

示例

void (^succussBlock)(void) = ^(void){
//成功之后的处理
NSLog(@"[xgpush]register succussBlock ,deviceToken: %@",deviceTokenStr);
};

void (^errorBlock)(void) = ^(void){
//失败之后的处理
NSLog(@"[xgpush]register errorBlock");
};

//注册设备
[XGPush registerDevice:deviceToken succussCallback:succussBlock errorCallback:errorBlock];

iOS推送结果

app在前台运行时，不弹出推送框，但是app通过代码可以获取到推送的消息。

app在后台运行或者杀死状态时，会弹出推送框并且可以通过代码获取到推送的消息。

app在前台和后台运行时，推送上报触发的是didReceiveRemoteNotification事件。

app在杀死状态时，推送上报触发的是didFinishLaunchingWithOptions事件。

用户能接收到的如下：

用户进入App，按home键，发送信鸽消息，可以接收到弹窗和通知中心的通知；

用户进入App，按home键，进程杀掉，可以接收到弹窗和通知中心的通知；

用户进入App，保持在App中，后台可以接收到信鸽消息，但是前台没有弹窗和通知中心通知。

iOS注意事项

信鸽只能保证将消息转交APNS，因此若APNS出错会产生一定得推送时间误差。

APNS只为离线终端保存一条消息，所以离线终端上线后仅能收到离线期间最新的一条消息。

受APNS和iOS的限制，效果统计功能可能会有一定得统计误差。