Erste Schritte

Installation

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

1. Paket installieren

   bun add @capgo/capacitor-device-integrity

2. Native Projekte synchronisieren

   bunx cap sync

3. Plattform-Anforderungen konfigurieren

   • Android: festlegen plugins.DeviceIntegrity.cloudProjectNumber für Play Integrity bei der Nutzung von Attestation-APIs.
   • iOS: App Attest Capability in Xcode für Attestation-APIs aktivieren.

Quickstart

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

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

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

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

Häufige Stolperfallen

• Nativer Sync: ausführen npx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

Warum dieses Plugin nutzen?

Nutze ein API, um Integrity-Signale bei der Registrierung, beim Login oder bei risikoreichen Aktionen zu sammeln:

• Probe-Support prüfen, bevor native APIs aufgerufen werden (getCapabilities)
• Android-Geräte mit Widevine fingerprinten (getWidevineFingerprint)
• Mit App Attest oder Play Integrity registrieren und validieren (prepareAttestation, createAttestation, createAssertion)
• iOS DeviceCheck-Token anfordern (getDeviceCheckToken)

Client-Werte sind erst vertrauenswürdig, wenn dein Backend die Token verifiziert und Replay-Protection erzwingt.

Nutzung

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

Widevine-Optionen

getWidevineFingerprint() akzeptiert optionale Felder:

Feld	Typ	Beschreibung
includeRawId	boolean	Wenn true, wird die Widevine-Device-ID als Base64-Raw-String inkludiert (sensibel).
hashSalt	string	Salt für fingerprint. Android verwendet den App-Package-Namen, wenn dieser weggelassen wird.

Backend-Anforderung

• Verifiziere App Attest- und Play Integrity-Token auf deinem Server.
• Behandle Widevine-IDs als sensible Daten und deklariere deren Nutzung in deiner Datenschutzerklärung.
• Nutze Widevine-Werte nicht für Werbung oder Cross-App-Tracking.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Sicherheit und Compliance zu planen, verbinden Sie es mit Verwendung von @capgo/capacitor-device-integrity für die native Funktion in Verwendung von @capgo/capacitor-device-integrity, @capgo/capacitor-app-attest für gezielte App Attest- und Play Integrity-Flows, Verschlüsselung für die Implementierungsdetails in Encryption, Compliance für die Implementierungsdetails in Compliance, und Capgo Sicherheit für den Produkt-Workflow in Capgo Security.