Documentation Cordova / OutSystems

1 Installation

Le plugin s'ajoute à votre application Cordova existante — aucune modification du build hôte n'est requise : permissions, écrans natifs et dépendances Gradle/Xcode sont déclarés par le plugin lui-même.

Android : cordova-android 15+, JDK 17+, Gradle installé et sur le PATH (Cordova ne l'embarque pas), minSdk 26, appareil réel avec NFC
iOS : Xcode 15+, iPhone réel, compte développeur Apple payant (exigé par le NFC — voir la section iOS)
L'émulateur ne convient pas : pas de caméra ni de NFC.

Terminal — projet Cordova existant

cordova plugin add https://git.cortixia.io/mohamed.zidoun/cordova-plugin-cortixia-kyc.git

OutSystems O11 — Extensibility Configurations de votre application mobile

{
  "plugin": {
    "url": "https://git.cortixia.io/mohamed.zidoun/cordova-plugin-cortixia-kyc.git"
  }
}

Sous OutSystems, publiez ensuite : MABS applique automatiquement les permissions et l'entitlement NFC déclarés par le plugin. L'API est disponible après deviceready sous cordova.plugins.cortixiaKyc.

2 Votre jeton API

Le jeton (format ck_live_…) est créé avec votre compte et visible sur votre tableau de bord. Il identifie votre entreprise, porte vos packs et votre quota. Créer un compte — 50 crédits d'essai, sans carte bancaire.

index.js — après deviceready

const kyc = cordova.plugins.cortixiaKyc;

const licence = await kyc.initialize({ apiToken: 'ck_live_VOTRE_JETON' });
// licence.client, licence.plan,
// licence.quota { limit, used, remaining }

Toutes les méthodes renvoient une Promise. En cas de refus, l'erreur porte { code, message } — le message est en français, prêt à afficher tel quel.

3 Premier scan

Un appel ouvre le parcours complet : caméra → MRZ → lecture NFC → liveness. Le plugin gère les écrans natifs, vous recevez un seul résultat. Le liveness compare le visage en direct à la photo de la puce.

index.js — ou nœud JavaScript OutSystems

const r = await kyc.scanIdCard();      // aussi : scanPassport()

if (r.status === 'success' && r.liveness.decision === 'True') {
  console.log(r.mrz.surname, r.mrz.document_number);
  const identite = r.decoded.decoded;  // dg11/dg12 : champs d'identité
  const photo = identite.dg2.face;     // portrait de la puce, JPEG base64
}

Sous OutSystems, placez ce code dans un nœud JavaScript côté client et mappez l'objet résolu sur vos variables locales. Documents pris en charge : carte d'identité biométrique et passeport algériens. Un parcours complet consomme trois crédits — un par pack.

À la carte

Points d'entrée modulaires

Chaque capacité s'appelle aussi seule — utile quand votre système possède déjà une partie du parcours.

scanMrz — lire la MRZ sans toucher la puce

const mrz = await kyc.scanMrz('idcard');   // ou 'passport'
console.log(mrz.fields.document_number);
console.log(mrz.mrz_keys);   // les clés nécessaires à la lecture NFC

readChip — lire la puce avec des clés que vous avez déjà

const chip = await kyc.readChip({
  documentType: 'idcard',
  mrzKeys: mrz.mrz_keys,   // issus de scanMrz(), ou de votre système
});
const photo = chip.decoded.dg2.face;   // portrait JPEG base64

checkLiveness — vérification de présence seule

const live = await kyc.checkLiveness();
if (live.decision === 'True') {
  // présence confirmée (decision est une chaîne)
}

scanMrz nécessite le pack MRZ, readChip le pack NFC, checkLiveness le pack Liveness — le serveur reste seul juge des droits.

Configuration iOS

L'API JavaScript est identique sur les deux plateformes. iOS impose seulement une signature particulière : le NFC exige un compte développeur Apple payant (les équipes personnelles gratuites n'y ont pas droit). Le plugin déclare lui-même l'entitlement NFC et l'identifiant d'applet du document — avec la signature automatique, Xcode active la capacité sur votre App ID.

build.json — à la racine de votre projet Cordova

{
  "ios": {
    "debug": {
      "codeSignIdentity": "Apple Development",
      "developmentTeam": "VOTRE_TEAM_ID",
      "automaticProvisioning": true,
      "buildFlag": ["-allowProvisioningUpdates"]
    },
    "release": {
      "codeSignIdentity": "Apple Development",
      "developmentTeam": "VOTRE_TEAM_ID",
      "automaticProvisioning": true,
      "buildFlag": ["-allowProvisioningUpdates"]
    }
  }
}

Terminal

cordova platform add ios
cordova run ios --device --buildConfig=build.json

Sous OutSystems : signez avec une équipe payante dont l'App ID a la capacité « NFC Tag Reading » — MABS applique le reste automatiquement.
iOS affiche sa propre feuille système « Ready to Scan » pendant la lecture NFC.
L'antenne NFC de l'iPhone est sur le bord supérieur du dos — tenez-y le document (contrairement à Android, où elle est au centre).

Build de release Android

Automatique. Le plugin embarque ses propres règles ProGuard (cortixia-kyc-proguard.pro) et les applique lui-même à tous les types de build : activez minifyEnabled si vous le souhaitez, il n'y a aucune règle à copier. Elles conservent la classe du plugin (chargée par réflexion depuis config.xml) et les bibliothèques de lecture de puce.

Le plugin Android est écrit en Java précisément pour qu'un build hôte standard — dont OutSystems — n'ait besoin d'aucune chaîne Kotlin.

Référence

Endpoints REST

Ce que le plugin appelle pour vous — utilisables aussi directement.

Endpoint	Rôle	Facturation
POST /api/sdk/v1/init	Valide votre jeton et renvoie votre plan, votre quota et vos packs actifs.	Non facturé
POST /api/sdk/v1/mrz	Valide et décode les lignes MRZ lues par la caméra.	1 crédit
POST /api/sdk/v1/decode	Décode les groupes de données lus sur la puce du document.	1 crédit
POST /api/sdk/v1/liveness	Compare une vidéo selfie à une photo de référence.	1 crédit
POST /api/sdk/v1/events	Télémétrie du SDK (début et fin de scan).	Non facturé

curl

curl -X POST https://www.e-kyc.online/api/sdk/v1/init \
  -H "X-API-Key: ck_live_VOTRE_JETON" \
  -H "Content-Type: application/json" \
  -d '{"sdk_version": "0.1.3", "platform": "cordova"}'

Erreurs

Codes d'erreur

Chaque refus porte un code stable et un message en français, prêt à afficher.

Code plugin	Signification
cancelled	L'utilisateur a quitté l'écran en cours de parcours.
not_initialized	initialize() n'a pas été appelé (ou le jeton a été refusé).
nfc_unavailable · nfc_disabled	Appareil sans NFC, ou NFC désactivé dans les réglages.
bac_failed	La puce a refusé l'authentification — la MRZ a été mal lue, refaites le scan.
nfc_read_failed	Lecture de la puce interrompue — repositionnez le document et réessayez.
capture_failed	Capture vidéo du liveness incomplète — réessayez.

HTTP	Code	Signification
401	invalid_token	Jeton absent, inconnu ou révoqué.
402	quota_exceeded	Crédits épuisés pour la période en cours.
402	no_active_subscription	Aucun abonnement actif sur le compte.
402	pack_not_entitled	Le pack requis n'est pas activé sur le compte.
400	invalid_datagroups	Les données envoyées ne sont pas exploitables.
502	liveness_unavailable	Le service de liveness est momentanément indisponible.

Une fois connecté, tous ces extraits sont pré-remplis avec votre jeton réel. Documentation personnalisée →

Cordova & OutSystems, même parcours.