Panduan Memulai

Instalasi

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

1. Install package

   bun add @capgo/capacitor-device-integrity

2. Sync proyek native

   bunx cap sync

3. Konfigurasikan persyaratan platform

   • Android: atur plugins.DeviceIntegrity.cloudProjectNumber untuk Play Integrity saat menggunakan attestation API.
   • iOS: aktifkan capability App Attest di Xcode untuk attestation API.

Mulai cepat

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

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

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

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

Kesalahan umum

• Sinkronisasi Native: jalankan npx cap sync setelah upgrade plugin.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Mengapa menggunakan plugin ini

Gunakan satu API untuk mengumpulkan sinyal integritas saat sign-up, login, atau tindakan berisiko tinggi:

• Cek dukungan probe sebelum memanggil native API (getCapabilities)
• Fingerprint perangkat Android dengan Widevine (getWidevineFingerprint)
• Register dan assert dengan App Attest atau Play Integrity (prepareAttestation, createAttestation, createAssertion)
• Request token iOS DeviceCheck (getDeviceCheckToken)

Nilai client tidak dapat dipercaya sampai backend Anda memverifikasi token dan menerapkan replay protection.

Penggunaan

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

Opsi Widevine

getWidevineFingerprint() menerima field opsional:

Field	Tipe	Deskripsi
includeRawId	boolean	Jika true, menyertakan base64 raw Widevine device ID (sensitif).
hashSalt	string	Salt untuk fingerprint. Android menggunakan nama package app jika dikosongkan.

Persyaratan backend

• Verifikasi token App Attest dan Play Integrity di server Anda.
• Anggap identifier Widevine sebagai data sensitif dan cantumkan penggunaannya di kebijakan privasi Anda.
• Jangan gunakan nilai Widevine untuk iklan atau pelacakan lintas aplikasi.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan keamanan dan kepatuhan, hubungkan dengan Menggunakan @capgo/capacitor-device-integrity untuk kapabilitas native dalam Menggunakan @capgo/capacitor-device-integrity, @capgo/capacitor-app-attest untuk alur App Attest dan Play Integrity yang lebih terfokus, Enkripsi untuk detail implementasi pada Encryption, Kepatuhan untuk detail implementasi di Compliance, dan Keamanan Capgo untuk alur kerja produk di Capgo Security.