Primeros pasos

Instalación

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando los siguientes comandos y sigue las instrucciones específicas para cada plataforma a continuación:

1. Instala el paquete

   bun add @capgo/capacitor-device-integrity

2. Sincroniza proyectos nativos

   bunx cap sync

3. Configura los requisitos de la plataforma

   • Android: establece plugins.DeviceIntegrity.cloudProjectNumber para Play Integrity al usar APIs de attestation.
   • iOS: habilita la capacidad App Attest en Xcode para APIs de attestation.

Inicio rápido

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

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

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

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

Errores comunes

• Sync nativo: ejecutar npx cap sync tras actualizar los plugins.
• Fuente de verdad: confiar src/definitions.ts en el repo de GitHub.

Por qué usar este plugin

Usa un API para recolectar señales de integridad durante el registro, login o acciones de alto riesgo:

• Soporte de probe antes de llamar a APIs nativas (getCapabilities)
• Fingerprint de dispositivos Android con Widevine (getWidevineFingerprint)
• Registro y validación con App Attest o Play Integrity (prepareAttestation, createAttestation, createAssertion)
• Solicitud de tokens de iOS DeviceCheck (getDeviceCheckToken)

Los valores del cliente no son confiables hasta que tu backend verifique los tokens y aplique protección contra replay.

Uso

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

Opciones de Widevine

getWidevineFingerprint() acepta campos opcionales:

Campo	Tipo	Descripción
includeRawId	boolean	Si es true, incluye el ID de dispositivo Widevine en base64 (sensible).
hashSalt	string	Salt para fingerprint. Android usa el package name de la app si se omite.

Requisito del backend

• Verifica los tokens de App Attest y Play Integrity en tu servidor.
• Trata los identificadores de Widevine como datos sensibles y declara su uso en tu política de privacidad.
• No utilices los valores de Widevine para publicidad o tracking entre apps.

Continúa desde Primeros pasos

Si estás usando Primeros pasos para planificar la seguridad y el cumplimiento, conéctalo con Usando @capgo/capacitor-device-integrity para la capacidad nativa en Usando @capgo/capacitor-device-integrity, @capgo/capacitor-app-attest para flujos de App Attest y Play Integrity enfocados, Cifrado para los detalles de implementación en Encryption, Cumplimiento para los detalles de implementación en Compliance, y Seguridad de Capgo para el flujo de trabajo de producto en Capgo Security.