Get Started in less than a minute

iOS Documentation


Installing the SDK with CocoaPods


The easiest way to get the SDK into your iOS project is to use CocoaPods. Install CocoaPods using

gem install cocoapods
If this is your first time using CocoaPods, run
pod setup
to create a local CocoaPods spec mirror. Create a file in your Xcode project called Podfile and add the following line:
pod 'Ringcaptcha'
In your Xcode project directory run
pod install
to download and install the library. CocoaPods will create a new Xcode workspace. Remember to open up this workspace in Xcode and not your project.


Installing the SDK Manually


To embed the SDK just drag & drop the iOS SDK library into your libs folder in your XCode project.

After adding it, make sure that in every target that the SDK will be included you link it to Ringcaptcha.framework and CoreTelephony.framework.


Simple widget

Also Include under your Project "Build Settings", "Linking" -> "Other Linker Flags" the following value: "-ObjC -all_load".


Simple widget

On each file you will be including RingCaptcha, make sure you import the header file.

#import <Ringcaptcha/Ringcaptcha.h>

Download iOS SDK now


Launching an Onboarding widget

To use the one screen onboarding process bundled into the SDK with the option of onboarding automatically from a website PIN, all you need to do is call the Ringcaptcha verifyOnboardWithAppKey method as described below from any user action like starting the app for the first time when is not logged-in.


Simple widget Simple widget Simple widget

On your ViewController, in the method hooked to the user event add the following line of code.

[Ringcaptcha verifyOnboardWithAppKey:@"{{ app_key }}" andSecretKey:@"{{ secret_key }}" inViewController:self delegate:nil success: ^(RingcaptchaVerification *verification) {
	NSLog(@"Successful onboarding");
} cancel:^(RingcaptchaVerification *verification) {
	NSLog(@"Onboarding cancelled");
}];

You can choose to implement the success and cancel blocks or implement the following delegate methods that will be called once the user exits the verification widget either successfully or cancelled:

- (void) didFinishPhoneNumberVerification: (RingcaptchaVerification*) verification;
- (void) didFinishPhoneNumberVerificationWithCancel: (RingcaptchaVerification*) verification;

In the event the widget does not find an open session or is unable to attribute the onboarding process to a user, it will automatically start the verification process by asking the phone number to the user to send the PIN code to.


Launching a Verification widget

To use the two screen verification process bundled into the SDK, all you need to do is call the Ringcaptcha verifyPhoneNumberWithAppKey method as described below from any user action like tapping a button for Verify your Phone Number.


Simple widget Simple widget Simple widget

On your ViewController, in the method hooked to the user event add the following line of code.

[Ringcaptcha verifyPhoneNumberWithAppKey:@"{{ app_key }}" andSecretKey:@"{{ secret_key }}" inViewController:self delegate:nil success: ^(RingcaptchaVerification *verification) {
	NSLog(@"Successful onboarding");
} cancel:^(RingcaptchaVerification *verification) {
	NSLog(@"Onboarding cancelled");
}];

And implement the following delegate methods that will be called once the user exits the verification widget either successfully or cancelled:

- (void) didFinishPhoneNumberVerification: (RingcaptchaVerification*) verification;
- (void) didFinishPhoneNumberVerificationWithCancel: (RingcaptchaVerification*) verification;

Implementing SMS Deep-Linking

Every SMS link sent by RingCaptcha will deep-link the user to either the application store for onboarding or the installed application for verification. Ringcaptcha link will redirect to the configured scheme and host for the app whenever a user opens the SMS link in their browser. In order to implement the custom sceheme in your app to populate automatically the PIN code, you will need to create a handler for the custom scheme and set URL type like the following:

scheme://ringcaptcha/verified?token={TOKEN}&pin={PIN_CODE}

In your project file, in the Info section, under in the URL types add the app identifier and URL scheme. Then just add a similar code to handle the custom-scheme to your AppDelegate.m file:

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {
   
    NSMutableDictionary *params = [[NSMutableDictionary alloc] init];
    NSArray *elts = [[url query] componentsSeparatedByString:@"&"];
    for(int i = 0;i<[elts count];i++) {
        NSArray *pars = [[elts objectAtIndex:i] componentsSeparatedByString:@"="];
        [params setObject:[pars objectAtIndex:1] forKey:[pars objectAtIndex:0]];
    }
    
    if([params objectForKey:@"pin"] != nil) {
        
        UIWindow *window=[UIApplication sharedApplication].keyWindow;
        UIViewController* mainController = (UIViewController*) window.rootViewController;
        
        NSString* pin = [params objectForKey:@"pin"];
        [Ringcaptcha verifyOnboardWithAppKeyAndPinCode:@"{{ app_key }}"
            andSecretKey:@"{{ secret_key }}"
            andPin:pin
            inViewController:mainController
            delegate: nil
            success:^(RingcaptchaVerification *verification) {
                NSLog(@"Verification process ended successfully? %@", verification.verificationId);
                NSLog(@"Verification process ended successfully? %d", verification.verificationSuccessful);
                NSLog(@"Verification process ended successfully? %@", verification.phoneNumber);
                NSLog(@"Verification process ended successfully? %@", verification.errorDescription);
            }
            cancel:^(RingcaptchaVerification *verification) {
                NSLog(@"Verification process cancelled? %d", verification.verificationSuccessful);
            }
         ];
    }
    return YES;
}
        

Implementing your own UI


Should you be interested on using your own UI and calling the backend of RingCaptcha, you can do so by calling the API methods bundled into the SDK as described below.

RingcaptchaAPI* controller = [[RingcaptchaAPI alloc] initWithAppKey:@”{{ app_key }}” andApiKey:@”{{ secret_key }}”];

To Request an SMS or VOICE PIN code to be send to the phone number

[controller sendCaptchaCodeToNumber:@”PHONE_NUMBER” withService:SMS delegate:self];

To Verify the PIN code entered by the user

[controller verifyCaptchaWithCode:@”PIN_CODE” delegate:self];

Lookup an existing session for this device for automatic onboarding

[controller onboardDelegate: self];

And implement the following delegate methods that will be called when each API call finishes.

This method is called when the communication with the server API was established correctly and a response received from the server for sending the one-time code to the phone number requested via the communication method estipulated in the app key.

RingcaptchaResponse object will be populated with the data received from the server such as: token, serviceType (e.g.: SMS, VOICE), status (e.g.: SUCCESS, ERROR), errorMessage (e.g.: ERROR_INVALID_PIN_CODE, etc), phone (e.g.: +123456789), transactionId (unique id for this verification transaction) and timeout (used when attempts have been blocked for X time)

- (void) didFinishCodeRequest: (RingcaptchaResponse*) rsp;

This method is called when there is a communication error with the server API for sending the one-time code to the phone number requested via the communication method estipulated in the app key.

NSError object will be populated with the NSLocalizedDescriptionKey and NSUnderlyingErrorKey with their corresponding exceptions user info and description.

- (void) didFinishCodeRequestWithError: (NSError*) err;

This method is called when the communication with the server API was established correctly and a response received from the server for checking the one-time code to the phone number requested via the communication method estipulated in the app key.

RingcaptchaResponse object will be populated with the status data received from the server such as: status (e.g.: SUCCESS, ERROR), errorMessage (e.g.: ERROR_INVALID_PIN_CODE, etc) and timeout (used when attempts have been blocked for X time)

- (void) didFinishCheckRequest: (RingcaptchaResponse*) rsp;

This method is called when there is a communication error with the server API for checking the one-time code to the phone number requested via the communication method estipulated in the app key and secret key/api key.

NSError object will be populated with the NSLocalizedDescriptionKey and NSUnderlyingErrorKey with their corresponding exceptions user info and description.

- (void) didFinishCheckRequestWithError: (NSError*) err;

This method is called when the communication with the server API was established correctly and a response received from the server for verifying the one-time code to the phone number requested via the communication method estipulated in the app key.

RingcaptchaResponse object will be populated with the data received from the server such as: token, serviceType (e.g.: SMS, VOICE), status (e.g.: NEW, SUCCESS, ERROR), errorMessage (e.g.: ERROR_INVALID_PIN_CODE, etc), phone (e.g.: +123456789), transactionId (unique id for this verification transaction) and timeout (used when attempts have been blocked for X time)

- (void) didFinishVerifyRequest: (RingcaptchaResponse*) rsp;

This method is called when there is a communication error with the server API for verifying the one-time code to the phone number requested via the communication method estipulated in the app key and secret key.

NSError object will be populated with the NSLocalizedDescriptionKey and NSUnderlyingErrorKey with their corresponding exceptions user info and description.

- (void) didFinishVerifyRequestWithError: (NSError*) err;

This method is called when the API successfully found open sessions for this device

NSError object will be populated with the NSLocalizedDescriptionKey and NSUnderlyingErrorKey with their corresponding exceptions user info and description.

- (void) didFinishOnBoardRequest: (RingcaptchaResponse* ) rsp;

This method is called when the API could not find an open onboard session for this device

NSError object will be populated with the NSLocalizedDescriptionKey and NSUnderlyingErrorKey with their corresponding exceptions user info and description.

- (void) didFinishOnBoardRequestNew:(RingcaptchaResponse)rsp;

This method is called when there is a communication error with the server API for onboarding

NSError object will be populated with the NSLocalizedDescriptionKey and NSUnderlyingErrorKey with their corresponding exceptions user info and description.

- (void) didFinishOnBoardRequestWithError: (NSError*) err;