Getting Started

설치

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-nfc` plugin in my project.

Manual Setup을 선호하는 경우, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래에 플랫폼에 따라 설명된 지침을 따르세요.

bun add @capgo/capacitor-nfc
bunx cap sync

Import

import { CapacitorNfc } from '@capgo/capacitor-nfc';

API 개요

startScanning

NFC 태그를 듣기 시작합니다.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.startScanning();

stopScanning

__CAPGO_KEEP_0__ 중단 스캔

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.stopScanning();

write

__CAPGO_KEEP_0__ 쓰기

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.write({} as WriteTagOptions);

erase

__CAPGO_KEEP_1__

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.erase();

makeReadOnly

__CAPGO_KEEP_4__

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.makeReadOnly();

share

__CAPGO_KEEP_7__

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.share({} as ShareTagOptions);

unshare

__CAPGO_KEEP_10__

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.unshare();

getStatus

현재 NFC 어댑터 상태를 반환합니다.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.getStatus();

showSettings

시스템 설정 페이지를 열어 NFC를 활성화할 수 있는 사용자에게 NFC를 활성화하도록 안내합니다.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.showSettings();

isSupported

장치에 NFC 하드웨어 지원 여부를 확인합니다.

반환 true 장치에 NFC 하드웨어가 존재하면 NFC가 현재 활성화되어 있거나 비활성화되어 있지 않습니다. NFC 하드웨어가 장치에 존재하지 않으면 false NFC 기능을 앱의 UI에 표시하기 위해 이 메서드를 사용하여 NFC 하드웨어가 장치에 존재하는지 여부를 확인하세요. NFC가 현재 활성화되어 있는지 여부를 확인하려면

NFC getStatus().

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.isSupported();

타입 참조

StartScanningOptions

선택 항목:

export interface StartScanningOptions {
  /**
   * iOS-only: closes the NFC session automatically after the first successful tag read.
   * Defaults to `true`.
   */
  invalidateAfterFirstRead?: boolean;
  /**
   * iOS-only: custom message displayed in the NFC system sheet while scanning.
   */
  alertMessage?: string;
  /**
   * iOS-only: session type to use for NFC scanning.
   * - `'ndef'`: Uses NFCNDEFReaderSession (default). Only detects NDEF-formatted tags.
   * - `'tag'`: Uses NFCTagReaderSession. Detects both NDEF and non-NDEF tags (e.g., raw MIFARE tags).
   *            Allows reading UID from unformatted tags.
   *            **Requires** the `Near Field Communication Tag Reader Session Formats` entitlement
   *            in your app with the `TAG` format included. Without it the session will fail to
   *            start and the promise will reject with a `NO_NFC` error code.
   * Defaults to `'ndef'` for backward compatibility.
   */
  iosSessionType?: 'ndef' | 'tag';
  /**
   * Android-only: raw flags passed to `NfcAdapter.enableReaderMode`.
   * Defaults to enabling all tag types with skipping NDEF checks.
   */
  androidReaderModeFlags?: number;
}

WriteTagOptions

현재 태그에 NDEF 메시지를 쓰기 위한 옵션입니다.

export interface WriteTagOptions {
  /**
   * Array of records that compose the NDEF message to be written.
   */
  records: NdefRecord[];
  /**
   * When `true`, the plugin attempts to format NDEF-formattable tags before writing.
   * Defaults to `true`.
   */
  allowFormat?: boolean;
}

ShareTagOptions

다른 장치와 Android Beam / P2P 모드에서 NDEF 메시지를 공유할 때 사용하는 옵션입니다.

export interface ShareTagOptions {
  records: NdefRecord[];
}

NfcStatus

NFC 어댑터 상태 중 하나입니다.

export type NfcStatus = 'NFC_OK' | 'NO_NFC' | 'NFC_DISABLED' | 'NDEF_PUSH_DISABLED';

NfcEvent

NFC 디스커버리 이벤트입니다.

export interface NfcEvent {
  type: NfcEventType;
  tag: NfcTag;
}

NfcStateChangeEvent

NFC 어댑터가 사용 가능/사용 불가 상태가 변경될 때 발생하는 이벤트입니다.

export interface NfcStateChangeEvent {
  status: NfcStatus;
  enabled: boolean;
}

NdefRecord

NDEF 레코드의 JSON 구조입니다.

export interface NdefRecord {
  /**
   * Type Name Format identifier.
   */
  tnf: number;
  /**
   * Type field expressed as an array of byte values.
   */
  type: number[];
  /**
   * Record identifier expressed as an array of byte values.
   */
  id: number[];
  /**
   * Raw payload expressed as an array of byte values.
   */
  payload: number[];
}

NfcEventType

NFC 발견 유형에 대한 설명입니다.

export type NfcEventType = 'tag' | 'ndef' | 'ndef-mime' | 'ndef-formatable';

NfcTag

native layers에서 반환된 전체 태그 정보의 표현입니다.

export interface NfcTag {
  /**
   * Raw identifier bytes for the tag.
   */
  id?: number[];
  /**
   * List of Android tech strings (e.g. `android.nfc.tech.Ndef`).
   */
  techTypes?: string[];
  /**
   * Human readable tag type when available (e.g. `NFC Forum Type 2`, `MIFARE Ultralight`).
   */
  type?: string | null;
  /**
   * Maximum writable size in bytes for tags that expose NDEF information.
   */
  maxSize?: number | null;
  /**
   * Indicates whether the tag can be written to.
   */
  isWritable?: boolean | null;
  /**
   * Indicates whether the tag can be permanently locked.
   */
  canMakeReadOnly?: boolean | null;
  /**
   * Array of NDEF records discovered on the tag.
   */
  ndefMessage?: NdefRecord[] | null;
}

실제 원본

이 페이지는 플러그인의 src/definitions.ts. upstream에서 API가 변경되면 다시 동기화하세요.

Getting Started에서 계속

If you are using Getting Started to plan dashboard and API operations, connect it with Using @capgo/capacitor-nfc for the native capability in Using @capgo/capacitor-nfc, API Overview for the implementation detail in API Overview, Introduction for the implementation detail in Introduction, API Keys for the implementation detail in API Keys, and __CAPGO_KEEP_0__ Devices __CAPGO_KEEP_0__의 구현 세부 사항입니다.