スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いのAIツールに Capgo のスキルを追加してください：

bunx 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.

手動セットアップを希望する場合は、以下のコマンドを実行してプラグインをインストールし、下記のプラットフォーム別の手順に従ってください：

bun add @capgo/capacitor-nfc
bunx cap sync

インポート

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

クイックスタート

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

await CapacitorNfc.startScanning();

例: stopScanning

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

await CapacitorNfc.stopScanning();

例: write

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

await CapacitorNfc.write({
  records: [
    {
      tnf: 1,
      type: [1],
      id: [1],
      payload: [1],
    },
  ],
});

よくある落とし穴

• リスナー: 画面がアンマウントされたらハンドルを削除します。
• ネイティブ同期: 実行 bunx cap sync プラグインのアップグレード後。
• 信頼できる情報源: 信頼 src/definitions.ts GitHub リポジトリ内。

API の概要

startScanning

NFCタグの読み取りを開始します。

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

await CapacitorNfc.startScanning();

stopScanning

実行中のNFCスキャンセッションを停止します。

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

await CapacitorNfc.stopScanning();

write

最後に検出されたタグに指定したNDEFレコードを書き込みます。

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

await CapacitorNfc.write({
  records: [
    {
      tnf: 1,
      type: [1],
      id: [1],
      payload: [1],
    },
  ],
});

erase

空のNDEFメッセージを書き込むことで、最後に検出されたタグの消去を試みます。

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

await CapacitorNfc.erase();

makeReadOnly

最後に検出されたタグを読み取り専用に設定することを試みます。

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

await CapacitorNfc.makeReadOnly();

share

ピアツーピアで他のデバイスとNDEFメッセージを共有します（Androidのみ）。

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

await CapacitorNfc.share({
  records: [
    {
      tnf: 1,
      type: [1],
      id: [1],
      payload: [1],
    },
  ],
});

unshare

先に指定したNDEFメッセージの共有を停止します（Androidのみ）。

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

await CapacitorNfc.unshare();

getStatus

現在のNFCアダプターの状態を返します。

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

const result = await CapacitorNfc.getStatus();
console.log(result);

showSettings

ユーザーがNFCを有効にできるシステム設定ページを開きます。

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

await CapacitorNfc.showSettings();

isSupported

デバイスがNFCハードウェアをサポートしているかを確認します。

戻り値 true NFCが現在有効か無効かに関わらず、デバイスにNFCハードウェアが搭載されている場合に返します。 false デバイスにNFCハードウェアが搭載されていない場合。

アプリのUIにNFC機能を表示すべきかどうかを判断するには、このメソッドを使用してください。NFCが現在有効かどうかを確認するには、 getStatus().

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

const result = await CapacitorNfc.isSupported();
console.log(result);

型リファレンス

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

ネイティブレイヤーから返されるタグ情報全体を表します。

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

Source of Truth

このページはプラグインの src/definitions.tsから生成されています。upstream で公開 API が変更されたら、再度 sync を実行してください。

Getting Startedの続きを進める

使用している場合 スタートガイド ダッシュボードと API の運用を計画するには、これを次と連携させます @capgo/capacitor-nfc の使い方 「@capgo/capacitor-nfc の使い方」のネイティブ機能については、 API の概要 「API の概要」の実装の詳細については、 はじめに 「はじめに」における実装の詳細については、 API キー および「API Keys」の実装の詳細については、 デバイス 実装の詳細については Devices を参照してください。