Prise en main

Installation

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite le prompt suivant :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-device-integrity` plugin in my project.

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

1. Installer le package

   bun add @capgo/capacitor-device-integrity

2. Synchroniser les projets natifs

   bunx cap sync

3. Configurer les prérequis de la plateforme

   • Android : configurez plugins.DeviceIntegrity.cloudProjectNumber Play Integrity lors de l'utilisation des API d'attestation.
   • iOS : activez la capacité App Attest dans Xcode pour les API d'attestation.

Démarrage rapide

import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const result = await DeviceIntegrity.getCapabilities();
console.log(result);

Exemple : getWidevineFingerprint

import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const capabilities = await DeviceIntegrity.getCapabilities();
if (capabilities.widevine.fingerprintAvailable) {
  const result = await DeviceIntegrity.getWidevineFingerprint();
  console.log(result);
}

Exemple : prepareAttestation

import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const capabilities = await DeviceIntegrity.getCapabilities();
const attestationSupported =
  capabilities.appAttest.supported || capabilities.playIntegrity.supported;

if (attestationSupported) {
  const result = await DeviceIntegrity.prepareAttestation();
  console.log(result);
}

Erreurs courantes

• Sync native : exécuter npx cap sync après les mises à jour du plugin.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Pourquoi utiliser ce plugin

Utilisez un API pour collecter des signaux d'intégrité lors de l'inscription, de la connexion ou d'actions à haut risque :

• Vérifiez le support avant d'appeler les API natives (getCapabilities)
• Identifiez les appareils Android avec Widevine (getWidevineFingerprint)
• Enregistrez et affirmez avec App Attest ou Play Integrity (prepareAttestation, createAttestation, createAssertion)
• Demandez des tokens iOS DeviceCheck (getDeviceCheckToken)

Les valeurs client ne sont pas fiables tant que votre backend n'a pas vérifié les tokens et appliqué une protection contre le replay.

Utilisation

import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const capabilities = await DeviceIntegrity.getCapabilities();
console.log(capabilities.platform, capabilities.playIntegrity.supported);

if (capabilities.widevine.fingerprintAvailable) {
  const widevine = await DeviceIntegrity.getWidevineFingerprint();
  console.log(widevine.fingerprint, widevine.securityLevel);
}

const attestationSupported =
  capabilities.appAttest.supported || capabilities.playIntegrity.supported;

if (attestationSupported) {
  try {
    const prepared = await DeviceIntegrity.prepareAttestation();

    const challengeResponse = await fetch(
      'https://api.example.com/integrity/registration-challenge',
    );
    if (!challengeResponse.ok) {
      throw new Error(`Challenge request failed with ${challengeResponse.status}`);
    }
    const challengeBody = await challengeResponse.json();
    if (typeof challengeBody.challenge !== 'string' || challengeBody.challenge.length === 0) {
      throw new Error('Backend response missing challenge');
    }
    const challenge = challengeBody.challenge;

    const registration = await DeviceIntegrity.createAttestation({
      keyId: prepared.keyId,
      challenge,
    });

    const payloadResponse = await fetch(
      'https://api.example.com/integrity/assertion-payload',
    );
    if (!payloadResponse.ok) {
      throw new Error(`Payload request failed with ${payloadResponse.status}`);
    }
    const payloadBody = await payloadResponse.json();
    if (typeof payloadBody.payload !== 'string' || payloadBody.payload.length === 0) {
      throw new Error('Backend response missing payload');
    }
    const payload = payloadBody.payload;

    const assertion = await DeviceIntegrity.createAssertion({
      keyId: prepared.keyId,
      payload,
    });

    console.log(registration.format, registration.token);
    console.log(assertion.format, assertion.token);
  } catch (error) {
    console.error('Attestation flow failed', error);
  }
}

if (capabilities.deviceCheck.supported) {
  const deviceCheck = await DeviceIntegrity.getDeviceCheckToken();
  console.log(deviceCheck.token);
}

Options Widevine

getWidevineFingerprint() accepte les champs optionnels suivants :

Champ	Type	Description
includeRawId	boolean	Si true, inclut l'ID de l'appareil Widevine brut en base64 (sensible).
hashSalt	string	Sel pour fingerprint. Android utilise le nom du package de l'app s'il est omis.

Exigence backend

• Vérifiez les tokens App Attest et Play Integrity sur votre serveur.
• Treat Widevine identifiers as sensitive and disclose use in your privacy policy.
• N'utilisez pas les valeurs Widevine pour la publicité ou le tracking inter-applications.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier la sécurité et la conformité, connectez-l’à Utilisation de @capgo/capacitor-device-integrity pour la capacité native dans l'utilisation de @capgo/capacitor-device-integrity, @capgo/capacitor-app-attest pour des flux App Attest et Play Integrity ciblés, Chiffrement pour les détails d'implémentation du chiffrement, Conformité pour les détails d'implémentation dans Compliance, et Capgo et la sécurité pour le workflow produit dans Capgo Security.