UnidaysVerificationSDK 0.3.2

UnidaysVerificationSDK 0.3.2

Jacob Hughes 维护。



  • MyUNiDAYS Ltd.

VerificationSDK

VerificationSDK 允许您直接从 UNiDAYS 获取代码。SDK 将使用您的用户的 UNiDAYS 凭证来获取代码,然后将其返回到您的应用程序。

VerificationSDK 支持检索两种不同的代码类型

  • Coded:与 UNiDAYS 原生应用通信或打开 webview 验证用户 UNiDAYS 凭证,成功后返回包含优惠代码信息的对象

  • Codeless:打开 webview,然后使用它来验证用户 UNiDAYS 凭证,成功后返回包含各种用户属性的对象

安装

UNiDAYS Verification SDK 可以通过 CocoaPodsCarthage 获取。

CocoaPods

CocoaPods 是 Cocoa 项目的依赖管理器。

要使用 CocoaPods 将 UNiDAYS Verification SDK 集成到您的 Xcode 项目中,请在您的 Podfile 中指定它

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'UnidaysVerificationSDK', '0.3.2'
end

然后,运行以下命令

$ pod install

Carthage

Carthage 是用于将框架添加到您的 Cocoa 应用程序的最简单方式。

要使用 Carthage 将 UNiDAYS 验证 SDK 框架添加到您的 Xcode 项目中,请在您的 Cartfile 中指定它。

github "MyUNiDAYS/VerificationSDK.iOS"

然后,运行以下命令

$ carthage update --platform iOS

这将构建一个 UNiDAYS 验证 SDK 框架的二进制文件,然后需要将其添加到您的项目中“构建阶段”下的“链接二进制库”。

使用方法

示例项目

此存储库包含两个示例项目,适用于 Swift 和 Objective-C。

将 UNiDAYS 添加到您自己的项目

1. 确保您为应用程序定义了自定义方案

Info.plist -> URL 类型 -> URL 方案 -> 您的自定义方案

UNiDAYS Custom Scheme

您可能已经有一个设置,但仍可以为 SDK 添加一个新的。

2. 将您的自定义方案发送给 UNiDAYS。

将您自定义方案通过电子邮件发送给您的 UNiDAYS 账户经理。我们使用自定义方案来验证与 UNiDAYS 的集成。

3. 将Unidays SDK查询方案添加到Info.Plist文件中

Info.plist -> LSApplicationQueriesSchemes -> unidays-sdk

UNiDAYS Custom Scheme

4. 设置Unidays SDK

在应用的AppDelegate中的didFinishLaunchingWithOptions方法内,使用客户ID设置SDK

Swift
import UnidaysVerificationSDK

// ...

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    // Override point for customization after application launch.

    //This is the custom URL scheme for your app
    let scheme = "your_custom_scheme"

    // This is subdomain of the perk you want to get a code for. If in doubt what this is speak to your UNiDAYS representative.
    let subdomain = "partner_store"

    let settings = UnidaysConfig(scheme: scheme, customerSubdomain: subdomain)

    // Set the customer API key on the UnidaysConfig object - this is only required when requesting the codeless code type.
    // If you are not using the method getCodeless() you can remove this line. See step 5 (Codeless) for more details.
    settings.customerApiKey = "your_secret_api_key"
    
    // Set the behaviourMode of the VerificationSDK. This is not a required setting, if not set this will default to webviewOnly.
    // The behaviourMode dictates the type of Verification flow that occurs when using the SDK, there are two options `webviewOnly` and `nativeAppOnly`.
    // This setting is discussed  in further detail in step 5.
    settings.behaviourMode = .webviewOnly

    do {
        try UnidaysSDK.sharedInstance.setup(settings: settings)
    } catch {
        switch error {
            case UnidaysError.URLSchemesNotSet:
            // The scheme you've provided is not available in your info.plist we will not be able to return the user to your app correctly.
            break
            default:
            break
        }
    }

    return true
}
Objective-C
#import <UnidaysSDK/UnidaysSDK-Swift.h>

// ...

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    //This is the custom URL scheme for your app
    NSString *scheme = @"your_custom_scheme";
    
     // This is subdomain of the perk you want to get a code for. If in doubt what this is speak to your UNiDAYS representative.
    NSString *subdomain = @"partner_store";
    
    UnidaysConfig *config = [[UnidaysConfig alloc] initWithScheme:scheme customerSubdomain:subdomain];
    
    // Set the customer API key on the UnidaysConfig object - this is only required when requesting the codeless code type.
    // If you are not using the method getCodeless() you can remove this line. See step 5 (Codeless) for more details.
    [config setCustomerApiKey:@"your_secret_api_key"];
    
    NSError *error;
    [[UnidaysSDK sharedInstance] setupWithSettings:config error: &error];
    
    if(error.code == UnidaysErrorURLSchemesNotSet) {
        // The scheme you've provided is not available in your info.plist we will not be able to return the user to your app correctly.
    }
    
    return YES;
}

5. 使用VerificationSDK获取代码

VerificationSDK支持检索两种不同的代码类型。下面讨论了如何实现获取这两种代码的方案。

Coded

调用Unidays SDK以获取编码响应并创建成功和错误处理程序

其中变量response将包含多个参数,其内容与UNiDAYS系统中的代码类型相关。

Coded支持两种不同的行为模式,webviewOnly - 在这种模式下,用户验证在应用程序内部使用webview进行,或者nativeAppOnly - 在这种模式下,通过与原生UNiDAYS交互进行验证(必须在用户的设备上安装,否则将提示安装UNiDAYS应用程序)。请在设置期间在UnidaysConfig实例上设置所需的behaviourMode。

Swift
func getCoded() {
    // Perks have a channel. Either instore or online if your not sure which you should be using then speak to your unidays representative.
    let channel = UnidaysSDK.Channel.Online

    UnidaysSDK.sharedInstance.getCoded(channel: channel), success: { (response)
        // Handle the code
        let code = response.code
        // Some codes may return an image url which you can use to show a barcode or QR code where relevant.
        let imageUrl = response.imageUrl
    }, error: { (error) in
        // Handle error as you deem appropriate
    }
}
Objective-C
- (void)getCoded {

    UnidaysChannel channel = UnidaysChannelOnline

    [[UnidaysSDK sharedInstance] getCodeWithChannel:channel   withSuccessHandler:^(id<CodedResultProtocol> _Nonnull response) {
        // Handle the coded response
         NSString *code = response.code;
    } withErrorHandler:^(NSError * _Nonnull error) {
        // Handle error as you deem appropriate
    }];
 }

Codeless

调用Unidays SDK获取无代码响应并创建成功和错误处理程序

其中变量response将包含用户属性字典,这些属性在UNiDAYS系统内部的合作伙伴设置期间已预先定义。

Codeless仅支持webviewOnly行为模式,验证将在此webview中通过应用程序内部完成。

Swift
func getCodeless() {

    UnidaysSDK.sharedInstance.getCodeless(success: { (response)
        // Handle the codeless response
        let userAttributes = response.attributes
    }, error: { (error) in
        // Handle error has you deem appropriate
    }
}
Objective-C
- (void)getCodeless {

    [[UnidaysSDK sharedInstance] getCodelessWithSuccessHandler:^(id<CodelessResultProtocol> _Nonnull response) {
        // Handle codeless response
        NSString *attributes = response.attributes;
    } withErrorHandler:^(NSError * _Nonnull error) {
        // Handle error as you deem appropriate
    }];
 }
   

Codeless要求在设置期间传递给UnidaysConfig对象的代码customerApiKey必须设置。关于详细信息,请参阅上面的步骤4。

6. 监听 UNiDAYS 应用程序的回调

在应用程序的 AppDelegate 中的 application(app:open:options:) 方法中,监听传入的回调

Swift
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    if UnidaysSDK.sharedInstance.process(url: url as NSURL) {
        // The UnidaysSDK handles this link and returns it to either your error handler or the success handler
        return true
    }
    return false
}
Objective-C
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    if ([[UnidaysSDK sharedInstance] processWithUrl:url]) {
        return true;
    }
    return false;
}

错误代码

如果代码检索失败,错误处理器将提供一个错误响应,以下列出了您可能遇到的错误代码。

代码 信息 描述
500 服务器错误 请求失败是因为内部服务器错误
1001 权限被拒绝 用户已拒绝权限以获取代码
1002 无效的 URL 签名 提供的 URL 签名与使用客户 API 密钥生成的签名不匹配
1003 成功响应中无参数 成功响应中未返回参数
1004 不支持的编码 不支持的响应编码
1005 无法解析响应 无法将代码响应解析成有用的内容
1006 未处理的 URL 响应 URL 方案有效,但路径未知
1007 未设置 URL 方案 未在应用程序的 info.plist 文件中设置 URL 方案
1008 设置不完整 未使用 UnidaysConfig 对象调用设置函数
1009 无法生成请求 URL 无法构建获取代码所需的请求 URL
1010 不支持的模式 如果 SDK 有两种代码请求类型 Coded 或 Codeless,如果某种类型不受支持,则返回此错误
1011 无法打开 webview 无法打开对于 Codeless 实现所需的 webview
1012 用户关闭了 webview 用户关闭了 webview,取消了获取 Codeless 请求
1013 无法加载 无法加载外部资源
1014 用户验证正在进行 用户正在等待 UNiDAYS 验证
1015 用户未授权 用户未授权检索此代码
1016 网络错误 在尝试获取代码时出现网络错误
1017 奖励不可用 所需的奖励当前不可用
1018 意外错误 出现了意外错误
1019 属性不可用 请求的属性当前不可用

调试和测试

VerificationSDK支持沙箱环境,这允许您在不拥有经验证用户或完全集成的情况下测试不同类型的代码。

您无需完全集成了UNiDAYS,才能使此步骤正常工作。

1. 在SDK上启用调试模式

Swift
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

    var settings = UnidaysConfig(scheme: scheme, customerSubdomain: subdomain)
    // Make sure you switch this back off in production
    settings.isDebugEnabled = true

    // Continue setup as before
}
Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    NSString *scheme = @"your_custom_scheme";
    NSString *subdomain = @"partner_store";
    
    UnidaysConfig *config = [[UnidaysConfig alloc] initWithScheme:scheme customerSubdomain:subdomain];
    // Make sure you switch this back off in production
    [config setIsDebugEnabled:true];
    
    // Continue setup as before
}
行为模式:仅限原生
  • 您需要一个已安装UNiDAYS原生应用的物理设备。
行为模式:仅限Web视图
  • 在您应用的 Info.plist 文件中,请确保自定义方案设置为 sampleapp。这将允许在成功响应后,webview 能够返回应用程序。如果您不确定如何设置您应用的自定义方案,请参考此 步骤

2. 调用 UNiDAYS SDK

当您按使用说明调用 UNiDAYS SDK 时,您将在原生 UNiDAYS 应用或 webview 中看到以下屏幕。

UNiDAYS Debug list screen

您可以从一系列库存响应中选择,以快速测试集成。如果您将来想要更改它们,它还可以允许尝试不同的代码类型。

3. 提交或编辑您的响应

您可以选择提交其中一个预定义的响应,或者编辑一个以满足您的需求。

UNiDAYS Debug list screen

无论哪种方式,使用预定义的响应或编辑一个后点击提交,都会将响应发回您的应用程序。

许可证

VerificationSDK 在许可证下提供。有关更多信息,请参阅 LICENSE 文件。