PROFILE.md

PHP Yoti App Integration

1. An Architectural View - High level overview of integration

2. Client Initialisation - Description on initialising the client

3. Profile Retrieval - Description on setting up profile

4. Handling Users - Description on handling user details

5. Running the Example How to run the example project provided

6. API Coverage - Attributes defined

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 Yoti Hub when you create/update your application.

The image below shows how your application back-end and Yoti integrate in the context of a Login flow. Yoti SDK carries out for you steps 6, 7 ,8 and the profile decryption in step 9.

Yoti also allows you to enable user details verification from your mobile app by means of the Android and iOS SDKs. In that scenario, your Yoti-enabled mobile app is playing both the role of the browser and the Yoti app. By the way, your back-end doesn't need to handle these cases in a significantly different way. You might just decide to handle the User-Agent header in order to provide different responses for web and mobile clients.

Client Initialisation

The YotiClient is the SDK entry point. To initialise it you need to include the following snippet inside your endpoint initialisation section:

<?php
require_once './vendor/autoload.php';
try {
    $client = new \Yoti\YotiClient('YOUR_SDK_ID', 'path/to/your-application-pem-file.pem');
} catch(Exception $e) {
    // Handle unhappy path
}

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 by adding the following to your endpoint handler:

<?php
// The token can be used only once
// Reusing the same token will result to a 404 error
$oneTimeUseToken = $_GET['token'];

try {
    $client = new \Yoti\YotiClient('SDK_ID', 'path/to/your-application-pem-file.pem');
    $activityDetails = $client->getActivityDetails($oneTimeUseToken);
} catch(Exception $e) {
    // Handle unhappy path
}

Available User Profile Attributes Through Getters

We have exposed user profile attributes through getters. You will find in the example below the getters available to you and how to use them:

<?php
$activityDetails    = $client->getActivityDetails($oneTimeUseToken);

$rememberMeId       = $activityDetails->getRememberMeId();

$profile            = $activityDetails->getProfile();

$familyName         = $profile->getFamilyName()->getValue();

$givenNames         = $profile->getGivenNames()->getValue();

$fullName           = $profile->getFullName()->getValue();

$dateOfBirth        = $profile->getDateOfBirth()->getValue(); // DateTime Object

$gender             = $profile->getGender()->getValue();

$nationality        = $profile->getNationality()->getValue();

$phoneNumber        = $profile->getPhoneNumber()->getValue();

$selfie             = $profile->getSelfie()->getValue(); // Yoti\Media\Image Object

$emailAddress       = $profile->getEmailAddress()->getValue();

$postalAddress      = $profile->getPostalAddress()->getValue();

$ageVerifications   = $profile->getAgeVerifications(); // array of AgeVerification object, e.g ['age_over:18' => new AgeVerification(),]

$ageOverXX          = $profile->findAgeOverVerification($xx); // AgeVerification Object (please see API Coverage for details), Where $xx is the age value, e.g 50

$ageUnderXX         = $profile->findAgeUnderVerification($xx); // AgeVerification Object (please see API Coverage for details), Where $xx is the age value, e.g 18

Handling Users

When you retrieve the user profile, you receive a rememberMeId 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. You can use this ID to verify whether (for your application) the retrieved profile identifies a new or an existing user. Here is an example of how this works:

<?php
try {
    $activityDetails = $client->getActivityDetails($oneTimeUseToken);
    $profile = $activityDetails->getProfile();
    $user = yourUserSearchFunction($activityDetails->getRememberMeId());

    if ($user) {
        // Handle login
    } else {
        // Handle registration
        $givenNames = $profile->getGivenNames()->getValue();
        $familyName = $profile->getFamilyName()->getValue();
    }
} catch (Exception $e) {
    // Handle unhappy path
}

Where yourUserSearchMethod is a piece of logic in your app that is supposed to find a user, given a userId. No matter if the user is a new or an existing one, Yoti will always provide her/his profile, so you don't necessarily need to store it.

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 Hub.

You can retrieve the sources and verifiers for each attribute as follows:

<?php
$givenNamesSources = $profile->getGivenNames()->getSources(); // array of anchors
$givenNamesVerifiers = $profile->getGivenNames()->getVerifiers(); // array of anchors

You can also retrieve further properties from these respective anchors in the following way:

<?php
// Retrieving properties of the first anchor
$value = $givenNamesSources[0]->getValue(); // string
$subType = $givenNamesSources[0]->getSubType(); // string
$timeStamp = $givenNamesSources[0]->getSignedTimeStamp()->getTimestamp(); // DateTime object
$originServerCerts = $givenNamesSources[0]->getOriginServerCerts(); // array of X509 certificates

Running the Example

• See the Profile Example folder for instructions on how to run the Profile Example project

API Coverage

• Activity Details
  • Remember Me ID getRememberMeId()
  • Parent Remember Me ID getParentRememberMeId()
  • Receipt ID getReceiptId()
  • Timestamp getTimestamp() // DateTime Object
  • Application Profile getApplicationProfile()
    • Name getApplicationName()->getValue()
    • Url getApplicationUrl()->getValue()
    • Logo getApplicationLogo()->getValue()
    • Receipt Bg Color getApplicationReceiptBgColor()->getValue()
  • Profile getProfile()
    • Photo getSelfie()->getValue() // Yoti\Media\Image Object
      • Image Data getContent()
      • MimeType getMimeType()
      • Base64Uri getBase64Content()
    • Given Names getGivenNames()->getValue()
    • Family Name getFamilyName()->getValue()
    • Full Name getFullName()->getValue()
    • Mobile Number getPhoneNumber()->getValue()
    • Email Address getEmailAddress()->getValue()
    • Age / Date of Birth getDateOfBirth()->getValue() // DateTime Object
      • Date format('d-m-Y')
    • Age / Age Verifications getAgeVerifications() // array of AgeVerification Object
      • Age Over 50 ['age_over:50'] // AgeVerification Object, this depends on your settings on Yoti Hub
    • Age Under Verification findAgeUnderVerification($xx) // Yoti\Profile\Attribute\AgeVerification Object
    • Age Over Verification findAgeOverVerification($xx) // Yoti\Profile\Attribute\AgeVerification Object, see details below
      • Age getAge() // int, e.g 50
      • Check Type getCheckType() // string, e.g 'age_over'
      • Result getResult() // boolean
      • Attribute getAttribute() // Yoti\Profile\Attribute Object
    • Address getPostalAddress()->getValue()
    • Structured Postal Address getStructuredPostalAddress()->getValue()
    • Gender getGender()->getValue()
    • Nationality getNationality()->getValue()
    • Document Details getDocumentDetails()->getValue()