Intégration Capacitor

Ce guide décrit l'installation du SDK dans votre application Capacitor et le parcours de capture puis d'envoi. Consultez la présentation pour la livraison, la clé SDK et les environnements.

Prérequis

• Capacitor 7, avec ses plateformes Android et/ou iOS et les outils de build requis par Capacitor.
• Xcode et CocoaPods pour iOS ; Android Studio pour Android.
• Le package certificall-mobile-sdk-capacitor-<version>.tgz fourni par Certificall.
• Un appareil physique pour valider le parcours de production.

La capture et l'envoi fonctionnent dans l'application native iOS ou Android. Ces méthodes sont indisponibles dans le navigateur, y compris avec ionic serve.

1. Installer et synchroniser

Copiez le package reçu dans vendor/, puis déclarez la dépendance :

Vous venez de la 2.0.0 ?

Le package s'appelle désormais @certificall/mobile-sdk-capacitor : renommez la clé de dépendance et vos imports. La permission motion n'existe plus : demandez ['camera', 'location']. Le reste de l'API est inchangé.

{
  "dependencies": {
    "@certificall/mobile-sdk-capacitor": "file:./vendor/certificall-mobile-sdk-capacitor-<version>.tgz"
  }
}

npm install
npx cap sync

Le package contient les binaires natifs. cap sync installe le plugin dans les plateformes de votre application.

2. Configurer les permissions iOS

Ajoutez à Info.plist :

<key>NSCameraUsageDescription</key>
<string>Nécessaire pour la capture de photos certifiées.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Nécessaire pour certifier la localisation de la photo.</string>
<key>NSMotionUsageDescription</key>
<string>Nécessaire pour collecter les mouvements lors de la capture.</string>

Vous n'avez pas besoin de permission de photothèque. Configurez la signature de votre application dans Xcode avant de l'exécuter sur appareil.

3. Configurer Android

Déclarez les permissions dans AndroidManifest.xml :

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

Le SDK apporte son propre fournisseur de fichier et les déclarations nécessaires à la détection de la caméra. Vous n'avez pas à ajouter de FileProvider pour le SDK.

Synchronisez puis reconstruisez l'application native :

npx cap sync android
npx cap open android

Pour iOS :

npx cap sync ios
npx cap open ios

4. Demander les permissions et initialiser

Demandez les permissions avant l'initialisation, qui démarre la collecte des positions et des mouvements. Cet exemple prépare le parcours après accord pour la localisation et, sur Android, la caméra.

import { Capacitor } from '@capacitor/core';
import { CertificallTrust } from '@certificall/mobile-sdk-capacitor';

export async function prepareCapture(): Promise<boolean> {
  const permissions = await CertificallTrust.requestPermissions({
    permissions: ['camera', 'location'],
  });
  if (permissions.location !== 'granted') return false;
  if (
    Capacitor.getPlatform() === 'android' &&
    permissions.camera !== 'granted'
  ) {
    return false;
  }

  await CertificallTrust.initialize({
    apiKey: '<votre clé API SDK>',
    baseUrl: 'https://dev.certificall.app/certificall/',
    appVersion: '1.0.0',
  });
  return true;
}

Sur iOS, requestPermissions() demande la localisation ; l'autorisation caméra est gérée à l'ouverture de la caméra. Le champ camera retourné par checkPermissions() n'est pas une vérification de l'autorisation système iOS.

Appelez la préparation à l'ouverture de votre écran. appVersion est la version de votre application.

5. Capturer puis envoyer

import { CertificallTrust } from '@certificall/mobile-sdk-capacitor';

const photo = await CertificallTrust.takePhoto({
  reportToken: 'CHANTIER-2026-001',
  metadata: { site: 'Paris', zone: 'A1' },
});

// Enregistrez ce JSON dans votre stockage avant l'envoi si la capture
// doit survivre à une fermeture de l'application.
const serializedPhoto = JSON.stringify(photo);

const sent = await CertificallTrust.sendPhoto({ photo });
console.log('Dossier :', sent.caseId);
console.log('Certificat PDF :', sent.pdfUrl);
console.log('Avertissements :', sent.warnings);

La variable serializedPhoto ne constitue pas un stockage persistant. Votre application choisit comment l'enregistrer, la relire et déclencher l'envoi. Voir Conservation et réessais.

Signature de sendPhoto

Avec Capacitor, passez { photo } à sendPhoto(). Avec React Native, la capture est passée directement.

Surface de l'API

Méthode	Retour	Usage
initialize({ apiKey, baseUrl, appVersion })	Promise<void>	Configuration ; les trois paramètres sont requis.
checkPermissions()	Promise<PermissionStatus>	États déclarés par le plugin pour les permissions.
requestPermissions({ permissions })	Promise<PermissionStatus>	Demande de permissions.
takePhoto({ reportToken?, metadata? }?)	Promise<CapturedPhoto>	Capture locale avec ses signaux.
sendPhoto({ photo })	Promise<SentPhoto>	Envoi et certification.
isDebugBuild()	Promise<{ debugBuild: boolean }>	Type de build de l'application.
getNetworkStatus()	Promise<{ connected, connectionType }>	État réseau courant.
startNetworkMonitoring()	Promise<void>	Active les événements networkStatusChange.
stopNetworkMonitoring()	Promise<void>	Arrête le suivi réseau.
getCurrentPosition()	Promise<LocationPosition>	Position courante.
watchPosition(callback)	Promise<string>	Suivi de position ; retourne un identifiant.
getCurrentMotion()	Promise<MotionData>	Mouvement courant.
watchMotion(callback)	Promise<string>	Suivi des mouvements ; retourne un identifiant.
clearWatch({ id })	Promise<void>	Arrête un suivi de position ou de mouvement.
getDeviceSnapshot({ includeLocation?, includeMotion? })	Promise<DeviceSnapshot>	Instantané de l'appareil.

Pour les erreurs de capture et d'envoi, lisez error.code et les données complémentaires dans error.data : reasons, status et reason. Consultez la référence des erreurs.

Suivre le réseau

Vous pouvez utiliser les événements réseau pour décider quand traiter votre file d'envoi :

const listener = await CertificallTrust.addListener(
  'networkStatusChange',
  status => {
    console.log(status.connected, status.connectionType);
    // Si le réseau revient, votre application peut traiter sa file d'envoi.
  },
);
await CertificallTrust.startNetworkMonitoring();

// À la fin du suivi :
await CertificallTrust.stopNetworkMonitoring();
await listener.remove();

connectionType vaut wifi, cellular, none ou unknown. Un état connecté ne garantit pas que Certificall soit joignable : traitez également les erreurs de sendPhoto().

Dépannage

Symptôme	Vérification
Plugin non détecté	Relancez npm install et npx cap sync, puis reconstruisez l'application.
Capture indisponible dans le navigateur	Exécutez l'application sur iOS ou Android.
Permission Android refusée	Demandez les permissions avant initialize().
NOT_INITIALIZED	Attendez la résolution de initialize() avant la capture ou l'envoi.
DEVICE_NOT_TRUSTED	Lisez error.data.reasons et les contrôles d'appareil.
INVALID_PHOTO	Passez { photo } avec l'objet complet rendu par takePhoto().
SERVER_REJECTED	Vérifiez error.data.status, error.data.reason, la clé et l'URL d'environnement.
Photo de développement refusée	Utilisez la pré-production ; pour la production, reprenez-la avec un build de distribution.