@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

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.. | v8.. | Yes | | v7.. | v7.. | On demand | | v6.. | v6.. | On demand |

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.

| Param | Type | | ------------- | --------------------------------------------------------------------------------- | | options | WidevineFingerprintOptions |

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.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | PrepareAttestationOptions |

Returns: Promise<PrepareAttestationResult>

createAttestation(...)

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

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

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | CreateAttestationOptions |

Returns: Promise<AttestationTokenResult>

createAssertion(...)

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

Creates a request assertion token bound to a request payload.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | CreateAssertionOptions |

Returns: Promise<AttestationTokenResult>

getDeviceCheckToken()

getDeviceCheckToken() => Promise<DeviceCheckTokenResult>

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

Returns: Promise<DeviceCheckTokenResult>

Interfaces

DeviceIntegrityCapabilities

| Prop | Type | Description | | ------------------- | --------------------------------------------------------------------------- | ---------------------------------------- | | platform | DeviceIntegrityPlatform | Platform currently executing the plugin. | | widevine | WidevineCapabilities | Android Widevine DRM support. | | appAttest | SupportStatus | iOS App Attest support. | | deviceCheck | SupportStatus | iOS DeviceCheck support. | | playIntegrity | SupportStatus | Android Play Integrity support. |

WidevineCapabilities

| Prop | Type | Description | | -------------------------------- | -------------------- | ----------------------------------------------------------- | | supported | boolean | Whether the Widevine DRM scheme is supported by the device. | | fingerprintAvailable | boolean | Whether the Widevine device unique ID can be read. | | securityLevelScanSupported | boolean | Whether the Widevine security level property can be read. |

SupportStatus

| Prop | Type | Description | | --------------- | -------------------- | ---------------------------------------------------------- | | supported | boolean | Whether the capability is available on the current device. |

WidevineFingerprintResult

| Prop | Type | Description | | ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------- | | platform | 'android' | Always android. | | source | 'widevine' | Always widevine. | | fingerprint | string | Salted SHA-256 fingerprint for storing alongside a user record. | | widevineIdSha256 | string | Unsalted SHA-256 hash of the Widevine device unique ID. | | widevineIdBase64 | string | Raw Widevine device unique ID encoded as base64. Returned only when includeRawId is true. | | securityLevel | string | Widevine security level when available, for example L1 or L3. | | vendor | string | DRM vendor when available. | | version | string | DRM plugin version when available. | | description | string | DRM plugin description when available. |

WidevineFingerprintOptions

| Prop | Type | Description | | ------------------ | -------------------- | ------------------------------------------------------------------------------------------- | | includeRawId | boolean | Return the raw Widevine device unique ID as base64. Defaults to false. | | hashSalt | string | Optional salt used to derive fingerprint. Android uses the app package name when omitted. |

PrepareAttestationResult

| Prop | Type | Description | | ------------ | --------------------------------------------------------------- | ------------------------------------------------------------------- | | keyId | string | iOS App Attest key ID or Android Play Integrity provider handle ID. | | format | AttestationFormat | Native attestation format used by the current platform. |

PrepareAttestationOptions

| Prop | Type | Description | | ------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | cloudProjectNumber | string | Android only. Google Cloud project number for Play Integrity. Can be configured globally via plugins.DeviceIntegrity.cloudProjectNumber. |

AttestationTokenResult

| Prop | Type | Description | | ------------ | --------------------------------------------------------------- | ------------------------------------------------------- | | token | string | Token/assertion that must be verified server-side. | | keyId | string | Key/provider handle used to create the token. | | format | AttestationFormat | Native attestation format used by the current platform. |

CreateAttestationOptions

| Prop | Type | Description | | ------------------------ | ------------------- | ------------------------------------------------------------- | | keyId | string | Key/provider handle returned from prepareAttestation(). | | challenge | string | Backend-issued one-time challenge. | | cloudProjectNumber | string | Android only. Google Cloud project number for Play Integrity. |

CreateAssertionOptions

| Prop | Type | Description | | ------------------------ | ------------------- | ------------------------------------------------------------- | | keyId | string | Key/provider handle returned from prepareAttestation(). | | payload | string | Backend-issued one-time request payload or nonce. | | cloudProjectNumber | string | Android only. Google Cloud project number for Play Integrity. |

DeviceCheckTokenResult

| Prop | Type | Description | | ----------- | ------------------- | ---------------------------------------- | | token | string | iOS DeviceCheck token encoded as base64. |

Type Aliases

DeviceIntegrityPlatform

'android' | 'ios' | 'web'

AttestationFormat

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