VerificationSDK

The VerificationSDK allows you to retrieve a code directly from UNiDAYS. The SDK will handle retrieving a code using your user's UNiDAYS credentials and then return it to your app.

The VerificationSDK supports the retrieval of two different code types:

• Coded: Communicates with the UNiDAYS native app or opens a webview to verify the users UNiDAYS credentials, on success an object is returned containing perk discount code information

• Codeless: Opens a webview which is then used to verify the user UNiDAYS credentials, on success an object is returned that contains various user attributes

Installation

The UNiDAYS Verification SDK is available through CocoaPods or Carthage.

CocoaPods

CocoaPods is a dependency manager for Cocoa projects.

To integrate the UNiDAYS Verification SDK into your Xcode project using CocoaPods, specify it in your 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

Then, run the following command:

$ pod install

Carthage

Carthage is intended to be the simplest way to add frameworks to your Cocoa application.

To add the UNiDAYS Verification SDK framework into your Xcode project using Carthage, specify it in your Cartfile:

github "MyUNiDAYS/VerificationSDK.iOS"

Then, run the following command:

$ carthage update --platform iOS

This builds a binary of the UNiDAYS Verification SDK framework that then needs to be added to Build Phases -> Link Binary With Libraries within your project.

Usage

Example project

There are two example projects included in this repository, for both Swift and Objective-C.

Add UNiDAYS to your own project

1. Make sure you define a custom scheme for your application

Info.plist -> URL types -> URL Schemes -> your-custom-scheme

It's very possible you already have one set but you can add a new one specifically for the SDK.

2. Send your custom scheme to UNiDAYS.

Email your custom scheme to your UNiDAYS account manager. We use the custom scheme to validate your integration with UNiDAYS.

3. Add the Unidays SDK query scheme to the Info.Plist

Info.plist -> LSApplicationQueriesSchemes -> unidays-sdk

4. Setup the Unidays SDK

Within your didFinishLaunchingWithOptions method in the applications AppDelegate, setup the SDK with your customerID:

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. Get a code using the VerificationSDK

The VerificationSDK supports the retrieval of two different code types. Implementation of how to get a code for both of these is discussed below.

Coded

Call the Unidays SDK to get a coded response and create a success and error handler

Where the variable response will contain a number of parameters whose contents are linked to your code type in the UNiDAYS system.

Coded supports two different behaviour modes, webviewOnly - where user Verification occurs inside the app using a webview or nativeAppOnly - where Verification occurs by interacting with the native UNiDAYS (this must be installed on the users device otherwise they are prompted to install the UNiDAYS app). Please set the required behaviourMode on the UnidaysConfig instance during setup.

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

Call the Unidays SDK to get a codeless response and create a success and error handler

Where the variable response will contain a dictionary of user attributes that have been predefined during partner setup within the UNiDAYS system.

Codeless only supports the webviewOnly behaviour mode, Verification will happen inside that app via a 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 requires the customerApiKey to be set on the UnidaysConfig object passed in during setup. See step 4 above for details.

6. Listen for callbacks from the UNiDAYS app

Within your application(app:open:options:) method in the applications AppDelegate, listen for incoming callbacks:

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;
}

Error Codes

If code retrieval fails the error handler will be provided an error response, listed below are the error codes you might face.

Debugging and Testing

The VerificationSDK does support a sandbox environment which allows you test different code types without having a verified user or a full integration.

You are not required to have fully integrated with UNiDAYS in order for this step to work.

1. Enable debug mode on the 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
}

Behaviour Mode: Native Only

• You will require a physical device with the UNiDAYS native app installed.

Behaviour Mode: Webview Only

• In your apps Info.plist file make sure that the custom scheme is set to sampleapp this will allow the webview to return the app on a successful response. Please follow this step if you are unsure how to set your apps custom scheme.

2. Call the UNiDAYS SDK

When you call the UNiDAYS SDK as described in the usage section, you will see the following screen open in the native UNiDAYS app or a webview:

Here you can select from a list of stock responses in order to test your integration quickly. It will also allow to try different code types if you should wish to change them in the future.

3. Submit or edit your response

You can either submit one of the pre-defined responses or edit one to suit your own needs.

Either way, using the pre-defined responses or editing one and clicking submit will result in the response being sent back to your app.

License

VerificationSDK is available under a license. See the LICENSE file for more info.