시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

1. 패키지 설치

   bun add @capgo/capacitor-device-integrity

2. 네이티브 프로젝트 동기화

   bunx cap sync

3. 플랫폼 요구 사항 설정

   • Android: 설정 plugins.DeviceIntegrity.cloudProjectNumber attestation API를 사용할 때 Play Integrity를 위한 설정입니다.
   • iOS: attestation API 사용을 위해 Xcode에서 App Attest capability를 활성화하세요.

빠른 시작

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

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

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

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

자주 하는 실수

• 네이티브 동기화: 실행 npx cap sync 플러그인 업그레이드 후.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

이 플러그인을 사용하는 이유

다음과 같은 상황에서 무결성 신호를 수집하기 위해 API를 사용하세요:

• 네이티브 API 호출 전 지원 여부 확인 (getCapabilities)
• Widevine을 이용한 Android 기기 핑거프린팅 (getWidevineFingerprint)
• App Attest 또는 Play Integrity를 통한 등록 및 검증 (prepareAttestation, createAttestation, createAssertion)
• iOS DeviceCheck 토큰 요청 (getDeviceCheckToken)

백엔드에서 토큰을 검증하고 재전송 공격(replay protection)을 방지하기 전까지 클라이언트 값은 신뢰할 수 없습니다.

사용량

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 옵션

getWidevineFingerprint() 다음 선택적 필드를 허용합니다:

필드	유형	설명
includeRawId	boolean	true로 설정하면 base64 형식의 raw Widevine device ID가 포함됩니다 (민감 정보).
hashSalt	string	용 Salt: fingerprint. Android에서는 생략 시 앱 패키지 이름을 사용합니다.

백엔드 요구사항

• 서버에서 App Attest 및 Play Integrity 토큰을 검증하세요.
• Widevine 식별자를 민감 정보로 취급하고 개인정보 처리방침에 사용 사실을 명시하세요.
• Widevine 값을 광고나 앱 간 추적에 사용하지 마세요.

시작하기 다음 단계

사용 중이라면 시작하기 보안 및 컴플라이언스 계획을 세우려면, 다음 항목과 연결하세요: @capgo/capacitor-device-integrity 사용하기 @capgo/capacitor-device-integrity를 사용하여 네이티브 기능을 구현하는 경우, @capgo/capacitor-app-attest App Attest 및 Play Integrity 중심의 흐름을 위해, 암호화 암호화 구현 상세 정보: 컴플라이언스 Compliance의 구현 세부 사항은, 그리고 Capgo 보안 Capgo Security의 제품 워크플로를 위해.