@capgo/capacitor-device-integrity

Collect device integrity and fraud signals in your Capacitor app: Play Integrity and a Widevine fingerprint on Android, App Attest and DeviceCheck on iOS. Your backend can verify the attestation and DeviceCheck tokens and use the Widevine fingerprint as a risk signal.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-device-integrity in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-device-integrity to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Attestation: prepareAttestation() prepares the native attestation state, then createAttestation() creates a token bound to a challenge from your backend.
• Request assertions: createAssertion() signs a request payload for server-side checks.
• Widevine fingerprint: getWidevineFingerprint() returns a stable Android DRM-derived ID.
• DeviceCheck: getDeviceCheckToken() creates an iOS token for fraud-state lookups.
• Capabilities: getCapabilities() reports what the current platform supports.
• Platforms: iOS and Android. Not available on web.

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()
• getWidevineFingerprint(...)
• prepareAttestation(...)
• createAttestation(...)
• createAssertion(...)
• getDeviceCheckToken()
• Interfaces
• Type Aliases

getCapabilities()

getCapabilities() => Promise<DeviceIntegrityCapabilities>

Returns the native integrity capabilities available on the current platform.

Returns: Promise<DeviceIntegrityCapabilities>

getWidevineFingerprint(...)

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

Returns an Android Widevine-derived fingerprint.

The default fingerprint is SHA-256 over the Widevine device unique ID and a salt. If hashSalt is not provided, Android uses the app package name as the salt.

The raw Widevine ID is sensitive and is only returned as base64 when includeRawId is true.

Returns: Promise<WidevineFingerprintResult>

prepareAttestation(...)

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

Prepares native attestation state and returns the key/provider handle.

iOS: creates an App Attest key. Android: prepares a Play Integrity Standard token provider.

Returns: Promise<PrepareAttestationResult>

createAttestation(...)

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

Creates a registration attestation token bound to a backend-issued challenge.

Returns: Promise<AttestationTokenResult>

createAssertion(...)

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

Creates a request assertion token bound to a request payload.

Returns: Promise<AttestationTokenResult>

getDeviceCheckToken()

getDeviceCheckToken() => Promise<DeviceCheckTokenResult>

Creates an iOS DeviceCheck token for server-side fraud-state lookups.

Returns: Promise<DeviceCheckTokenResult>

Interfaces

DeviceIntegrityCapabilities

WidevineCapabilities

SupportStatus

WidevineFingerprintResult

WidevineFingerprintOptions

PrepareAttestationResult

PrepareAttestationOptions

AttestationTokenResult

CreateAttestationOptions

CreateAssertionOptions

DeviceCheckTokenResult

Type Aliases

DeviceIntegrityPlatform

'android' | 'ios' | 'web'

AttestationFormat

'apple-app-attest' | 'google-play-integrity-standard'