@capgo/capacitor-device-integrity

Device integrity and fraud signals for Capacitor:

• Android: Widevine DRM fingerprint and Play Integrity Standard API attestation.
• iOS: Apple App Attest and DeviceCheck.
• Web: unsupported fallback that reports no native capabilities.

Security model

This plugin is designed for fraud and abuse detection. It does not make client-side values trustworthy by itself.

• Verify App Attest and Play Integrity tokens on your backend.
• Treat Widevine values as sensitive identifiers.
• Disclose identifier use in your privacy policy.
• Do not use Android Widevine values for advertising or cross-app tracking.
• Do not attempt iOS fingerprinting. Apple does not provide a public review-safe stable device ID for this use case.

Compatibility

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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

Then use the following prompt:

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

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-device-integrity
npx cap sync

Platform setup

Android

Widevine fingerprinting does not require extra permissions.

Play Integrity requires Google Play services and a Cloud project number:

// capacitor.config.ts
plugins: {
  DeviceIntegrity: {
    cloudProjectNumber: '123456789012'
  }
}

You can also pass cloudProjectNumber directly to the attestation methods.

iOS

Enable the App Attest capability in Xcode:

1. Open your app target.
2. Go to Signing & Capabilities.
3. Add App Attest.
4. Test on a physical device when validating real App Attest and DeviceCheck behavior.

Usage

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

const capabilities = await DeviceIntegrity.getCapabilities();

if (capabilities.platform === 'android' && capabilities.widevine.fingerprintAvailable) {
  const widevine = await DeviceIntegrity.getWidevineFingerprint();
  await api.saveDeviceSignal({
    widevineIdSha256: widevine.widevineIdSha256,
    fingerprint: widevine.fingerprint,
    securityLevel: widevine.securityLevel,
  });
}

if (capabilities.appAttest.supported || capabilities.playIntegrity.supported) {
  const prepared = await DeviceIntegrity.prepareAttestation();
  const challenge = await api.createDeviceChallenge();

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

  await api.verifyDeviceAttestation(attestation);
}

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

Backend handling

Store the platform-specific evidence with the user record only after server-side checks:

• Android Widevine: store widevineIdSha256 and optionally the raw widevineIdBase64 only when you explicitly need it.
• Android Play Integrity: decode the returned token with Google's server API and validate request hash, package name, certificate digest, and device/app integrity verdicts.
• iOS App Attest: verify the attestation object/assertion against Apple's App Attest rules, app identity, nonce, public key, and counter.
• iOS DeviceCheck: send the token to Apple's DeviceCheck server API and maintain fraud bits on your backend.

API

getCapabilities() => Promise<DeviceIntegrityCapabilities>

getWidevineFingerprint(options?: WidevineFingerprintOptions | undefined) => Promise<WidevineFingerprintResult>

prepareAttestation(options?: PrepareAttestationOptions | undefined) => Promise<PrepareAttestationResult>

createAttestation(options: CreateAttestationOptions) => Promise<AttestationTokenResult>

createAssertion(options: CreateAssertionOptions) => Promise<AttestationTokenResult>

getDeviceCheckToken() => Promise<DeviceCheckTokenResult>