个推SDK集成
iOS SDK开发准备
由于iOS系统限制,在后台的应用将无法维持长连接。个推服务器发送消息给离线用户时,会利用苹果推送系统发送APNS 到用户设备上,所以需要应用配合提交APS证书和DeviceToken。
1. 运行环境
iOS 4.0+
GPRS、3G或Wi-Fi等网络
手机可以没有SIM卡,但是可能导致部分功能缺失 Apple应用ID和对应推送证书(APNS证书,请参照附录1:创建Apple应用并创建APNS推送证书)
2. 创建Apple应用ID和APNS推送证书个推需要通过APNS来唤醒您的应用,所以需要对应app的推送证书。如果对获取推送证书有疑问,请参照附录:
创建Apple应用并创建APNS推送证书
3. 注册账号并登记应用(必须)
[1] 访问个推开放平台(http://dev.igetui.com),点击“立即注册”注册个推账户 [2] 按要求填入用户名、邮箱等基本信息,注册并激活账户
[3] 登录个推平台,按照提示登记应用,输入应用相关信息,上传iOS应用证书,点击“保存”创建您的应用。记录生成应用的AppKey/AppID/AppSecret信息(详看常见名词介绍),后续客户端集成过程中需要用到
4. 获取SDK开发工具包(必须)
5. 了解个推推送服务框架
|
说明:
|
iOS SDK集成步骤
概述
1. 项目设置
2. Link to the SDK
3. iOS应用&Server&getui SDK&getui Server和Apple Push Notification Server的交互过程
概述
我们提供的一个SDK开发工具包,包含了iOS SDK的全部所需资源,解压缩后的文件目录结构如图:
其中dist目录包含集成SDK所需的静态库和头文件。
注意: libGexinSdk-{version}.a(version为具体的sdk版本号)使用libo工具将支持i386、armv6、armv7和armv7s的代码打包到了一起,所以这个库将同时支持simu
1. 项目设置
导入dist/include/所有的头文件、libGexinSdk-{version}.a文件和几个系统库到XCode项目中就可以开始code了。 将dist目录拷贝到项目工程目录下
添加头文件搜索目录
添加库文件
个推SDK依赖几个额外的系统库支持,还需要导入以下5个库:
libz.dylib
libsqlite3.dylib Security.framework SystemConfiguration.framework CFNetwork.framework
2. Link to the SDK
要使用个推的推送服务需要创建一个GexinSdk的对象,由这个对象来和个推服务器完成必要交互。
创建GexinSdk对象需要提供GexinSdkDelegate的observer来接收推送的回调消息。 除了接收个推的推送消息,个推还使用APNS来唤醒应用,如果需要处理APNS消息,请参考Demo工程 个推SDK还支持发送消息到服务器(具体参考SDK reference),这点是APNS不具备的功能。 最后个推还可以对client打标签(Tag),请参考SDK reference。 具体的集成过程请看demo/bld/Demo.xcodeproj工程。
备注:demo/bld/StartApp.xcodeproj是用来演示通过个推启动其它应用的。StartApp注册Url sharedApplication] openURL:aUrl];打开。
API:iOS
本文档介绍了iOS SDK API的基本说明和使用方法,如有更多疑问,请联系我们
设置处理显示的AlertView是否随屏幕旋转 | 创建个推SDK的对象 | 根据payloadId接收推送消息 提交APNS注册后返回的deviceToken | 设置用户标签 | 从客户端发送上行消息到应用服务器 关闭通道并清理资源 | SDK注册成功通知 | SDK通知收到个推推送消息 SDK通知发送上行消息结果 | SDK通知发送错误 | 错误状态定义 获取用户的ClientID | 绑定用户别名(iOS) | 解绑用户别名(iOS)
设置处理显示的AlertView是否随屏幕旋转
setAllowedRotateUiOrientations
当推送弹框消息,SDK会根据这个来设置处理显示的AlertView是否随屏幕旋转。 +(void)setAllowedRotateUiOrientations:(NSArray *)orientations;
参数
orientations:支持的屏幕方向列表,具体值请参照UIInterfaceOrientation(From iOS SDK)
说明 设置为与您的应用中shouldAutorotateToInterfaceOrientation中相同的参数,这样不会因为推送消息弹框导致您的UI意外旋转到不希望的模式。 头文件
GexinSdk.h
注意:如果不关心UI方向,不要调用这个方法。
下一个
创建个推SDK的对象
createSdkWithAppId:appKey:appSecret:appVersion:delegate:error
创建个推SDK的对象
+ (GexinSdk *)createSdkWithAppId:(NSString *)appid
appKey:(NSString *)appKey
appSecret:(NSString *)appSecret
appVersion:(NSString *)aAppVersion
delegate:(id<GexinSdkDelegate>)delegate
error:(NSError **)error;
参数
appid:个推登记应用的appid
appKey:个推登记应用的appKey
appSecret:个推登记应用的appSecret
delegate:推送消息回调接口
error:错误消息,保留参数
说明 appid、appKey和appSecret必须正确,否则会导致推送消息无法接收。目前无法在error参数中告知这类错误信息。 请不用用同一个appid创建多个对象。
头文件
GexinSdk.h
上一个 下一个
根据payloadId接收推送消息
retrivePayloadById
- (NSData *)retrivePayloadById:(NSString *)payloadId;
参数 payloadId:接收的推送消息的id,如果id不正确,将无法取到消息内容。 返回值
无法取到消息内容,返回nil。
说明 SDK仅保持5天内的消息,请及时获取。已获取的消息无法再次获取。 头文件
GexinSdk.h
上一个 下一个
提交APNS注册后返回的devicetoken
registerDeviceToken
提交APNS注册后返回的deviceToken。
- (void)registerDeviceToken:(NSString *)deviceToken;
参数
deviceToken:APNS返回的client标识。
说明
个推服务需要使用APNS来辅助推送消息,如果不提交deviceToken,会导致推送功能不正常。 请在收到
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken 后将deviceToken字符取出后调用这个接口提交deviceToken。具体实现请参考Demo工程。 如果注册APNS失败导致无法获取deviceToken,仍然需要上传空的deviceToken,个推服务器在应用离线的时候将不会发送APNS。 头文件
GexinSdk.h
上一个 下一个
设置用户标签
setTags
给用户打标签
- (BOOL)setTags:(NSArray *)tags;
参数 tags:NSString的对象数组,不能为nil。只能包含中文字符、英文字母、0-9、空格、+-*.的组合。 返回值
如果tags参数不合法,返回NO。
说明
给用户打标签,可以在个推后端根据标签内容做差异化推送。具体请询问技术支持。 会覆盖上一次的调用结果。 头文件
GexinSdk.h
上一个 下一个
从客户端发送上行消息到应用服务器
sendMessage:error
客户端发送上行消息到应用服务器。
- (NSString *)sendMessage:(NSData *)body error:(NSError **)error; 参数
body:二进制消息内容
error:保留
返回值
消息id,如果发送前验证失败返回nil;
说明 请不要数据量发送过大消息。不要过于频繁发送消息,否则消息可能丢失。 头文件
GexinSdk.h
上一个 下一个
关闭通道并清理资源
destroy
关闭通道并清理资源。用于在开启ARC的项目中替换release调用。 - (void)destroy;
参数
无
返回值
无
头文件 GexinSdk.h
上一个 下一个
SDK注册成功通知
GexinSdkDidRegisterClient
SDK注册成功通知。
- (void)GexinSdkDidRegisterClient:(NSString *)clientId;
参数
clientId:标识用户的clientId
说明
创建GexinSdk对象后,SDK会自动向个推服务器注册SDK,当成功注册时,SDK通知应用注册成功。 注意:注册成功仅表示推送通道建立,如果appid/appkey/appSecret等验证不通过,依然无法接收到推送消息,请确保验证信息正确
上一个 下一个
SDK通知收到个推推送消息
GexinSdkDidReceivePayload:fromApplication
SDK通知收到个推推送消息。
- (void)GexinSdkDidReceivePayload:(NSString *)payloadId fromApplication:(NSString *)appId;
参数
payloadId:代表推送消息的唯一id
appId:应用的appId
说明
SDK会将推送消息在本地数据库中保留5天,请及时取出(See retrivePayloadById:),取出后消息将被删除。
上一个 下一个
SDK通知发送上行消息结果
GexinSdkDidSendMessage:result
SDK通知发送上行消息结果。See Also:sendMessage:error:
- (void)GexinSdkDidSendMessage:(NSString *)messageId result:(int)result; 参数
messageId:sendMessage:error:返回的id
result:成功返回0
上一个 下一个
SDK通知发送错误GexinSdkDidOccurError
SDK通知发送错误。集成SDK时用来告知使用SDK的错误。- (void)GexinSdkDidOccurError:(NSError *)error;
参数
error:错误
上一个 下一个
错误状态定义GXErrorNO
说明
上一个 下一个
获取用户的ClientID
clientId
说明
- (NSString *)clientId;
参数
无。
返回值
返回当前用户的ClientID
说明 当前用户的ClientID,如果ClientID不存在,返回null 头文件
GexinSdk.h
上一个 下一个
绑定用户别名(iOS)bindAlias
typedef enum {
GXSdkRegisterFailed = -1000,
GXSdkBindAppIDFailed,
GXSdkFeedbackFailed,
} GXSdkErrorNO;
GXSdkRegisterFailed 注册失败 GXSdkBindAppIDFailed Deprecated GXSdkFeedbackFailed Feedback失败
- (void)bindAlias:(NSString *)alias;
参数 alias:别名名称:长度40字节,支持中、英文(区分大小写)、数字以及下划线。 说明
1、同一个别名最多绑定10个ClientID(适用于允许多设备同时登陆的应用),当已绑定10个ClientID时,再次调用此接口会自动解绑最早绑定的记录; 2、当ClientID已绑定了别名A,若调用此接口绑定别名B,则与别名A的绑定关系会自动解除; 3、此接口与unBindAlias一天内最多调用100次,两次调用的间隔需大于5s;
头文件
GexinSdk.h
上一个 下一个
解绑用户别名(iOS)
unbindAlias
- (void)unbindAlias:(NSString *)alias;
参数 alias:别名名称:长度40字节,支持中、英文(区分大小写)、数字以及下划线。 说明
1、此接口与bindAlias一天内最多调用100次,两次调用的间隔需大于5s;
2、只能解绑当前手机ClientID与别名的关系,不能解绑其他手机上ClientID与别名的关系; 头文件
GexinSdk.h
上一个