Zingle iOS SDK
概览
Zingle 是一个多渠道通讯平台,允许企业与非顾客之间发送、接收和自动处理对话。通常,企业通过网页浏览器与 Zingle 交互以管理与他们顾客的对话。Zingle API 为开发者提供功能,代表企业或非顾客操作。Zingle iOS SDK 为移动应用开发者提供了在 Zingle API 之上的易用层。
要查看最新的 API 文档,请参考:https://github.com/Zingle/rest-api/
联系人与账户类会话的对比
联系会话
联系会话表示像酒店客人这样的人。此会话由使用 Zingle API 的第三方应用程序用户(代表用户)用于与服务(如酒店前台)通信。
本 README 中的所有用法示例都将涉及联系类用法。
账户会话
账户会话表示使用 API 与自己的客人或客户通信的 Zingle 客户。
有关账户类用法的更多信息,请参见 将 SDK 作为账户类用户使用。
使用 CocoaPods 安装
CocoaPods 是 Objective-C 的依赖项管理器,它自动化并简化了在使用第三方库(如 ZingleSDK)的项目中的过程。您可以使用以下命令安装它。
$ gem install cocoapods
CocoaPods 是 Objective-C 的一个依赖项管理器,用于自动化和简化使用第三方库(如 ZingleSDK)的过程。您可以使用以下命令来安装它:
Podfile
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
pod 'ZingleSDK'
要使用 CocoaPods 将 ZingleSDK 集成到您的 Xcode 项目中,请在您的 Podfile
中指定它。
$ pod install
然后,运行以下命令
#import <ZingleSDK/ZingleSDK.h>
在需要的地方导入 SDK 头文件
会话创建
- 要初始化一个联系类会话,需要一些数据。
- Zingle API 用户的令牌(这是您的 Zingle 仪表盘用户名)
- Zingle API 用户的密钥(这是您的 Zingle 仪表盘密码)
- 通道值,例如在自定义聊天类型中当前第三方应用用户的用户名
初始化
使用联系人选择和错误处理块
// Initialize the session object.
session = [ZingleSDK contactSessionWithToken:myToken
key:myKey
channelTypeId:channelId
channelValue:username];
// Optionally set an error-handling block.
// (You may alternatively use the completion block with its error property if you only wish to explicitly handle connection errors.)
session.error = ^(ZNGError * _Nonnull error) {
// Do something with the error
};
// Connect, optionally providing a block to be called once all available contact services have been found
[session connectWithContactServiceChooser:^ZNGContactService * _Nullable(NSArray<ZNGContactService *> * _Nonnull availableContactServices) {
// Choose a contact service and return it immediately or present the user with a choice and return nil
//
[self presentContactServiceChoiceToUser];
return nil;
} completion:nil];
// ... Wait for user input ...
void userDidSelectContactService:(ZNGContactService *)selectedContactService
{
// Choose a contact service if it was not done in the block above, optionally providing a completion block
[session setContactService:selectedContactService completion:^(ZNGContactService * _Nullable contactService, ZNGService * _Nullable service, ZNGError * _Nullable error) {
if (error != nil) {
// Something went wrong
} else {
// You did it!
// If you would like to access the data directly, you may grab a conversation object.
ZNGConversation * conversation = session.conversation;
// You may also grab a view controller that will handle message displaying and sending messages.
ZNGConversationViewController * conversationViewController = session.conversationViewController;
[self presentViewController:conversationViewController animated:YES completion:nil];
}
}];
}
使用KVO
您可以使用KVO来确定当availableContactServices数组被填充时,并处理任何错误。
session = [ZingleSDK contactSessionWithToken:myToken
key:myKey
channelTypeId:channelId
channelValue:username];
[session addObserver:self forKeyPath:@"availableContactServices" options:0 context:NULL];
[session addObserver:self forKeyPath:@"mostRecentError" options:0 context:NULL];
[session connect];
- (void) observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary<NSString *,id> *)change context:(void *)context
{
if ([keyPath isEqualToString:@"availableContactServices"]) {
// Present UI to the user to select a contact service
} else if ([keyPath isEqualToString:@"mostRecentError"]) {
// Handle an error
}
}
void userDidSelectContactService:(ZNGContactService *)selectedContactService
{
[session setContactService:selectedContactService completion:^(ZNGContactService * _Nullable contactService, ZNGService * _Nullable service, ZNGError * _Nullable error) {
if (error != nil) {
NSLog(@"Something went wrong")
} else {
// You did it!
// If you would like to access the data directly, you may grab a conversation object.
ZNGConversation * conversation = session.conversation;
// You may also grab a view controller that will handle message displaying and sending messages.
ZNGConversationViewController * conversationViewController = session.conversationViewController;
[self presentViewController:conversationViewController animated:YES completion:nil];
}
}];
}
使用预选联系服务
您可能希望在登录时立即选择一个联系服务。
// Initialize the session object. This will send off a request for all available contact services.
session = [ZingleSDK contactSessionWithToken:myToken
key:myKey
channelTypeId:channelId
channelValue:username];
[session connectWithContactServiceChooser:^ZNGContactService * _Nullable(NSArray<ZNGContactService *> * _Nonnull availableContactServices) {
if ([availableContactServices containsObject:preselectedContactService]) {
return preselectedContactService;
} else {
// The preselected contact service is not available. Where did it all go wrong?
[self manuallySelectContactService];
return nil;
}
} completion: ^(ZNGContactService * _Nullable contactService, ZNGService * _Nullable service, ZNGError * _Nullable error) {
if (error == nil) {
// You did it!
}
}];
推送通知
当收到推送通知并使用NSNotification通过SDK发送时,会话对象和会话视图控制器对象将刷新数据(请参阅下文“接收推送通知”)
准备接收推送通知
证书和注册
SDK的用户必须在应用中拥有有效的推送通知权限/证书。他还负责在启动时注册应用推送通知能力。请参阅Apple本地和远程通知编程指南以及Ray Wenderlich的推送通知教程。
设置令牌
一旦应用成功注册推送通知,在创建ZingleSession之前,需要在ZingleSDK中设置设备令牌。
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
// ...
application.registerForRemoteNotifications()
// ...
}
func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {
ZingleSDK.setPushNotificationDeviceToken(deviceToken)
}
接收推送通知
一旦建立了一个有效推送通知权限和设置设备令牌的ZingleSession,每当收到新数据时,推送通知将发送到设备。SDK用户需要发布一个NSNotification,以便SDK元素可以接收和响应通知。
All ZingleSDK push notifications should include the Category value of ZingleSDK. A push notification regarding a message will also include the contact service ID of the sender of the message as 'feedId.' Following is a sample push notification dictionary and the Swift code to post an NSNotificationCenter notification to allow ZingleSDK elements to react to the new data.
{
aps = {
alert = {
body = " Jason Nobody \nThis is the message body.";
};
sound = default;
};
feedId = "28e02b1d-a38e-4e6b-85d1-95fe29983a7d";
category = "ZingleSDK";
}
func handleRemoteNotificationDictionary(userInfo: [NSObject : AnyObject], fromApplicationState state: UIApplicationState) {
NSNotificationCenter.defaultCenter().postNotificationName(ZNGPushNotificationReceived, object: nil, userInfo: userInfo)
}
日志记录
The ZingleSDK uses the CocoaLumberjack logging framework with a specific logging context.
#define ZINGLE_LOG_CONTEXT 889
Zingle对象模型
模型 | 描述 |
---|---|
ZingleSDK | 静态类,提供用于Zingle会话对象的便利构造函数 |
ZingleSession | 抽象类,表示与Zingle API的连接 |
ZingleContactSession | 具体子类,表示作为联系人类用户(例如,酒店客人与前台的沟通)与Zingle API的连接 |
ZingleAccountSession | 具体子类,表示作为账户类用户(例如,酒店员工)与Zingle API的连接 |
ZNGAccount | 请参阅Zingle资源概述 - 账户 |
ZNGService | 请参阅Zingle资源概述 - 服务 |
ZNGPlan | 请参阅Zingle资源概述 - 计划 |
ZNGContact | 请参阅Zingle资源概述 - 联系人 |
ZNGAvailablePhoneNumber | 请参阅Zingle资源概述 - 可用电话号码 |
ZNGLabel | 请参阅Zingle资源概述 - 标签 |
ZNGCustomField | 请参阅Zingle资源概述 - 自定义字段 |
ZNGCustomFieldOption | 请参阅Zingle资源概述自定义字段选项 |
ZNGCustomFieldValue | 请参阅Zingle资源概述 - 自定义字段值 |
ZNGChannelType | 请参阅Zingle资源概述 - 通道类型 |
ZNGServiceChannel | 请参阅Zingle资源概述 - 服务通道 |
ZNGContactChannel | 请参阅Zingle资源概述 - 联系人通道 |
ZNGMessageCorrespondent | 消息对应者是消息上的发送者或接收者的抽象表示。 |
ZNGMessageAttachment | 消息附件提供将二进制数据(例如图片)添加到消息的能力。 |
ZNGConversation | 负责维护联系人和服务之间对话状态的模型。 |
ZNGConversationViewController | 管理联系人和服务之间对话的UI。 |
ZNGAutomation | 请参阅Zingle资源概述 - 自动化 |