using-mobile-native-capabilities

モバイルのネイティブ機能の使用

lightning/mobileCapabilities モジュールは、ネイティブデバイス機能（バーコードスキャン、生体認証、位置情報など）用のサービスオブジェクトを返すファクトリー関数を公開します。各サービスは共通のBaseCapabilityを拡張し、isAvailable() メソッドを備えているため、機能が利用できない環境（デスクトップ、モバイルウェブ）でも LWC が適切に動作を縮退できます。

このスキルでは、エージェントが（1）適切な機能を選び、（2）信頼できる型定義を読み込み、（3）適切な利用可否の判定、エラー処理、非推奨に配慮した API の選択とともに、サービスを LWC に組み込めるように案内します。

このスキルを使う場面

• ユーザーが、以下の一覧にあるデバイス機能を使う LWC を求めている場合。
• ユーザーが lightning/mobileCapabilities、「モバイル機能」、または「Nimbus」に言及している場合。
• ユーザーが利用可能なモバイルネイティブ API や、自分の機能に適した API を知りたい場合。

次の場合はこのスキルを使用しないでください。

• LWC のモバイルオフライン対応レビュー（lwc:if、インライン GraphQL、Komaci-priming 違反）には、reviewing-lwc-mobile-offline を使用してください。
• 汎用的な Lightning Base Components の選択には、using-lightning-base-components を使用してください。

前提条件

• LWC がサポート対象のモバイルコンテナ（Salesforce Mobile App、Field Service Mobile App）内で実行されることを把握していること。これらの機能はデスクトップおよびモバイルウェブでは利用できません。すべての呼び出しを isAvailable() で判定してください。
• lightning/mobileCapabilities モジュールの宣言に精通していること（mobile-capabilities を参照）。

機能一覧

機能	リファレンス	用途
アプリレビュー	App Review	ネイティブアプリ内でユーザーにレビューを促します。
AR 空間キャプチャ	AR Space Capture	AR を使って実空間を 3D スキャンします。
バーコードスキャナー	Barcode Scanner	カメラで QR／UPC／EAN／Code-128 などを読み取ります。
生体認証	Biometrics	Face ID／指紋認証で認証します。
カレンダー	Calendar	デバイスのカレンダーの予定を読み取るか、作成します。
連絡先	Contacts	デバイスのアドレス帳の連絡先を読み取るか、作成します。
ドキュメントスキャナー	Document Scanner	エッジ検出機能を使い、カメラで紙の書類をスキャンします。
ジオフェンシング	Geofencing	デバイスが地理的な境界を越えたときにロジックを実行します。
位置情報	Location	GPS 座標を取得し、更新を監視します。
NFC	NFC	NFC タグを読み取るか、書き込みます。
決済	Payments	Apple Pay／Google Pay で決済を受け付けます。

ワークフロー

ステップ 1 — 機能を特定する

ユーザーが求める機能を、機能一覧のいずれかの行に対応づけます。複数の機能にまたがる依頼（例：「バーコードをスキャンして連絡先に保存する」）の場合は、各機能を個別に計画してください。機能ごとにファクトリー関数が 1 つあります。

ステップ 2 — 共通リファレンスと機能別リファレンスを読み込む

以下の 2 つの共通リファレンスは、各セッションで一度だけ読んでください。すべての機能に適用され、機能別ファイルには重複して記載されていません。

• BaseCapability — すべてのサービスが拡張する、isAvailable() を備えた共通インターフェースです。
• mobile-capabilities — すべての再エクスポートされたサービスを示す lightning/mobileCapabilities モジュール宣言です。

続いて、上の表から機能のリファレンスファイルを開いてください。機能別リファレンスには、そのサービス固有の TypeScript API（ファクトリー関数、サービスインターフェース、オプション型、結果型、エラー型）が記載されており、上記 2 つの共通リファレンスがすでに参照されていることを前提としています。

API を記憶から推測せず、必ず読んでください。サービスは進化しており、新しい代替手段があるため明示的に @deprecated とされているメソッドもあります。

ステップ 3 — LWC にサービスを組み込む

各機能について、次の手順を実行します。

1. lightning/mobileCapabilities からファクトリーをインポートします。

   import { getBarcodeScanner } from 'lightning/mobileCapabilities';
   

2. インスタンスを取得します：const scanner = getBarcodeScanner();
3. isAvailable() で呼び出しをガードします。

   if (!scanner.isAvailable()) {
     // graceful fallback or user message
     return;
   }
   

4. 非推奨ではないエントリーポイントを呼び出します。複数のサービスでは、古いメソッドに @deprecated を付けたまま、推奨されるメソッドも提供しています。リファレンスに記載された推奨メソッドを必ず使用してください。
5. プロミスを try/catch で囲み、サービスが公開する型付き失敗コード（例：BarcodeScannerFailureCode、LocationServiceFailureCode）を処理します。ユーザーによるキャンセル、権限拒否、サービス利用不可は、それぞれ異なる UX 状態です。

ステップ 4 — 失敗の種類をユーザーに伝える

各サービスは独自の失敗コード列挙型を定義しています。コードをユーザーが取るべき行動につながるメッセージに変換してください。USER_DENIED_PERMISSION の場合は、ユーザーに権限の許可を求めます。USER_DISABLED_PERMISSION の場合は、OS の設定画面に移動するよう案内します。SERVICE_NOT_ENABLED は開発者が確認できるエラーとし、ユーザーには表示しないでください。

ステップ 5 — サポートされている範囲内で使用する

モバイル機能を利用できるのは、サポート対象の Salesforce モバイルアプリ内で LWC が実行されている場合のみです。同じコンポーネントがデスクトップまたはモバイルウェブでレンダリングされる場合でも、ファクトリーはオブジェクトを返しますが、isAvailable() は false を返します。利用可能だと決めつけず、すべての呼び出しを必ずガードしてください。

例

例 — 「バーコードをスキャンしてフィールドに書き込む」

1. 対応する機能：バーコードスキャナー。
2. バーコードスキャナーを読みます。
3. scan(options) を使用します（非推奨の beginCapture / resumeCapture / endCapture の組み合わせは使用しません）。
4. オプションで、必要なシンボル体系を barcodeTypes に設定します（デフォルトはサポートされているすべてのタイプです）。1 回だけ読み取る場合は enableMultiScan: false を設定します。
5. 解決時には、result[0].value をバインドされたフィールドに書き込みます。拒否時には、error.code を BarcodeScannerFailureCode と照合します。

例 — 「注文の合計金額を Apple Pay で支払う」

1. 対応する機能：Payments。
2. Paymentsを読みます。
3. isAvailable() でガードします。
4. リファレンスに従って決済リクエストオブジェクトを構築します。
5. 解決時には、呼び出し元のフローにトランザクション ID を渡します。拒否時には、ユーザーによるキャンセルと決済失敗を別々に処理します。

検証チェックリスト

• すべての機能呼び出しの前に isAvailable() を確認している。
• 非推奨ではないエントリーポイントを使用している（バーコードでは beginCapture / resumeCapture / endCapture を使用しない、など）。
• 各拒否パスを、型付き失敗コードの列挙型に対応付けている。
• インポート元がプライベートパスではなく lightning/mobileCapabilities である。
• 機能がデスクトップまたはモバイルウェブで実行されると決めつけていない。

トラブルシューティング

• 実機で isAvailable() が false を返す — デバイスでサポートされていないアプリの画面（Salesforce モバイルまたは Field Service モバイル以外）が実行されているか、組織レベルの設定によってサービスが制限されています。解決するには、コードではなく組織の設定を変更してください。
• TypeScript がインポートを見つけられない — LWC が lightning/mobileCapabilities にアクセスできることを確認してください。このモジュールは Salesforce のモバイルコンテナ内ではグローバルに宣言されていますが、それ以外の環境では型を別途インストールする必要があります。
• 非推奨のバーコードメソッドがまだ動作する — はい。ただし、新しいコードでは scan() と dismiss() を使用する必要があります。エージェントが受け取ったサンプルコードは、返す前にリファクタリングしてください。
• 1つのコンポーネントで複数の機能を使用する — 機能ごとに個別のインスタンスを取得してください（独立したサービスオブジェクトです）。それらの間で状態を共有しようとしないでください。