mobile-platform-native-capabilities-integrate

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

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

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

このスキルを使用する場合

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

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

• LWC のモバイルオフライン対応のレビュー（lwc:if、インライン GraphQL、Komaci のプライミング違反）— mobile-platform-offline-validate を使用してください。
• 汎用的な Lightning ベースコンポーネント／SLDS ブループリントの選択やスタイル設定 — design-systems-slds-apply を使用してください。

前提条件

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

機能一覧

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

ワークフロー

ステップ 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つのコンポーネントで複数の機能を使用する — 機能ごとに個別のインスタンスを取得してください（独立したサービスオブジェクトです）。それらの間で状態を共有しようとしないでください。