Get Started in less than a minute

Installing the HTML & JS Widget


To embed the widget on your website, simply paste the following code at the end of the HTML section right before the closing <body> tag:

<script type='text/javascript' charset='UTF-8' src="//cdn.ringcaptcha.com/widget/v2/bundle.min.js"></script>

Please note that if you decide to include the bundle.min.js with SSL you will need to ensure you have a valid certificate running on the server.

Launching an Onboarding widget

To use the one screen onboarding process bundled into widget to send an SMS PIN code with a link to download your app automatically deeplinked to the Android and iOS Stores you will need to include the data-mode parameter into the div tag with value "onboarding".


Simple widget Simple widget

For every different MOBILE app you want the user to onboard into, add the following <div> with a unique ID. The widget will be rendered in the spot where this <div> is placed.

<div id="xyz" data-widget data-app="{{ app_key }}" data-locale="en" data-mode="onboarding"></div>

Launching a Verification widget

To use the three-step screen verification process bundled into widget to send an SMS PIN code with a unique code to verify the user posseses a valid phone number just don't include the data-mode parameter into the div tag or set the value to "verification".


Simple widget Simple widget Simple widget

For every different phone number that you would like to verify, add the following <div> with a unique ID. The widget will be rendered in the spot where this <div> is placed.

<div id="xyz" data-widget data-app="{{ app_key }}" data-locale="en" data-mode="verification"></div>

Verifying the PIN code


To ensure the transaction is authentic you need to make a call to RingCaptcha in order to validate the PIN code inserted by the user. This step is done at the server level, on your website page that submits the form where the widget is placed, capture the parameters sent by the widget phone,pin code and token and send them to our servers via any language library listed below.

<?php

require_once __DIR__.'/vendor/autoload.php';

$appKey = "{{ app_key }}"; //Please safeguard this key
$secretKey = "{{ secret_key }}"; //Please safeguard this key
$lib = new Ringcaptcha($appKey, $secretKey);
$lib->setSecure(true); //Configure to send the request using SSL.

if ( $lib->isValid($_POST["ringcaptcha_pin_code"], $_POST["ringcaptcha_session_id"]) ) {
	// Successfull verification flow.
	$user_phone = $lib->getPhoneNumber(); //retrieve phone number
	$geo_located = $lib->isGeoLocated(); //retrieve whether its been geo located or not
	$id = $lib->getId(); //retrieve and store transaction id for reconciliation purposes
} else {
	die ("RingCaptcha verification failed. Reason: " . $lib->getMessage());
}
?>

View on GitHub

from lib.Ringcaptcha import Ringcaptcha

lib = Ringcaptcha('{{ app_key }}','{{ secret_key }}')
if lib.isValid(pinCode,token):
    print 'Is valid ' + lib.getPhoneNumer() + ' ' + lib.isGeoLocated() + ' with id: ' + lib.getId()
else:
    print 'Invalid ' + lib.getMessage()

View on GitHub

require 'ringcaptcha'

def valid_rc
  rcap = RingCaptcha::RingCaptcha.new('{{ app_key }}','{{ secret_key }}')
  @validation = rcap.validate_pin_code(params[:pin_code], params[:token])
  if @rcap_valid
    puts "Is valid #{@rcap_valid.phone_number} #{@rcap_valid.geolocation} with id: #{@rcap_valid.transaction_id}"
  else
    puts "Invalid #{@rcap_valid.message}"
  end

  render json: @validation
end

View on GitHub

var ringcaptcha = require('RingCaptcha')

ringcaptcha.verify(code,token, function(response){
	if (response.status == "SUCCESS") {
	  //successful verification
	  //response.phone_number
	} else {
	  //error
	}
})

View on GitHub

Sorry you can't find your library, but remember you are allowed to write your own. Follow the docs for the API


Customizing the HTML & JS Widget


For every data-widget added into your HTML, a unique widget will be created. Each of these widgets will emit events per action upon the container for which you can listen to and act accordingly. You can use these events to customise most of the behavior of the widgets. Make sure all the javascript added to customise the widget is positioned after the bundle.min.js javascript reference is set.

The complete list of events are:

  • ready.rc.widget: when the widget is at the phone input screen

  • retry.rc.widget: when the user requests a PIN retry

  • fallback.rc.widget: when the user clicks on the fallback option of "call me"

  • max_validations.rc.widget: when the user tried the maximum number of PIN code validations (set to 10 for now)

  • verified.rc.widget: when the user successfully enters the correct PIN code

  • error.rc.widget: whenever an error happens. The details will be found on the error variable

  • pending.rc.widget: when the widget is at the PIN code screen


Adding Voice option to the widget

In order to add a VOICE call as an option to the widget, you will need your account configured in Rockstar mode and add the following <data-type> property in the widget tag. The available options are "sms" for only allowing SMS, "voice" only for voice calls and "dual" for allowing either SMS or Voice calls.

<div id="xyz" data-widget data-app="{{ app_key }}" data-mode="verification" data-type="dual" ></div>

Customizing the widget copy texts

To have the widget render different copy texts, you will need to over-write the default options with this javascript. You only need to add the ones that you want to change, the rest will automatically default to the ones provided by RingCaptcha. Right before the RingCaptcha bundle.min.js is set add the following code:

<script>
var RingCaptchaLocale = { en: { "onboarding.send": "Get MyApp" } };
</script>

Download the complete list of texts here


Displaying the widget only for the enabled countries


To automacatically have the widget show or hide based on the country of the IP address of the user and the enabled countries in Ringcaptcha, add the following property on the <div> tag.

<div id="xyz" data-widget data-app="{{ app_key }}" data-display-always="false"></div>

Displaying the widget in a fixed language


The data-locale option will determine the language to display the widget in and the language of the SMS / Voice. Should you not add this value, the language of the browser will be used to determine how to show the widget and SMS / Voice. See the example below for displaying the texts in portuguese.

<div id="xyz" data-widget data-app="{{ app_key }}" data-locale="pt"></div>

The list of supported languages is: ar (Arabic), de (German), en (English), es (Spanish), fi (Finnish), fr (French), gr (Greek), it (Italian), ja (Japanese), nl (Dutch), pt (Portuguese), ru (Russian), sv (Swedish), tr (Turkish), zh Chinese

. Should you need a language not specified in this list, feel free to send us an email with the request or if interested, with the translations.

Changing the widget default country


The country displayed by default on the widget will correspond to the IP address the user has at the moment of displaying the widget. In the interest of changing it to display a fixed country code by default instead of the country the user is accessing the site from, please include the javascript at the end of the <body> tag

var country = "us";
var appKey = "{{ app_key }}";
var widget = new RingCaptcha.Widget('#xyz', {
  app: appKey,
  events: {
    ready: function () {
      $(this).find('[data-country-iso="' + country +'"]').click();
    }
  }
}).setup();

Set the phone number value dynamically


Imagine you already have the phone number stored in your database, or in your site already and you want to pre-poluate the widget with that number. You can accomplish this by hooking up to the "ready.rc.widget" event and set the value dynamically.

var phoneNumber = "1111111111";
var appKey = "{{ app_key }}";
var widget = new RingCaptcha.Widget('#xyz', {
  app: appKey,
  events: {
    ready: function () {
      $(this).find('.phone-input').val(phoneNumber);
    }
  }
}).setup();

Disable the country list dropdown


To disable the country list drop-down so the user does not have the option of changing it, you will need to use the following code:

var appKey = "{{ app_key }}";
var widget = new RingCaptcha.Widget('#xyz', {
  app: appKey,
  events: {
    ready: function () {
      $(this).off('click', '.country-button');
    }
  }
}).setup();

For any other customizations not included here, keep in mind you can write any code that listens to the JS events emitted by the widget.