Queue-It iOS WebUI SDK
用于将 Queue-It 的虚拟候客室集成到以 Objective-C 或 Swift 编写的 iOS 应用程序中的库。
安装
开始之前,请从 GO Queue-it Platform 下载白皮书 Mobile App Integration。此白皮书包含完成成功集成所需的信息。
需求
在版本 2.12.X 中,QueueITEngine 将根据安装的 iOS 版本进行切换,因为旧的 UIWebView 已在 iOS 12 中被标记为弃用。如果 iOS 版本高于 10.0.0,则将使用较新的 WKWebView 而不是 UIWebView。
因此,2.12.X 版本的最低 iOS 版本为 8.3,这是引入了 WKWebView 的版本。在同一轮更新中,我们删除了仅针对 iPhone 的目标限制,因此库现在也可以与 iPad 一起使用。
从版本 2.13.0 开始,QueueITEngine 不再支持 UIWebView,而将仅使用 WKWebView。此外,最低支持的 iOS 版本已更新到 9.3。
3.0.0 版本引入了一些重大更改,因为 QueueITEngine 的接口已经被修改,现在 run
函数使用 NSError 模式返回错误,而不是抛出 NSException。
XCFramework
您可以手动添加在 releases 中发布的 XCFramework。
CocoaPods
CocoaPods 是用于 Cocoa 项目的依赖管理器。您可以使用以下命令安装它
gem install cocoapods
要使用 CocoaPods 将 SDK 集成到您的 Xcode 项目中,请指定 Podfile
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.3'
use_frameworks!
target '<Your Target Name>' do
pod 'QueueITLibrary', '~> 3.0.3'
end
然后,运行以下命令
pod install
用法
我们有一个包含演示应用的存储库 这里,但您可以在以下示例中了解如何使用此库的基本概念。
在此示例中,我们有一个需要使用 Queue-it 进行保护的 UITableViewController
。UIViewController
的头文件具有以下签名
#import <UIKit/UIKit.h>
#import "QueueITEngine.h"
@interface TopsTableViewController : UITableViewController<QueuePassedDelegate, QueueViewWillOpenDelegate, QueueDisabledDelegate, QueueITUnavailableDelegate, QueueViewClosedDelegate, QueueSessionRestartDelegate>
-(void)initAndRunQueueIt;
@end
QueueITEngine 类将打开一个网页来显示从提供的参数中找到的队列。
示例控制器的实现如下所示
-(void)initAndRunQueueIt
{
NSString* customerId = @"yourCustomerId"; // Required
NSString* waitingRoomIdOrAlias = @"yourWaitingRoomIdOrAlias"; // Required
NSString* layoutName = @"yourLayoutName"; // Optional (pass nil if no layout specified)
NSString* language = @"en-US"; // Optional (pass nil if no language specified)
self.engine = [[QueueITEngine alloc]initWithHost:self customerId:customerId eventOrAliasId:waitingRoomIdOrAlias layoutName:layoutName language:language];
[self.engine setViewDelay:5]; // Optional delay parameter you can specify (in case you want to inject some animation before Queue-It UIWebView or WKWebView will appear
self.engine.queuePassedDelegate = self; // Invoked once the user is passed the queue
self.engine.queueViewWillOpenDelegate = self; // Invoked to notify that Queue-It UIWebView or WKWebview will open
self.engine.queueDisabledDelegate = self; // Invoked to notify that queue is disabled
self.engine.queueITUnavailableDelegate = self; // Invoked in case QueueIT is unavailable (500 errors)
self.engine.queueUserExitedDelegate = self; // Invoked when user chooses to leave the queue
self.engine.queueViewClosedDelegate = self; // Invoked after the WebView is closed
self.engine.queueSessionRestartDelegate = self; // Invoked after user clicks on a link to restart the session. The link is 'queueit://restartSession'.
NSError* error = nil;
BOOL success = [self.engine run:&error];
/**
To enqueue with an enqueue-token or key use one of the following:
[self.engine runWithEnqueueKey:@"keyValue" error:&error];
[self.engine runWithEnqueueToken:@"tokenValue" error:&error];
**/
if (!success) {
if ([error code] == NetworkUnavailable) {
// Thrown when Queue-It detects no internet connectivity
NSLog(@"%ld", (long)[error code]);
NSLog(@"Network unavailable was caught in DetailsViewController");
NSLog(@"isRequestInProgress - %@", self.engine.isRequestInProgress ? @"YES" : @"NO");
}
else if ([error code] == RequestAlreadyInProgress) {
// Thrown when request to Queue-It has already been made and currently in progress. In general you can ignore this.
}
else {
NSLog(@"Unknown error was returned by QueueITEngine in DetailsViewController");
}
}
}
// This callback will be called when the user has been through the queue.
// Here you should store session information, so user will only be sent to queue again if the session has timed out.
-(void) notifyYourTurn:(QueuePassedInfo*) queuePassedInfo {
NSLog(@"You have been through the queue");
NSLog(@"QUEUE TOKEN: %@", queuePassedInfo.queueitToken);
}
// This callback will be called just before the webview (hosting the queue page) will be shown.
// Here you can change some relevant UI elements.
-(void) notifyQueueViewWillOpen {
NSLog(@"Queue will open");
}
// This callback will be called when the queue used (event alias ID) is in the 'disabled' state.
// Most likely the application should still function, but the queue's 'disabled' state can be changed at any time,
// so session handling is important.
-(void)notifyQueueDisabled:(QueueDisabledInfo* _Nullable) queueDisabledInfo {
NSLog(@"Queue is disabled");
}
// This callback will be called when the mobile application can't reach Queue-it's servers.
// Most likely because the mobile device has no internet connection.
// Here you decide if the application should function or not now that is has no queue-it protection.
-(void) notifyQueueITUnavailable:(NSString*) errorMessage {
NSLog(@"QueueIT is currently unavailable");
}
// This callback will be called after a user clicks a close link in the layout and the WebView closes.
// The close link is "queueit://close". Whenever the user navigates to this link, the SDK intercepts the navigation
// and closes the webview.
-(void)notifyViewClosed {
NSLog(@"The queue view was closed.")
}
// This callback will be called when the user clicks on a link to restart the session.
// The link is 'queueit://restartSession'. Whenever the user navigates to this link, the SDK intercepts the navigation,
// closes the WebView, clears the URL cache and calls this callback.
// In this callback you would normally call run/runWithToken/runWithKey in order to restart the queueing.
-(void) notifySessionRestart {
NSLog(@"Session was restarted");
[self initAndRunQueueIt];
}
作为应用程序开发者,您必须在应用程序存储中管理状态(用户是否曾之前排队)。
获取等候室状态
如果您使用的是版本 3.1.14
或更高版本,可以使用新的 QueueITWaitingRoomProvider
通过以下方法获取等候室状态:
TryPass
TryPassWithEnqueueToken
TryPassWithEnqueueKey
调用上述方法之一将触发成功时的 notifyProviderSuccess
回调,或在失败时的 notifyProviderFailure
回调。
使用来自 ProviderSuccessDelegate
的 notifyProviderQueueITUnavailable
时,将根据 isPassThrough
结果提供 QueueTryPassResult
。
true
表示QueueItToken
不为空,并且在QueueTryPassResult
中可以找到更多信息。false
表示等候室处于活动状态。您可以通过调用QueueITWaitingRoomView
的show
方法来展示等候室给访客,并需要提供queueUrl
和targetUrl
(了解更多信息)
向访客展示队列页面
如果您使用的是版本 3.1.14
或更高版本,则可用 QueueITWaitingRoomView
类。
当等候室正在排队等候访客时,每个访客必须至少访问一次。您可以通过使用 show
方法来做到这一点,您需要提供 queueUrl
和 targetUrl
,它们是由 QueueITWaitingRoomProvider
类的 notifyProviderSuccess
返回的,前提是等候室处于活动状态 (了解更多信息)
展示队列页面的示例代码
-(void)notifyProviderSuccess:(QueueTryPassResult* _Nonnull) queuePassResult {
[self.waitingRoomView show:queuePassResult.queueUrl targetUrl:queuePassResult.targetUrl];
}