vouch Docs

Under Development: This SDK is currently in development. Documentation and API may change. For production use, please contact our team.

Overview

The vouch iOS SDK provides an Objective-C compatible bridge (VouchSDKBridge) for integrating verification flows into Objective-C applications or frameworks like React Native. The bridge wraps the native Swift SDK and exposes a UIKit-based interface.

Initialization

The SDK bridge should be initialized at the application level and kept alive for the duration of your app's lifecycle. This ensures proper state management and allows multiple verification requests throughout the user's session.

Recommended initialization pattern:

#import <VouchSDK/VouchSDK-Swift.h>

@interface AppDelegate ()
@property (nonatomic, strong) VouchSDKBridge *vouchSDK;
@end

@implementation AppDelegate

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

    self.vouchSDK = [[VouchSDKBridge alloc] initWithCustomerId:@"CUSTOMER_ID"];
    return YES;
}

@end

Important: Keep the SDK bridge instance alive for the entire lifecycle of your application. Creating multiple instances may lead to unexpected behavior.

Requesting a Verification

To initiate a verification flow, call the start method on your SDK bridge instance. This method returns a UIViewController that can be presented modally, pushed onto a navigation stack, or embedded in your view hierarchy.

Basic usage example:

NSDictionary *inputs = @{
    @"INPUT1_NAME": @"INPUT1_VALUE",
    @"INPUT2_NAME": @"INPUT2_VALUE",
    @"INPUT3_NAME": @"INPUT3_VALUE"
};

UIViewController *vouchVC = [self.vouchSDK startWithDataSourceId:@"DATA_SOURCE_ID"
                                                      webhookUrl:@"WEBHOOK_URL"
                                                          inputs:inputs
                                                      completion:^(VouchSuccessObjC *success, VouchErrorObjC *error) {
    if (success) {
        NSLog(@"Proof id: %@", success.proofId);
    } else if (error) {
        NSLog(@"Proof with id failed: %@, reason: %ld", error.proofId, (long)error.reason);
    }

    [self dismissViewControllerAnimated:YES completion:nil];
}];

[self presentViewController:vouchVC animated:YES completion:nil];

Parameters

Initializing the SDK bridge requires your customerId.

The start method accepts the following parameters. For detailed documentation on dataSourceId, webhookUrl, and inputs, see the Vouch URL Parameters section.

dataSourceId

Type: NSString *

The identifier for the data source to use for verification.

webhookUrl

Type: NSString *

The URL where verification results will be sent.

inputs

Type: NSDictionary<NSString *, NSString *> * (nullable)

A dictionary of input parameters required by the data source. Pass nil if no inputs are required.

completion

Type: void (^)(VouchSuccessObjC *success, VouchErrorObjC *error)

A completion block that is called when the verification process completes. Either success or error will be non-nil, but never both.

Success case (VouchSuccessObjC):

proofId: The unique identifier of the generated proof

Error case (VouchErrorObjC):

proofId: The unique identifier of the failed proof request
reason: A VouchErrorReasonObjC enum value describing why the verification failed

Error Handling

The SDK provides comprehensive error handling through the completion block. All error cases include both a proofId and a specific reason to help diagnose issues.

Error Reasons

The VouchErrorReasonObjC enum provides the following failure reasons:

Reason	Value	Description
`VouchErrorReasonObjCDataSourceOrCustomerNotFound`	0	The provided `dataSourceId` or `customerId` does not match any known entity in the vouch system. Verify your IDs are correct.
`VouchErrorReasonObjCOutdatedVersion`	1	A newer version of the SDK is available and must be downloaded. Update the SDK to the latest version.
`VouchErrorReasonObjCCreatingProofRequestFailed`	2	The SDK was unable to create the proof request. This may indicate a network or configuration issue.
`VouchErrorReasonObjCBackgroundTimeout`	3	The user kept the application in the background for too long during verification. The app must remain active for the entire verification process.
`VouchErrorReasonObjCRequestTooLarge`	4	The captured request exceeds size limits and cannot be notarized. Consider using a different data source or reducing the scope of verification.
`VouchErrorReasonObjCDataSourceMisconfigured`	5	The selected data source contains unsupported configuration. Contact support or try a different data source.
`VouchErrorReasonObjCProvingFailed`	6	The SDK failed to notarize the request. This may indicate a technical issue with the verification process.
`VouchErrorReasonObjCProofUploadFailed`	7	The SDK failed to upload the proof to the vouch server. Check network connectivity and retry.
`VouchErrorReasonObjCAttachmentReuploadFailed`	8	The SDK failed to upload attachments to your server. Verify your webhook endpoint is accessible and properly configured.
`VouchErrorReasonObjCProofIdTaken`	9	A proof with the same ID already exists on the vouch server. Ensure proof IDs are unique.
`VouchErrorReasonObjCNetworkConnectionLost`	10	The device lost internet connection during verification. Ensure stable connectivity and retry.

Example error handling:

UIViewController *vouchVC = [self.vouchSDK startWithDataSourceId:@"DATA_SOURCE_ID"
                                                      webhookUrl:@"WEBHOOK_URL"
                                                          inputs:nil
                                                      completion:^(VouchSuccessObjC *success, VouchErrorObjC *error) {
    if (success) {
        NSLog(@"Verification successful! Proof ID: %@", success.proofId);
        // Handle success
    } else if (error) {
        NSLog(@"Verification failed. Proof ID: %@", error.proofId);

        switch (error.reason) {
            case VouchErrorReasonObjCNetworkConnectionLost:
                NSLog(@"Please check your internet connection and try again.");
                break;
            case VouchErrorReasonObjCBackgroundTimeout:
                NSLog(@"Please keep the app in the foreground during verification.");
                break;
            case VouchErrorReasonObjCOutdatedVersion:
                NSLog(@"Please update the app to continue.");
                break;
            default:
                NSLog(@"Error: %@", error.localizedDescription);
                break;
        }
    }

    [self dismissViewControllerAnimated:YES completion:nil];
}];

Best Practice: Always handle both success and error cases in your completion block. Log the proofId for debugging and user support purposes.

Version checking (iOS 14-16.3)

VouchSDK functionalities are disabled on iOS 14-16.3. To check if your current iOS version is supported:

if ([VouchSDK isSupported]) {
    // Initialize and start
} else {
    // Show an error
}

Usage (Objective-C)