README.md in yoti-1.2.1 vs README.md in yoti-1.3.0

- old
+ new

@@ -6,20 +6,20 @@ 1. [An Architectural view](#an-architectural-view) - High level overview of integration 1. [Requirements](#requirements) - Everything you need to get started 1. [Installing the SDK](#installing-the-sdk) - How to install our SDK 1. [Configuration](#configuration) - Configuring the SDK -1. [Profile Retrieval](#profile-retrieval) - How to retrieve a Yoti profile using the token +1. [Profile Retrieval](#profile-retrieval) - How to retrieve a Yoti profile using the one time use token 1. [AML Integration](#aml-integration) - How to integrate with Yoti's AML (Anti Money Laundering) service 1. [Running the Examples](#running-the-examples) - How to run the example projects provided 1. [API Coverage](#api-coverage) - Attributes defined 1. [Support](#support) - Please feel free to reach out ## An Architectural view To integrate your application with Yoti, your back-end must expose a GET endpoint that Yoti will use to forward tokens. -The endpoint can be configured in your Yoti Dashboard when you create/update your application. It can be found in the Integration section under the Callback URL name. +The endpoint is configured in the [Yoti Dashboard](https://www.yoti.com/dashboard) where you create/update your application. To see an example of how this is configured, see the [Running the Examples](#running-the-examples) section. The image below shows how your application back-end and Yoti integrate into the context of a Login flow. Yoti SDK carries out for you steps 6, 7, 8 and the profile decryption in step 9. ![alt text](login_flow.png "Login flow") @@ -38,11 +38,11 @@ [Protocol buffers]: https://en.wikipedia.org/wiki/Protocol_Buffers [Base64 data]: https://en.wikipedia.org/wiki/Base64 ## Requirements -The Yoti gem requires at least Ruby 2.0.0. +The Yoti gem requires at least Ruby `2.4.0`. If you're using a version of Ruby lower than 2.2.2 you might encounter issues when [Bundler][] tries to install the [Active Support][] gem. This can be avoided by manually requiring activesupport 4.2. ```ruby gem activesupport '~> 4.2' ``` @@ -138,27 +138,30 @@ [Heroku Command Line]: https://devcenter.heroku.com/articles/heroku-command-line ## Profile Retrieval -When your application receives a token via the exposed endpoint (it will be assigned to a query string parameter named `token`), you can easily retrieve the user profile: +When your application receives a one time use token via the exposed endpoint (it will be assigned to a query string parameter named `token`), you can easily retrieve the user profile: ```ruby -yoti_activity_details = Yoti::Client.get_activity_details(params[:token]) +one_time_use_token = params[:token] +yoti_activity_details = Yoti::Client.get_activity_details(one_time_use_token) ``` Before you inspect the user profile, you might want to check whether the user validation was successful. This is done as follows: ```ruby if yoti_activity_details.outcome == 'SUCCESS' - user_profile = yoti_activity_details.user_profile + profile = yoti_activity_details.profile + given_names = profile.given_names.value + family_name = profile.family_name.value else # handle unhappy path end ``` -The `user_profile` object provides a set of attributes corresponding to user attributes. Whether the attributes are present or not depends on the settings you have applied to your app on Yoti Dashboard. +The `profile` object provides a set of attributes corresponding to user attributes. Whether the attributes are present or not depends on the settings you have applied to your app on Yoti Dashboard. ### Handling Users When you retrieve the user profile, you receive a user ID generated by Yoti exclusively for your application. This means that if the same individual logs into another app, Yoti will assign her/him a different ID. @@ -166,34 +169,63 @@ Here is an example of how this works: ```ruby if yoti_activity_details.outcome == 'SUCCESS' user = your_user_search_function(yoti_activity_details.user_id) + profile = yoti_activity_details.profile if user # handle login + email = profile.email_address.value else # handle registration + given_names = profile.given_names.value + family_name = profile.family_name.value + email = profile.email_address.value end else # handle unhappy path end ``` Where `your_user_search_function` is a piece of logic in your app that is supposed to find a user, given a user_id. Regardless of whether the user is a new or an existing one, Yoti will always provide their profile, so you don't necessarily need to store it. +You can retrieve the sources and verifiers for each attribute as follows: + +```ruby +given_names_sources = profile.given_names.sources // list of anchors +given_names_verifiers = profile.given_names.verifiers // list of anchors +``` +You can also retrieve further properties from these respective anchors in the following way: + +```ruby +// Retrieving properties of the first anchor +value = given_names_sources[0].value // string +sub_type = given_names_sources[0].sub_type // string +time_stamp = given_names_sources[0].signed_time_stamp.time_stamp // DateTime object +origin_server_certs = given_names_sources[0].origin_server_certs // list of X509 certificates +``` + +In case you want to prove the sources and verifiers of the helper`ActivityDetails.age_verified` on `Age Over 18` set as age derivation, please retrieve it's original attribute from the profile as follow: + +```ruby +age_attribute = profile.get_attribute('age_over:18') +sources = age_attribute.sources +verifiers = age_attribute.verifiers +``` + ## AML Integration Yoti provides an AML (Anti Money Laundering) check service to allow a deeper KYC process to prevent fraud. This is a chargeable service, so please contact [sdksupport@yoti.com](mailto:sdksupport@yoti.com) for more information. Yoti will provide a boolean result on the following checks: * PEP list - Verify against Politically Exposed Persons list * Fraud list - Verify against US Social Security Administration Fraud (SSN Fraud) list * Watch list - Verify against watch lists from the Office of Foreign Assets Control -To use this functionality you must ensure your application is assigned to your organisation in the Yoti Dashboard - please see here for further information. +To use this functionality you must ensure your application is assigned to your organisation in the Yoti Dashboard - please see [here](https://www.yoti.com/developers/documentation/#1-creating-an-organisation) for further information. For the AML check you will need to provide the following: * Data provided by Yoti (please ensure you have selected the Given name(s) and Family name attributes from the Data tab in the Yoti Dashboard) * Given name(s) @@ -226,30 +258,35 @@ puts Yoti::Client.aml_check(aml_profile) ``` ## Running the Examples -The examples can be found in the [examples folder](examples). -For them to work you will need a working callback URL that your browser can redirect to. The callback URL for both examples will be: `http://your-local-url.domain/profile`. +The examples can be found in the [examples folder](examples). -The examples also use the `YOTI_APPLICATION_ID` environment variable to display the Yoti Connect button. This value can be found in your Yoti account, on the *Keys* settings page. - ### Ruby on Rails -* rename the [.env.example](examples/rails/.env.example) file to `.env` and fill in the required configuration values -* install the dependencies with `bundle install` -* start the server `rails server` +1. Create your application in the [Yoti Dashboard](https://www.yoti.com/dashboard/applications) +1. Set the application domain of your app to `localhost:3000` +1. Set the scenario callback URL to `/profile` +1. Rename the [.env.example](examples/rails/.env.example) file to `.env` +1. Fill in the environment variables in this file with the ones specific to your application (mentioned in the [Configuration](#configuration) section) +1. Install the dependencies with `bundle install` +1. Start the server `rails server` -Visiting the `http://your-local-url.domain` should show a Yoti Connect button +Visiting `http://localhost:3000/` should show a Yoti Connect button ### Sinatra -* rename the [.env.example](examples/sinatra/.env.example) file to `.env` and fill in the required configuration values -* install the dependencies with `bundle install` -* start the server `ruby ./app.rb` +1. Create your application in the [Yoti Dashboard](https://www.yoti.com/dashboard/applications) +1. Set the application domain of your app to `localhost:4567` +1. Set the scenario callback URL to `/profile` +1. Rename the [.env.example](examples/sinatra/.env.example) file to `.env` +1. Fill in the environment variables in this file with the ones specific to your application (mentioned in the [Configuration](#configuration) section) +1. Install the dependencies with `bundle install` +1. Start the server `ruby ./app.rb` -Visiting the `http://your-local-url.domain` should show a Yoti Connect button +Visiting `http://localhost:4567/` should show a Yoti Connect button ### AML Check * rename the [.env.example](examples/aml_check/.env.example) file to `.env` and fill in the required configuration values * install the dependencies with `bundle install` @@ -257,23 +294,22 @@ ## API Coverage * Activity Details * [X] User ID `user_id` - * [X] Profile + * [X] Base64 Selfie URI `base64_selfie_uri` + * [X] Age verified `age_verified` + * [X] Profile `profile` * [X] Selfie `selfie` * [X] Full Name `full_name` * [X] Given Names `given_names` * [X] Family Name `family_name` * [X] Mobile Number `phone_number` * [X] Email Address `email_address` * [X] Age / Date of Birth `date_of_birth` - * [X] Age / Verify Condition `age_[over|under]:[1-999]` * [X] Address `postal_address` * [X] Gender `gender` * [X] Nationality `nationality` - * [X] Base64 Selfie URI `base64_selfie_uri` - * [X] Age verified `age_verified` ## Support For any questions or support please email [sdksupport@yoti.com](mailto:sdksupport@yoti.com). Please provide the following to get you up and working as quickly as possible: