Intégration du workflow

Intégrez des workflows KYC dans votre application web à l’aide du SDK Web ComplyCube.

Vue d'ensemble

Ce guide vous accompagne dans l'intégration du SDK Web avec ComplyCube flux de travail.

Pour un exemple rapide à copier-coller, utilisez notre assistant d’intégration.

Flux d'intégration

Le SDK Web s'exécute dans votre frontend, mais s'appuie sur votre backend pour créer des jetons sécurisés. Voici comment cela fonctionne :

Créer un client

Enregistrez un nouveau client (c.-à-d. le client) en utilisant l'API ComplyCube

Générez un jeton SDK

Votre backend demande un jeton JWT lié à ce client.

Importez et montez le SDK

Ajoutez les fichiers JS et CSS, puis montez le SDK dans votre application web.

Capturez des documents, des vidéos et des selfies

Le SDK guide votre client à travers les étapes requises.

Effectuer les contrôles de vérification

Les données capturées sont envoyées en toute sécurité à ComplyCube pour les vérifications, et les résultats sont fournis en temps réel via l’API ou les webhooks.

Guide d'intégration

Créer un client

Chaque flux de vérification commence par un client (c.-à-d. client). Utilisez l'API pour créer le client.

Exemple de requête

curl -X POST https://api.complycube.com/v1/clients \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "type": "person",
          "email": "john.doe@example.com",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe"
          }
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const client = await complycube.client.create({
  type: "person",
  email: "john.doe@example.com",
  personDetails: {
    firstName: "John",
    lastName: "Doe"
  }
});

from complycube import ComplyCubeClient
cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

new_client = {
    'type':'person',
    'email':'john.doe@example.com',
    'personDetails': {
        'firstName':'John',
        'lastName':'Doe'
    }
}

client = cc_api.clients.create(**new_client)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->clients()->create([
    'type' => 'person',
    'email' => 'john@doe.com',
    'personDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe'
    ]
]);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Clients;

var clientApi = new ClientApi(new ComplyCubeClient("<YOUR_API_KEY>"));
var newClient = new ClientRequest {
  type = "person",
  email = "john@doe.com",
  personDetails = new PersonDetails {
    firstName = "John",
    lastName = "Doe"
  }
}

var client = await clientApi.CreateAsync(newClient);

Exemple de réponse

La réponse contiendra un id (l'ID du client). Il est requis pour l'étape suivante.

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "john.doe@example.com",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "createdAt": "2020-01-04T17:24:29.146Z",
    "updatedAt": "2020-01-04T17:24:29.146Z"
}

Voir Référence de l'API Clients pour en savoir plus.

Générer un jeton SDK

Votre backend doit créer un jeton SDK pour chaque nouveau flux. Ce jeton associe la session du SDK au client. Les jetons sont de courte durée et ne doivent pas être réutilisés.

Exemple de requête

curl -X POST https://api.complycube.com/v1/tokens \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "referrer": "https://www.example.com/*"
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const token = await complycube.token.generate("CLIENT_ID", {
    referrer: "https://www.example.com/*"
});

from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

token = cc_api.tokens.create('CLIENT_ID','https://www.example.com/*')

 use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$report = $ccapi->tokens()->generate('CLIENT_ID', 'https://www.example.com/*');

using ComplyCube.Net;
using ComplyCube.Net.Resources.SDKTokens;

var sdkTokenApi = new SDKTokenApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var sdkTokenRequest = {
  clientId = "CLIENT_ID",
  referrer = "https://www.example.com/*"
}

var sdkToken = await sdkTokenApi.GenerateToken(sdkTokenRequest);

Exemple de réponse

{
    "token": "<CLIENT_TOKEN>"
}

Voir Référence de l'API des jetons SDK pour en savoir plus.

Importer le SDK

Pour importer notre SDK Web, vous devez l'inclure dans le HTML de votre page cible :

<!DOCTYPE html>
<html>
  <head>
    ...
    <!-- Importation de la bibliothèque JavaScript -->
    <script src="complycube.min.js"></script>

    <!-- Importation du CSS par défaut -->
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
     <!-- C'est ici que le SDK Web sera monté -->
    <div id="complycube-mount"></div>
  </body>
</html>

Chargement du SDK avec intégrité (Facultatif)

Pour plus de sécurité, vous pouvez charger le SDK Web ComplyCube de manière facultative à l’aide de Intégrité des sous-ressources (SRI). Cela permet au navigateur de vérifier que les fichiers JavaScript et CSS n’ont pas été modifiés en les validant à l’aide de sommes de contrôle cryptographiques.

Récupérer les dernières valeurs d’intégrité du SDK

Pour vous assurer d’utiliser toujours la dernière version prise en charge du SDK et les derniers hachages d’intégrité, récupérez les métadonnées des ressources depuis le point de terminaison d’informations du SDK Web.

Exemple de requête

curl -X POST https://api.complycube.com/v1/webSdk/latest \
     -H 'Authorization: <YOUR_API_KEY>'

Exemple de réponse

La réponse inclut les URL et les valeurs d’intégrité correspondantes pour les ressources JavaScript et CSS.

{
  "js": {
    "url": "<JAVASCRIPT_ASSET_URL>/complycube.min.js",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  },
  "css": {
    "url": "<CSS_ASSET_URL>/style.css",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  }
}

Importer le SDK à l’aide d’attributs d’intégrité

Utilisez les valeurs renvoyées pour charger le SDK dans votre HTML avec integrity et crossorigin attributs :

<!DOCTYPE html>
<html>
  ...
  <head>
    <!-- Importation de la bibliothèque JavaScript -->
    <script
      src="<JAVASCRIPT_ASSET_URL>/sdk.min.js"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
    </script>

    <!-- Importation du CSS par défaut -->
    <link
      rel="stylesheet"
      href="<CSS_ASSET_URL>/style.css"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
  </link>
  </head>
  
  <!-- C'est ici que le SDK Web sera monté -->
  <body>
    <div id="complycube-mount"></div>
  </body>
</html>

Remarques

L’utilisation du SRI est facultative, mais recommandée pour les environnements avec des exigences de sécurité plus strictes.
L’attribut crossorigin="anonymous" est requis lors de l’utilisation de SRI avec des ressources servies depuis une origine différente.
Les valeurs d’intégrité peuvent changer lorsque le SDK est mis à jour. Récupérez toujours les dernières valeurs depuis le point de terminaison.

Les liens vers complycube.min.js et style.css peuvent être trouvés dans votre portail développeurs.

Monter le SDK

Dans le cadre du montage du SDK Web, vous devez spécifier un ID du modèle de flux de travail. Le SDK exécutera automatiquement la active version du flux de travail sélectionné.

Une fois le flux de vérification terminé, les clients sont redirigés vers l'URL de retour que vous spécifiez.

Avec le jeton généré, le SDK Web peut être initialisé dans votre frontend à l'aide du code JavaScript suivant :

ComplyCube.mount({
  token: '<YOUR_WEB_SDK_TOKEN>',
  containerId: 'complycube-mount',
  workflowTemplateId: "WORKFLOW_TEMPLATE_ID",
  onComplete: function(data) {    
    // Demandez à votre backend d'avertir ComplyCube une fois le flux de travail terminé
    // afin de déclencher les contrôles de vérification
    console.info('Capture terminée');
  },
  onModalClose: function() {
    // Gérer la tentative de fermeture de la fenêtre modale
  },
  onError: function ({ type, message }) {
    if (type === 'token_expired') {
      // Demander un nouveau jeton SDK
    } else {
      // Gérer les autres erreurs
      console.error(message);
    }
  }
});

Les paramètres de montage du SDK sont décrits dans la section Paramètres du SDK ci-dessous.

Politique de référent

Pour permettre une communication réussie entre le SDK et nos serveurs, l'en-tête de votre page web Politique de référent doit être défini sur strict-origin-when-cross-origin. Cela garantit que les informations de référent sont transmises de manière sécurisée lors des requêtes HTTP.

Vous pouvez soit le faire par programmation, soit l'ajouter directement à la page web comme suit : <meta name="referrer" content="strict-origin-when-cross-origin">

Effectuer les contrôles de vérification

Une fois que votre client démarre le flux, une session de flux de travail est automatiquement créée. Cette session contient toutes les données capturées (documents, images et vidéos), ainsi que le suivi de la progression. Vous pouvez les consulter via la page des sessions de flux de travail sur le portail ou via l'API.

Lorsque le flux se termine, le SDK déclenche le onComplete rappel. Le rappel fournit un objet de données qui inclut le workflowSessionId. Votre backend doit utiliser cet ID pour informer ComplyCube que le flux de travail est terminé, ce qui déclenche à son tour les contrôles de vérification définis dans le flux de travail.

Si vous avez configuré des webhooks comme décrit dans notre guide sur les webhooks, vous serez averti une fois qu'une session de flux de travail sera terminée.

Vous pouvez récupérer les détails d'une session de flux de travail en appelant la requête de récupération de session de flux de travail.

Exemple d'une requête complète de session de flux de travail

curl -X POST https://api.complycube.com/v1/workflowSessions/{:wfSessionId}/complete \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const wfSession = await complycube.workflowSession.complete("WORKFLOW_SESSION_ID");

from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

workflow_session = cc_api.workflowsessions.complete('WORKFLOW_SESSION_ID')

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$workflowSession = $ccapi->workflowSessions()->complete('WORKFLOW_SESSION_ID');

using ComplyCube.Net;
using ComplyCube.Net.Resources.WorkflowSessions;

var wfSessionApi = new WorkflowSessionApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var workflowSession = await wfSessionApi.CompleteAsync("WORKFLOW_SESSION_ID");

Référence du SDK

Cette section décrit tous les paramètres configurables, les rappels, les méthodes du cycle de vie et les options de personnalisation de marque disponibles dans le SDK Web ComplyCube.

Paramètres

Option

Description

jeton

Le jeton SDK généré par votre backend. C'est obligatoire. Type: chaîne

workflowTemplateId

L'ID du modèle de flux de travail à charger pour cette session. C'est obligatoire.

Type : chaîne

containerId

L'ID de l'élément conteneur où le SDK s'intègre. Celui-ci doit être un élément vide.

Type : chaîne Valeur par défaut: complycube-mount

useModal

Définit si les écrans de l'interface utilisateur se chargent dans une fenêtre modale plutôt qu'en ligne. Type : booléen Valeur par défaut: true

useFullScreen

Définit si le SDK se charge en mode plein écran. Type : booléen Valeur par défaut: false

disableClientAnalytics

Définit si nous suivons ou non les statistiques client.

Type : booléen Valeur par défaut: false

Rappel

Les rappels vous permettent de réagir aux événements du cycle de vie du SDK.

Option

Description

onComplete

Déclenché après que le client a terminé le flux de vérification. Cela sert à invoquer une requête de finalisation de session de flux de travail.

onError

Déclenché lorsqu'une erreur se produit. L'objet erreur comporte deux attributs :

type : cela peut être :
- exception
- token_expired : indique que le jeton a expiré. Dans ce cas, un nouveau jeton SDK doit être fourni.
message : description de l'erreur.

onExit

Ce rappel est déclenché lorsque votre client quitte avant de terminer le flux. Il renverra la raison de la sortie, par ex., USER_CONSENT_NOT_GRANTED.

onModalClose

Déclenché lorsque le client tente de fermer la fenêtre modale. Vous pouvez autoriser ou empêcher la fermeture en mettant à jour l'attribut isModalOpen à l'aide de updateSettings.

Mise à jour des paramètres

Un certain nombre de paramètres peuvent être mis à jour à l’exécution comme suit :

complycube = ComplyCube.mount({...});

// Remplacer le jeton SDK
complycube.updateSettings({ token: "NEW_SDK_TOKEN" });
...
// Ouvrir la fenêtre modale
complycube.updateSettings({ isModalOpen: true });

//Fermer la fenêtre modale
complycube.updateSettings({ isModalOpen: false });

Démontage du SDK

Si vous utilisez le SDK dans une application monopage (SPA), vous pouvez appeler la fonction unmount pour supprimer le SDK et réinitialiser son état.

complycube = ComplyCube.mount({...});
...
complycube.unmount()

Identité visuelle

Vous pouvez personnaliser les couleurs, les logos et d’autres éléments de marque via la page des paramètres de l’image de marque, si cette option est disponible dans votre forfait.