@41devs/naya-id-angular

SDK Angular officiel de Naya ID — vérification d'identité (eKYC) clé en main pour l'Afrique de l'Ouest.

Un service injectable, un appel : consentement, capture guidée du document, selfie avec défi de vivacité imposé par le serveur, confirmation des données lues, décision expliquée — puis un NayaResult typé.

Pays : Bénin, Côte d'Ivoire, Sénégal, Mali, Burkina Faso, Togo. Documents : CNI (CEDEAO), CIP (Bénin), passeport, permis de conduire. Langues : français, anglais, portugais.

Comment c'est construit

Le parcours est celui du SDK navigateur @41devs/naya-id-js : une seule implémentation, partagée avec les intégrations sans framework. Cette bibliothèque y ajoute ce qu'attend une application Angular :

• injection — un service providedIn: 'root', testable et remplaçable ;
• chargement différé — le SDK n'entre pas dans le bundle initial (voir plus bas) ;
• zone Angular — le parcours tourne hors zone, sans quoi le flux caméra déclencherait une détection de changements à chaque trame ; vos rappels y sont ramenés, donc signaux et vues se mettent à jour normalement ;
• rendu serveur — sans document, le service rend une erreur typée au lieu de lever.

Conséquence utile : les correctifs et les nouveautés du parcours arrivent chez vous au prochain npm update, sans publication de cette bibliothèque.

Installation

npm install @41devs/naya-id-angular

@41devs/naya-id-js est installé automatiquement. Angular 19 ou 20.

Utilisation

Session ouverte par votre backend (production)

Votre serveur ouvre la vérification avec sa clé d'API — qui ne quitte jamais le serveur — puis ne confie au navigateur que verificationId et sessionToken.

import { Component, inject, signal } from '@angular/core';
import { NayaIdService, type NayaResult } from '@41devs/naya-id-angular';

@Component({ /* … */ })
export class KycComponent {
  private readonly naya = inject(NayaIdService);
  readonly result = signal<NayaResult | null>(null);

  async verify(session: { verificationId: string; sessionToken: string }) {
    this.result.set(
      await this.naya.startVerification({
        auth: session,
        config: { locale: 'fr' },
      }),
    );
  }
}

Clé de test (démo)

await this.naya.startVerification({
  auth: { apiKey: 'naya_test_xxx' },
  config: { country: 'BJ', documentTypes: ['cni'] },
});

Une clé live utilisée depuis un navigateur doit déclarer ses origines dans le dashboard, sinon l'API répond 403. Préférez la session serveur.

Instance réutilisable

const verification = await this.naya.create({ auth, config });
verification.on('step', (e) => console.log(e));
const result = await verification.open();
verification.destroy();

Résultat

startVerification ne rejette jamais : annulation et erreurs reviennent dans le NayaResult.

switch (result.status) {
  case 'approved': break;   // result.riskScore, result.ocrData…
  case 'review':   break;   // décision finale notifiée sur callbackUrl
  case 'rejected': break;   // result.reasonCodes
  case 'cancelled': break;
  case 'error':    break;   // result.errorCode, result.requestId
}

Ne vous fiez jamais au résultat rendu par le navigateur pour décider : seul le webhook (ou GET /verifications/:id avec votre clé) fait foi.

Configuration

config est le NayaConfig du SDK navigateur — pays, documents, langue, consentement, confirmation des données lues, capture, vivacité, relais QR, thème, libellés surchargeables, télémétrie, onEvent. La liste complète et à jour est dans la documentation du SDK navigateur.

Utile côté Angular :

config: {
  container: this.host.nativeElement,   // monte le parcours dans votre page
  theme: { primaryColor: '#172062', mode: 'auto', radius: 'soft' },
  strings: { welcomeTitle: 'Vérifions votre identité' },
  onEvent: (e) => this.analytics.track(e.type),  // rappelé dans la zone Angular
}

Pourquoi la bibliothèque n'exporte que des types

public-api.ts réexporte les types du SDK navigateur, jamais de valeurs. Une constante ou une fonction réexportée placerait le SDK dans le graphe statique du module, et donc dans le bundle initial de votre application : mesuré sur l'application de démonstration, 308 ko au lieu de 154 ko, soit 39 ko de transfert supplémentaires chargés par tous vos visiteurs, y compris ceux qui ne lancent jamais de vérification.

Les types disparaissent à la compilation : ils ne coûtent rien. Pour les rares valeurs utiles à un hôte, le service expose des accesseurs asynchrones :

const countries = await this.naya.countries();   // sélecteur maison
const support = await this.naya.isSupported();   // avant d'ouvrir

Dans la plupart des cas vous n'en avez pas besoin : config accepte directement les codes (country: 'BJ'), typés par NayaCountryCode.

Rendu serveur (SSR)

Le service détecte l'absence de navigateur (PLATFORM_ID) et rend un NayaResult en erreur unsupported_browser au lieu de lever. Le SDK n'est jamais importé côté serveur, puisque l'import est différé au premier lancement.

Vérifier la compatibilité du navigateur

const s = await this.naya.isSupported();
if (!s.ok) {
  // s.code : in_app_browser | insecure_context | unsupported_browser
}

Démonstration

projects/demo contient une application avec tous les réglages du parcours.

npm start

Licence

Voir LICENSE.