datakeen-session-react

v1.1.162

Published

14 minutes ago

React SDK component to manage and render Datakeen session experiences easily.

0High
0Medium
0Low

dk-fullstack

datakeen session sdk react component ui frontend typescript

SDK Datakeen Session React

CI/CD Status

| Branch | Pipeline | Coverage | NPM version | |--------|----------|----------|-------------| | main | | | | | staging | | | | | dev | | | |

Table des matières

Installation

# Via npm
npm install datakeen-session-react

# Via yarn
yarn add datakeen-session-react

# Via pnpm
pnpm add datakeen-session-react

Peer dependencies requises

npm install axios react react-dom
# axios@^1.8.0  react@^18.0.0  react-dom@^18.0.0

Stratégie de publication

Le SDK utilise une pipeline CI/CD automatisée qui publie sur npm avec trois tags distincts selon la branche Git :

| Branche Git | Tag NPM | Format de version | Environnement | Commande d'installation | |-------------|-----------|---------------------------|--------------------|------------------------------------------| | main | @latest | 1.1.x (Stable) | Production | npm install datakeen-session-react | | staging | @rc | 1.1.x-rc.y (RC) | Pré-production | npm install datakeen-session-react@rc | | dev | @dev | 1.1.x-dev.y (Dev Build) | Développement | npm install datakeen-session-react@dev |

Chaque merge sur les branches principales déclenche automatiquement :

dev → Incrémente la pré-version → Publie sur @dev
staging → Incrémente la RC → Publie sur @rc
main → Incrémente le patch → Publie sur @latest

Démarrage rapide

Prérequis

React 18+
Un identifiant de session Datakeen valide (obtenu via l'API Datakeen)

Option 1 — Hook `useSession` (recommandé)

import useSession from "datakeen-session-react";

const VerificationPage = () => {
  const { SessionComponent } = useSession(
    "votre-session-id",
    { selfie: false, requireMobile: false }, // optionnel
    "https://app-v3.datakeen.co/backend"     // optionnel
  );

  return <div>{SessionComponent}</div>;
};

Option 2 — Composant `DatakeenSession`

import { DatakeenSession } from "datakeen-session-react";

const VerificationPage = () => (
  <DatakeenSession
    sessionId="votre-session-id"
    sessionConfig={{ selfie: false, requireMobile: false }}
    apiBaseUrl="https://app-v3.datakeen.co/backend"
  />
);

Option 3 — Configuration globale avec `ConfigProvider`

import { DatakeenSession, ConfigProvider } from "datakeen-session-react";

const App = () => (
  <ConfigProvider apiBaseUrl="https://app-v3.datakeen.co/backend">
    <DatakeenSession sessionId="votre-session-id" />
  </ConfigProvider>
);

API publique

`useSession(sessionId, sessionConfig?, apiBaseUrl?)` — Hook principal

import useSession from "datakeen-session-react";

const { SessionComponent } = useSession(
  sessionId: string,
  sessionConfig?: SessionConfig,
  apiBaseUrl?: string
);

| Paramètre | Type | Requis | Description | |-----------|------|--------|-------------| | sessionId | string | ✅ | ID unique de la session Datakeen | | sessionConfig | SessionConfig | ❌ | Options de configuration du flux | | apiBaseUrl | string | ❌ | URL de base de l'API (override la config globale) |

SessionConfig

| Propriété | Type | Description | |-----------|------|-------------| | selfie | boolean | Active la vérification par selfie biométrique | | requireMobile | boolean | Force l'utilisation d'un appareil mobile (redirection QR code) |

Retour : { SessionComponent: React.ReactElement }

`DatakeenSession` — Composant principal

import { DatakeenSession } from "datakeen-session-react";

<DatakeenSession
  sessionId="votre-session-id"
  sessionConfig={{ selfie: true }}
  apiBaseUrl="https://app-v3.datakeen.co/backend"
/>

Gère automatiquement : loading/erreur/expiration, layouts mobile/desktop, couleurs dynamiques depuis le template, redirection QR code si requireMobile.

`ConfigProvider` — Provider de configuration

import { ConfigProvider } from "datakeen-session-react";

<ConfigProvider apiBaseUrl="https://app-v3.datakeen.co/backend">
  {/* Tous les DatakeenSession enfants utilisent cette URL */}
  <DatakeenSession sessionId="session-1" />
</ConfigProvider>

`configureApiBaseURL(baseURL)` — Configuration runtime

import { configureApiBaseURL } from "datakeen-session-react";

// À appeler une fois au démarrage de l'application
configureApiBaseURL("https://app-v3.datakeen.co/backend");

`useI18n()` — Hook de traduction

import { useI18n } from "datakeen-session-react";

const { t, translateCodeDescription, translateDocumentType, setLanguage, currentLanguage } = useI18n();

// Changer la langue ("fr" | "en")
await setLanguage("en");

// Traduire un code d'analyse (ex: "2.2")
const desc = translateCodeDescription("2.2");

// Traduire un type de document
const label = translateDocumentType("passport");

`I18nProvider` / `useI18nContext()` — Contexte i18n

import { I18nProvider, useI18nContext } from "datakeen-session-react";

// Provider
<I18nProvider defaultLanguage="fr">
  {children}
</I18nProvider>

// Hook contexte
const { language, setLanguage } = useI18nContext();

Utilitaires d'analyse — `extractRootCauses`, `hasAnalysisFailed`, `getPrimaryRootCause`

import { extractRootCauses, hasAnalysisFailed, getPrimaryRootCause } from "datakeen-session-react";
import type { Prediction, AnalysisResult } from "datakeen-session-react";

// Extraire toutes les causes d'échec
const causes: string[] = extractRootCauses(predictions);

// Vérifier si l'analyse a échoué
const failed: boolean = hasAnalysisFailed(predictions);

// Obtenir la cause principale
const primary: string | null = getPrimaryRootCause(predictions);

Interface Prediction

interface Prediction {
  code: string;            // ex: "1.0", "2.2", "4.0"
  codeName: string;        // ex: "conform", "non_conform"
  codeDescription: string;
  type: string;
  userInput?: { birthDate?: string; firstName?: string; lastName?: string };
}

Codes de résultat principaux :

| Code | Statut | Signification | |------|--------|---------------| | 1.0 | ai_approved | Document vérifié avec succès | | 2.x | ai_rejected | Document refusé (ex: 2.1 qualité, 2.2 non-conforme) | | 3.0 | failed | Erreur d'analyse | | 4.0 | to_verify | Vérification manuelle requise |

Service qualité image — `professionalImageQuality`

import { professionalImageQuality } from "datakeen-session-react";
import type { QualityAnalysis, QualityEnhancementOptions } from "datakeen-session-react";

// Analyser la qualité
const analysis: QualityAnalysis = professionalImageQuality.analyzeQuality(width, height);

// Amélioration automatique depuis flux vidéo
const { dataUrl, analysis, enhanced } = professionalImageQuality.autoEnhanceImage(
  videoElement,
  { x: 0, y: 0, width: 640, height: 480 },
  { outputFormat: "jpeg", jpegQuality: 0.92 }
);

Chargement CSS dynamique — `useRouteCSS`

import { useRouteCSS } from "datakeen-session-react";

// Charger le CSS d'une route au montage
const { loadCSS, unloadCSS } = useRouteCSS("selfie", {
  unloadOnUnmount: true
});

Routes CSS disponibles : start, user-input, contact-info, otp, selfie, document-check, end-flow, jdi, video-recorder, ui-components

Configuration de l'URL API

Le SDK résout l'URL API dans cet ordre de priorité :

Prop apiBaseUrl passée à useSession / DatakeenSession
ConfigProvider parent avec apiBaseUrl
configureApiBaseURL() appelée au runtime
window.VITE_API_BASE_URL (variable globale injectée)
import.meta.env.VITE_API_BASE_URL (Vite)
Fallback : http://localhost:8888

Configuration par environnement (exemple)

// sdk-configuration.ts
import { configureApiBaseURL } from "datakeen-session-react";

const urls = {
  production: "https://app-v3.datakeen.co/backend",
  staging:    "https://app.staging.datakeen.co/backend",
  development:"https://app.dev.datakeen.co/backend",
};

configureApiBaseURL(urls[process.env.NODE_ENV] ?? urls.development);

Via `.env` (Vite)

VITE_API_BASE_URL=https://app-v3.datakeen.co/backend

Commande de setup rapide :

npm run setup:env

Voir docs/configuration.md et docs/dynamic-configuration.md pour plus de détails.

Flux de vérification supportés

Types de nœuds dans un parcours (template)

| Type de nœud | Description | |---|---| | information-input | Saisie données utilisateur (identité, contact, adresse, champs custom) | | document-collection | Collecte et analyse de document (upload ou photo recto/verso) | | controle-jdi | Justificatif de domicile (JDI) | | selfie-capture | Capture selfie biométrique (via Unissey) | | biometric-capture | Capture biométrique | | video-capture | Capture vidéo du document | | condition | Branchement conditionnel basé sur les données de session | | end | Écran de fin et callback | | custom | Nœud personnalisé avec champs définis dans le template |

Documents d'identité supportés

🇫🇷 Carte Nationale d'Identité
🇫🇷 Passeport
🇫🇷 Permis de conduire
🇫🇷 Titre de séjour

Types de champs custom (`CustomField`)

type CustomFieldValueType =
  | "text" | "enum" | "number" | "boolean"
  | "date" | "address" | "list";

Architecture du SDK

DatakeenSession
  ├── useSessionData          → Chargement & normalisation session depuis API
  ├── useStepNavigation       → Navigation graph-like (edges + conditions)
  └── SessionContent          → Dispatcher étapes → composants
        ├── StartSession
        ├── UserInputForm      (identity / contact / address / custom fields)
        ├── DocumentCollection (upload + photo recto/verso + retry)
        ├── JDI flow           (Justificatif de domicile)
        ├── Selfie / VideoCapture / BiometricCapture
        ├── OTPVerification
        ├── ContactInfoForm
        ├── PdfGeneration
        └── EndFlow

Gestion d'état

Store global : SessionContext (session, step, userInput, contactInfo)
Mémoire session : sessionMemoryStore (Map<sessionId, données>) — persiste userInput entre les étapes
Retry counts : Stockés dans session.retryCounts: Record<nodeId, number>

Navigation

La navigation suit les edges du template (graphe orienté). Les nœuds condition et external-verification s'auto-exécutent et sont sautés lors du retour arrière.

// Primitives exposées par useStepNavigation
setStep(n, skipHistory?)    // navigation directe
goBack()                    // retour (skip auto-executing nodes)
goToNextStep(nodeId, template, handle?) // suit les edges
canGoBack                   // boolean

Voir docs/navigation-history.md.

Nœud conditionnel

Le nœud condition évalue des expressions basées sur :

userInput.* — données saisies par l'utilisateur
session.result.* — résultat d'analyse IA
{documentTemplateId}.* — champs extraits du document

Voir docs/condition-node.md.

Système de polling

Le système de polling (v2.0.0) supporte les analyses multiples par session et suit l'état via analysisId.

Cycle d'états d'une analyse

| status | analysisId | progress | code | Signification | |----------|-------------|-----------|--------|---------------| | processing | null | 50% | null | Analyse en cours | | ai_approved | set | 100% | 1.0 | Document approuvé | | ai_rejected | set | 100% | 2.x | Document refusé | | to_verify | set | 100% | 4.0 | Vérification manuelle | | failed | set | 100% | 3.0 | Erreur d'analyse |

Options de polling

analyzeFiles(sessionId, nodeId, files, docTypeId, {
  enablePolling: true,
  pollingOptions: {
    interval: 2000,          // ms entre chaque poll
    maxAttempts: 300,        // max 10 min
    timeout: 600000,
    onProgress: (status) => { /* ... */ },
    onComplete: (result) => { /* ... */ },
    onFailed:   (error) =>  { /* ... */ },
  }
});

Voir docs/POLLING_SYSTEM.md pour la documentation complète.

Internationalisation (i18n)

Le SDK utilise sa propre instance i18next (isolée de l'application hôte).

Langues supportées : fr (défaut), en
Persistance : localStorage clé datakeen-sdk-language
Ressources : traductions principales, types de documents, noms de pays (ISO2/ISO3)

// Intégration avec I18nProvider
<I18nProvider defaultLanguage="fr">
  <DatakeenSession sessionId="..." />
</I18nProvider>

// Changement de langue depuis l'application hôte
const { setLanguage } = useI18nContext();
setLanguage("en");

Documentation avancée

| Document | Description | |----------|-------------| | docs/JOURNEY_NODE_BUILDER.md | Architecture runtime, ajouter un nouveau type de nœud | | docs/POLLING_SYSTEM.md | Système de polling v2.0.0 — point de départ recommandé | | docs/condition-node.md | Nœud conditionnel — tokens, expressions, exemples | | docs/navigation-history.md | Système d'historique de navigation | | docs/configuration.md | Configuration de base | | docs/dynamic-configuration.md | Configuration dynamique multienv | | docs/environment.md | Variables d'environnement | | docs/migration-guide.md | Guide de migration depuis l'ancienne API | | docs/sdk_integration_guide.md | Intégration dans un projet Vite + React |

Exemples de code

| Fichier | Description | |---------|-------------| | examples/usage-example.tsx | Intégration basique | | examples/analysis-progress-example.tsx | Polling avec barre de progression | | examples/sdk-configuration.ts | Configuration par environnement | | examples/test-updated-urls.ts | Tests de validation des URLs |

Développement et tests

Scripts disponibles

# Build production (CJS + ESM + types)
pnpm build

# Build en mode watch
pnpm build:watch

# Développement avec hot-reload
pnpm dev

# Lancer les tests Jest
pnpm test

# Lancer le SDK + la démo en parallèle
pnpm dev:full

# Lint
pnpm lint

Stack technique

| Outil | Version | Rôle | |-------|---------|------| | TypeScript | 5.8 | Typage strict | | Rollup | 4.x | Bundler (CJS + ESM + types) | | Babel | 7.x | Transpilation | | Jest | 29.x | Tests unitaires | | React Testing Library | — | Tests composants | | Cypress | 13.x | Tests composants E2E | | Tailwind CSS | 4.x | Styles | | ESLint | 9.x | Linting (flat config) |

Formats de build

| Format | Chemin | Usage | |--------|--------|-------| | CommonJS | dist/cjs/ | Node.js / bundlers CJS | | ES Module | dist/esm/ | Bundlers modernes (Vite, etc.) | | TypeScript | dist/types/ | Déclarations de types |

Ajouter un nouveau nœud

Étendre SessionTemplateNode dans src/types/session.ts
Créer le composant dans src/components/
Brancher dans src/components/template/TemplateNodeRenderer.tsx
Gérer navigation et persistance
Ajouter styles et traductions (src/i18n/fr.json, en.json)
Écrire les tests

Voir docs/JOURNEY_NODE_BUILDER.md pour la checklist complète.

Support

Email : [email protected]
Documentation API : https://api.datakeen.co/docs
Site Web : www.datakeen.co