QueueITLibrary 3.4.2

QueueITLibrary 3.4.2

测试已测试
Lang语言 Obj-CObjective C
许可证 MIT
发布最后发布2024年4月

由以下人员维护:Alexander YaremchukQueueITLibraryQueueITLibrary



  • Queue-It

CocoaPods

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 进行保护的 UITableViewControllerUIViewController 的头文件具有以下签名

#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 回调。

使用来自 ProviderSuccessDelegatenotifyProviderQueueITUnavailable 时,将根据 isPassThrough 结果提供 QueueTryPassResult

  • true 表示 QueueItToken 不为空,并且在 QueueTryPassResult 中可以找到更多信息。
  • false 表示等候室处于活动状态。您可以通过调用 QueueITWaitingRoomViewshow 方法来展示等候室给访客,并需要提供 queueUrltargetUrl了解更多信息

向访客展示队列页面

如果您使用的是版本 3.1.14 或更高版本,则可用 QueueITWaitingRoomView 类。

当等候室正在排队等候访客时,每个访客必须至少访问一次。您可以通过使用 show 方法来做到这一点,您需要提供 queueUrltargetUrl,它们是由 QueueITWaitingRoomProvider 类的 notifyProviderSuccess 返回的,前提是等候室处于活动状态 (了解更多信息

展示队列页面的示例代码

-(void)notifyProviderSuccess:(QueueTryPassResult* _Nonnull) queuePassResult {   
   [self.waitingRoomView show:queuePassResult.queueUrl targetUrl:queuePassResult.targetUrl];
}

生命周期图

App Integration Flow