个推平台客户端SDK接入文档

个推平台客户端SDK接入文档

编号:GEXIN_iOS_Native
版本:GEXIN_iOS_SDK V1.0.5

运行环境

1. iOS 4.0+
2. GPRS、3G或Wi-Fi等网络
3. 手机可以没有SIM卡，但是可能导致部分功能缺失
4. Apple应用ID和对应推送证书（APNS证书，请参照附录1：创建Apple应用并创建APNS推送证书）

 

说明

Appkey：预先分配的第三方应用ID。

AppSecret：认证密钥，预先协商后登记到双方服务端。

ClientID：用于标识客户端身份，由第三方客户端获取并保存到第三方服务端。

payload：透明数据（对用户透明），支持二进制格式（不支持转义字符），数据大小 不超过2k。个推系统不对消息内容进行解释，只负责将数据透传至第三方客户端。

1.开发准备

由于iOS系统限制，在后台的应用将无法维持常连接。个推服务器发送消息给离线用户时，会利用苹果推送系统发送APN到用户设备上，所以需要应用配合提交APS证书和DeviceToken。

1.1 创建Apple应用ID和APNS推送证书

个推需要通过APN来唤醒您的应用，所以需要对应app的推送证书。如果对获取推送证书有疑问，请参照附录1：创建Apple应用并创建APNS推送证书

1.2 注册账号并登记应用（必须）

【1】访问个推开放平台（http://dev.），点击“免费注册”注册个推账户

【2】按要求填入用户名、邮箱等基本信息，注册并激活账户

【3】登录个推平台，按照提示登记应用，输入应用相关信息，勾选“Android”类型，输入应用标识，点击“保存”创建您的应用

（应用标识如为Android，填写为工程的package name，通常以com开始；如为iOS，填写为bundleid；如果Android和iOS公用，则按android填写）

1.3获取SDK开发工具包（必须）

在网站下载开发工具包，包含客户端和服务端两部分：
下载地址：http://www./download/iOS/SDK_OPEN_IOS.zip

【1】客户端资料包含：

· 文档
· 需导入的资源
· 演示工程源码 

【2】服务端资料包含：

· 文档（服务端API文档，详细指导如何调用接口） 
· 需导入的资源  

1.4上传证书

个推管理后台暂时不能提交iOS的push证书，需要将：

·个推appid（参照注册账号并登记应用（必须））

·相关应用的bundle id

·APNS证书（.p12格式）以及相应的环境（沙箱环境或者生产环境）

·APNS证书的密码

通过QQ或email等方式提供给我们（技术支持）。

对bundle id和APNS证书有疑问，请参照创建Apple应用ID和APNS推送证书。

注意：这是iOS SDK能够接收到推送消息的必要步骤。

2.开发环境

建议使用XCode 4.5或以上版本

3.SDK集成步骤

我们提供的一个ZIP压缩包，包含了SDK的全部所需资源，解压缩后的文件目录结构如图：

其中dist目录包含集成SDK所需的静态库和头文件。

注意：libGexinSdk-{version}.a（version为具体的sdk版本号）使用libo工具将支持i386、armv6、armv7和armv7s的代码打包到了一起，所以这个库将同时支持simulator和device。

3.1项目设置

导入dist/include/所有的头文件、libGexinSdk-{version}.a文件和几个系统库到XCode项目中就可以开始code了。

将dist目录拷贝到项目工程目录下 
cp -r {your sdk path}/getui-ios-sdk-0.9.2/dist {third-patry libs in your project}/getui-sdk

添加头文件搜索目录

添加库文件

个推SDK依赖几个额外的系统库支持，还需要导入以下5个库:

libz.dylib

libsqlite3.dylib

Security.framework

SystemConfiguration.framework

CFNetwork.framework

3.2 Link to the SDK

要使用个推的推送服务需要创建一个GexinSdk的对象，由这个对象来和个推服务器完成必要交互。具体的交互过程，请参考附录2： iOS应用&Server、getui SDK、getui Server和Apple Push Notification Server的交互过程。创建GexinSdk对象需要提供GexinSdkDelegate的observer来接收推送的回调消息。

除了接收个推的推送消息，个推还使用APN来唤醒应用，如果需要处理APN消息，请参考Demo工程

个推SDK还支持发送消息到服务器（具体参考SDK reference），这点是APNS不具备的功能。

最后个推还可以对client打标签（Tag），请参考SDK reference。

具体的集成过程请看demo/bld/Demo.xcodeproj工程。

备注：demo/bld/StartApp.xcodeproj是用来演示通过个推启动其它应用的。StartApp注册Url schema，可以通过[[UIApplication sharedApplication] openURL:aUrl];打开。

3.3 iOS应用&Server、getui SDK、getui Server和Apple Push Notification Server的交互过程（重要）

请仔细阅读该流程，如有疑问，可随时和我们技术支持的同学联系

4. SDK接口文档

GexinSdk

setAllowedRotateUiOrientations

当推送弹框消息，SDK会根据这个设置来处理显示AlertView是否随屏幕旋转。
+(void)setAllowedRotateUiOrientations:(NSArray *)orientations; 

参数

orientations:支持的屏幕方向列表，具体值请参照UIInterfaceOrientation（From iOS SDK）

说明

设置为与您的应用中shouldAutorotateToInterfaceOrientation中相同的参数，这样不会因为推送消息弹框导致您的UI意外旋转到不希望的模式。

头文件

GexinSdk.h

注意：如果不关心UI方向，不要调用这个方法。

createSdkWithAppId:appKey:appSecret:appVersion:delegate:error

创建个推SDK的对象
+ (GexinSdk *)createSdkWithAppId:(NSString *)appid 
appKey:(NSString *)appKey 
appSecret:(NSString *)appSecret 
appVersion:(NSString *)aAppVersion 
delegate:(id)delegate 
error:(NSError **)error;

参数

appid:个推登记应用的appid

appKey:个推登记应用的app Key

appSecret:个推登记应用的app secret

delegate:推送消息回调接口

error:错误消息，保留参数

说明

appid、appKey和appSecret必须正确，否则会导致推送消息无法接收。目前无法在error参数中告知这类错误信息。
请不用用同一个appid创建多个对象。

头文件

GexinSdk.h

retrivePayloadById

- (NSData *)retrivePayloadById:(NSString *)payloadId;

参数

payloadId:接收的推送消息的id，如果id不正确，将无法取到消息内容。

返回值

无法取到消息内容，返回nil。

说明

SDK仅保持5天内的消息，请及时获取。已获取的消息无法再次获取。

头文件

GexinSdk.h

registerDeviceToken

提交APNS注册后返回的device token。 
- (void)registerDeviceToken:(NSString *)deviceToken;

参数

deviceToken:APNS返回的client标识。

说明

个推服务需要使用APN来辅助推送消息，如果不提交deviceToken，会导致推送功能不正常。 请在收到 
- (void)application:(UIApplication *)application 
didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken 
后将deviceToken字符取出后调用这个接口提交device token。具体实现请参考Demo工程。 如果注册APNS失败导致无法获取deviceToken，仍然需要上传空的deviceToken，个推服务器在应用离线的时候将不会发送APN。

头文件

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

GexinSdkDelegate

GexinSdkDidRegisterClient

SDK注册成功通知。 
- (void)GexinSdkDidRegisterClient:(NSString *)clientId;

参数

clientId:标识用户的clientId

说明

创建GexinSdk对象后，SDK会自动向个推服务器注册SDK，当成功注册时，SDK通知应用注册成功。

注意：注册成功仅表示推送通道建立，如果appid/appkey/appSecret等验证不通过，依然无法接收到推送消息，请确保验证信息正确

GexinSdkDidReceivePayload:fromApplication

SDK通知收到个推推送消息。
- (void)GexinSdkDidReceivePayload:(NSString *)payloadId fromApplication:(NSString *)appId;

参数

payloadId:代表推送消息的唯一id

appId:应用的appId

说明

SDK会将推送消息在本地数据库中保留5天，请及时取出（See retrivePayloadById：），取出后消息将被删除。

GexinSdkDidSendMessage:result

SDK通知发送上行消息结果。See Also:sendMessage:error:
- (void)GexinSdkDidSendMessage:(NSString *)messageId result:(int)result;

参数

messageId:sendMessage:error:返回的id

result:成功返回0

GexinSdkDidOccurError

SDK通知发送错误。集成SDK时用来告知使用SDK的错误。
- (void)GexinSdkDidOccurError:(NSError *)error;

参数

error:错误

GXErrorNO

    typedef enum {
    GXSdkRegisterFailed = -1000,
    GXSdkBindAppIDFailed,
    GXSdkFeedbackFailed,
} GXSdkErrorNO;

说明

GXSdkRegisterFailed
注册失败
GXSdkBindAppIDFailed
Deprecated
GXSdkFeedbackFailed
Feedback失败

5. 技术支持

联系电话：北京010-84471969杭州0571-85350669

商务合作：陈先生18018556088

网址：

商务合作邮箱：[e-mail] 

附录1：创建Apple应用并创建APNS推送证书

创建应用程序ID

登陆iOS Dev Center选择进入iOS Provisioning Portal。

在Certificates，Identifiers &Profiles中，点iOS Apps的任何一项进入

在iOS Provisioning Portal中，点击App IDs进入App ID列表。

创建App ID，如果ID已经存在可以直接跳过此步骤

为App开启Push Notification功能。如果是已经创建的App ID也可以通过设置开启Push Notification功能。

根据实际情况完善App ID信息并提交,注意此处需要指定具体的Bundle ID不要使用通配符。

配置和下载证书

如果你之前没有创建过Push证书或者是要重新创建一个新的，请在证书列表下面新建。

新建证书需要注意选择证书种类（开发证书用于开发和调试使用，生产证书用于App Store发布）

点击Continue后选择证书对应的应用ID，然后继续会出现“About Creating a Certificate Signing Request (CSR)”。

根据它的说明创建Certificate Signing Request。

然后点击Continue ，上传刚刚生成的 .certSigningRequest文件 点”generate”生成APNs Push Certificate。

下载并双击打开证书，证书打开时会启动“钥匙串访问”工具。

在“钥匙串访问”中你的证书会显示在“我的证书”中，注意选择“My Certificates” 和”login”

导出 .p12证书文件

在“钥匙串访问”中，选择刚刚加进来的证书，选择右键菜单中的“导出“...””。

将文件保存为Personal Information Exchange (.p12)格式。

注意：务必同时选择证书和密钥然后再导出。

保存p12文件时，可以为其设置密码，也可能让密码为空。