Per iniziare

Installazione

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

1. Installa il pacchetto

   bun add @capgo/capacitor-device-integrity

2. Sincronizza i progetti nativi

   bunx cap sync

3. Configura i requisiti della piattaforma

   • Android: imposta plugins.DeviceIntegrity.cloudProjectNumber per Play Integrity quando usi le API di attestation.
   • iOS: abilita la capability App Attest in Xcode per le API di attestation.

Avvio rapido

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

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

Esempio: 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);
}

Esempio: 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);
}

Errori comuni

• Sync nativo: esegui npx cap sync dopo gli aggiornamenti dei plugin.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Perché usare questo plugin

Usa un API per raccogliere segnali di integrità durante la registrazione, il login o azioni ad alto rischio:

• Verifica il supporto prima di chiamare le API native (getCapabilities)
• Fingerprint dei dispositivi Android con Widevine (getWidevineFingerprint)
• Registrazione e asserzione con App Attest o Play Integrity (prepareAttestation, createAttestation, createAssertion)
• Richiesta di token iOS DeviceCheck (getDeviceCheckToken)

I valori client non sono affidabili finché il tuo backend non verifica i token e applica la protezione dal replay.

Utilizzo

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);
}

Opzioni Widevine

getWidevineFingerprint() accetta campi opzionali:

Campo	Tipo	Descrizione
includeRawId	boolean	Se true, include l'ID dispositivo Widevine raw in base64 (sensibile).
hashSalt	string	Salt per fingerprint. Android usa il nome del package dell'app se omesso.

Requisiti backend

• Verifica i token App Attest e Play Integrity sul tuo server.
• Tratta gli identificativi Widevine come dati sensibili e dichiarane l'uso nella privacy policy.
• Non utilizzare i valori Widevine per pubblicità o cross-app tracking.

Continua da Getting Started

Se stai usando Per iniziare per pianificare sicurezza e compliance, collegalo a Utilizzo di @capgo/capacitor-device-integrity per la funzionalità nativa in Utilizzo di @capgo/capacitor-device-integrity, @capgo/capacitor-app-attest per i flussi App Attest e Play Integrity focalizzati, Crittografia per i dettagli di implementazione della crittografia, Conformità per i dettagli implementativi in Compliance, e Sicurezza Capgo per il workflow di prodotto in Capgo Security.