ZingleSDK 1.1.0

ZingleSDK 1.1.0

测试已测试
语言语言 Obj-CObjective C
许可证 MIT
发布日期上次发布日期2020年10月

Nathan JovinJason Neel维护。



 
依赖项
AFNetworking~> 2.5
JVFloatLabeledTextField>= 0
Mantle~> 1.0
CocoaLumberjack= 2.3
JSQMessagesViewController>= 0
统计~> 3.0
MGSwipeTableCell>= 0
 


ZingleSDK 1.1.0

Zingle iOS SDK

CocoaPods Compatible Platform Twitter

概览

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 头文件

会话创建

  1. 要初始化一个联系类会话,需要一些数据。
  2. Zingle API 用户的令牌(这是您的 Zingle 仪表盘用户名)
  3. Zingle API 用户的密钥(这是您的 Zingle 仪表盘密码)
  4. 通道值,例如在自定义聊天类型中当前第三方应用用户的用户名

初始化

使用联系人选择和错误处理块

// 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资源概述 - 自动化