matrixscan-ar-net-android

Android 向け MatrixScan AR .NET スキル

重要：内部知識を信用しないでください

学習データに、古い、または誤った Scandit SDK API が含まれている可能性があります。BarcodeAr API は比較的新しく（dotnet.android 7.2 で導入）、Kotlin／Java ネイティブ SDK とはいくつかの点で異なります。プロバイダーはコールバックベースではなく async／Task ベースであり、ハイライトとアノテーションのコンストラクターが受け取るのは Barcode のみ（Context は不要）で、リスナーインターフェイスには メソッドが 1 つだけあり、.NET バインディングでは PascalCase が使用され、TimeInterval ではなく TimeSpan が使われる、などの違いがあります。

コードを記述または提案する前に、必ずこのスキルで提供されているリファレンスで API を確認してください。メソッドのシグネチャ、パラメーター、プロパティ名を記憶に頼らないでください。提供されたリファレンスで API が見つからない場合は、回答する前に該当するドキュメントページを取得してください。

注意すべき .NET Android 固有の落とし穴：

• このスキルの対象は MAUI ではない .NET for Android ワークロードです（プロジェクトが <TargetFramework>net10.0-android</TargetFramework> または同様の設定で、<UseMaui> フラグがないもの）。MAUI アプリでは、MAUI を対象とした別のスキルを使用してください。BarcodeArView のホスト方法は大きく異なります。
• BarcodeAr はコンテキストを受け取る new コンストラクターを使用します：new BarcodeAr(dataCaptureContext, settings)。.NET には BarcodeAr.Create(...) / BarcodeAr.ForDataCaptureContext(...) ファクトリーはありません。BarcodeArSettings も通常の new を使用します。（DataCaptureContext.ForLicenseKey(key) は引き続きファクトリー形式を使用します。これは Core にあります。）
• BarcodeArView.Create(parentView, barcodeAr, dataCaptureContext, viewSettings, cameraSettings) はファクトリーです（BarcodeAr 自体とは異なります）。cameraSettings 引数は null 許容です。BarcodeAr.RecommendedCameraSettings を使用するには null を渡してください。parentView は Android.Views.View / ViewGroup（通常は FrameLayout またはアクティビティのルートコンテンツビュー）です。BarcodeArCoordinatorLayout はありません。このコンテナーは SparkScan 専用です。BarcodeArView は、渡された任意の ViewGroup に自身を追加します。
• BarcodeArView は IDisposable を実装しますが、それ自体は Android の View ではありません。 このクラスは、必要に応じて（ネイティブ相互運用など）Android.Views.View に変換する public static implicit operator View(BarcodeArView view) を宣言していますが、自分でビュー階層に追加する必要はありません。Create ファクトリーが自動的に parentView に追加します。
• ビューのライフサイクルでは barcodeArView.OnResume() / barcodeArView.OnPause() を使用します。これらは Android 専用メソッド（バインディング内で #if __ANDROID__ により条件付きコンパイル）であり、アクティビティの OnPause / OnResume とは異なります。アクティビティの呼び出しをこれらに転送してください。.NET の BarcodeArView に OnDestroy() はありません。代わりに Dispose() を呼び出してください（アクティビティの OnDestroy または Dispose 内で）。
• IBarcodeArListener にあるメソッドは 1 つだけです： OnSessionUpdated(BarcodeAr, BarcodeArSession, IFrameData)。Kotlin の BarcodeArListener にあるような OnObservationStarted / OnObservationStopped コールバックはありません。これらを実装するとコンパイルエラーになります。このインターフェイスには宣言されていません。
• 慣用的な C# では、リスナーインターフェイスよりもイベント API（barcodeAr.SessionUpdated += handler）を優先してください。ハンドラーは BarcodeAr、Session、FrameData を含む BarcodeArEventArgs を受け取ります。他のプラットフォームとの互換性のため、AddListener(IBarcodeArListener) も引き続き使用できます。
• OnSessionUpdated / SessionUpdated はバックグラウンドの認識スレッドで実行されます。 UI を更新する場合は RunOnUiThread(() => { … }) を使ってディスパッチしてください。
• プロバイダーインターフェイスは非同期であり、コールバックベースではありません。 IBarcodeArHighlightProvider.HighlightForBarcodeAsync(Barcode) は Task<IBarcodeArHighlight?> を返し、IBarcodeArAnnotationProvider.AnnotationForBarcodeAsync(Barcode) は Task<IBarcodeArAnnotation?> を返します。Callback パラメーターや callback.OnData(...) メソッドを探さないでください。.NET バインディングにはありません。特定のバーコードのハイライト／アノテーションを抑制するには、Task.FromResult<IBarcodeArHighlight?>(null) を返すか、async メソッドから null を返してください。
• ハイライトとアノテーションのコンストラクターが受け取るのは Barcode だけです。Context 引数はありません。new BarcodeArRectangleHighlight(barcode)、new BarcodeArCircleHighlight(barcode, BarcodeArCircleHighlightPreset.Dot)、new BarcodeArInfoAnnotation(barcode)、new BarcodeArStatusIconAnnotation(barcode)、new BarcodeArPopoverAnnotation(barcode, buttons) を使用してください。Context を渡すとコンパイルエラーになります。
• シンボロジー名は C# の PascalCase です：Symbology.Ean13Upca、Symbology.Ean8、Symbology.Code128、Symbology.Code39、Symbology.Qr、Symbology.DataMatrix、Symbology.InterleavedTwoOfFive。Kotlin のアンダースコア形式（EAN13_UPCA）ではありません。
• BarcodeArSettings には Enabled 切り替え機能がありません。BarcodeAr 自体にも Enabled プロパティはありません。スキャンを一時停止／再開するには、barcodeArView.Pause() / barcodeArView.Start() を使用してください。
• .NET の BarcodeArViewSettings は最小限の設定です。 プロパティは SoundEnabled、HapticEnabled、DefaultCameraPosition の 3 つだけです。TriggerButtonCollapseTimeout、InactiveStateTimeout、ToastSettings、DefaultMiniPreviewSize のようなプロパティを作らないでください。これらは BarcodeAr ではなく SparkScan のものです。
• BarcodeArFeedback は Scandit.DataCapture.Barcode.Ar.Feedback にあり、Core.Common.Feedback.Feedback 型のプロパティ Scanned と Tapped を持ちます。引数なしのコンストラクター new BarcodeArFeedback() は、両方のイベントが無音のフィードバックオブジェクトを生成します。これを barcodeAr.Feedback に代入すると、デフォルトのビープ音／バイブレーションが無効になります。デフォルトに戻すには、静的な BarcodeArFeedback.DefaultFeedback を使用してください。（注：.NET では静的プロパティであり、Kotlin の BarcodeArFeedback.defaultFeedback() メソッドではありません。）
• ハイライトのタップ操作は、BarcodeArView の HighlightForBarcodeTapped イベント（EventHandler<HighlightForBarcodeTappedEventArgs>）として公開されています。.NET の BarcodeArView に UiListener プロパティはありません。Kotlin の IBarcodeArViewUiListener は、代わりに C# イベントとして公開されています。イベント引数には BarcodeAr、Barcode、Highlight が含まれます。
• barcodeAr.Feedback はプロパティ（get/set）です。ApplySettingsAsync(BarcodeArSettings) は Task を返します。BarcodeAr.RecommendedCameraSettings はメソッドではなく静的プロパティです（Kotlin SDK では BarcodeAr.createRecommendedCameraSettings() として公開されますが、.NET では getter です）。
• .NET API ツリーに BarcodeArFilter / SetBarcodeFilter はありません。 Kotlin/iOS の setBarcodeFilter(...) メソッド（8.1 で追加）は、現時点では dotnet.android では公開されていません。使用しないでください。
• SDK 8.0 以降では明示的な初期化が必要です。 Android.App.Application をサブクラス化し、[Application] を付与して、Scandit のコードが実行される前に OnCreate() で ScanditCaptureCore.Initialize() と ScanditBarcodeCapture.Initialize() を呼び出してください。これを行わないと、DI コンテナーに登録がないため、最初の new BarcodeAr(...) / BarcodeArView.Create(...) 呼び出し時に起動エラーが発生します。6.x / 7.x では不要です。 完全な MainApplication.cs のテンプレートについては、references/integration.md を参照してください。
• NuGet パッケージは Scandit.DataCapture.Core と Scandit.DataCapture.Barcode です。ここでは個別の *.Maui パッケージはありません。これらは MAUI プロジェクト専用です。学習データからバージョンを推測しないでください。固定する前に WebFetch を使い、https://www.nuget.org/packages/Scandit.DataCapture.Barcode/ から最新の安定版を取得してください。存在しないバージョン（例：8.4.0 しか公開されていないのに 8.13.0 を指定）を作り上げると、dotnet restore が Unable to find package Scandit.DataCapture.Core with version (>= …) で失敗します。手順全体については、references/integration.md のステップ 0 を参照してください。
• Android の SupportedOSPlatformVersion は 24 以上である必要があります。 .csproj で設定してください。これより低い値では、uses-sdk:minSdkVersion 21 cannot be smaller than version 24 declared in library というエラーでビルドに失敗します。
• [Activity] が付与されたクラスの <activity> 要素を AndroidManifest.xml に宣言しないでください。 [Activity(MainLauncher = true, ...)] 属性は .NET for Android における正式な登録方法です。ビルド時に .NET から導出された Java クラス名を使って、正しい名前のエントリーが最終的なマニフェストにマージされます。手動で <activity android:name=".MainActivity"> を追加すると、<ApplicationId> を基準に解決され、生成されたクラスと一致しないため、起動時に ClassNotFoundException: Didn't find class ... .MainActivity が発生します。マニフェストに追加するのは、スキルが明示的に指定する要素（<uses-feature>、<uses-permission>）だけにしてください。アクティビティは属性に任せてください。
• 実行時のカメラ権限ヘルパー（CameraPermissionActivity）は AppCompatActivity を継承しているため、.csproj に Xamarin.AndroidX.AppCompat が必要です。バージョンを固定する場合は、Xamarin のパッチリビジョンを含む利用可能な最も高いバージョン（例：1.7.0 ではなく 1.7.0.5）を選んでください。.X サフィックスは Xamarin バインディングレベルの更新を示し、重要な推移的依存関係の修正が含まれています。
• アクティビティには Theme.AppCompat の派生テーマが必要です。 アクティビティが AppCompatActivity を継承するため、[Activity] 属性に Theme = "@style/Theme.AppCompat.Light.NoActionBar" を設定するか、マニフェストの <application> に android:theme=... を設定してください。設定しないと、起動時に SetContentView が IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity をスローします。dotnet new android テンプレートのデフォルトテーマは AppCompat ベースではないため、明示的な設定が必要です。

インテントの振り分け

ユーザーのリクエストに基づき、回答する前に適切なリファレンスファイルを読み込んでください。

• BarcodeAr を一から統合する、設定を行う、ハイライトや注釈をカスタマイズする、セッション更新に対応する、フィードバックをカスタマイズする、またはタップ操作を設定する場合（例：「.NET Android アプリに MatrixScan AR を追加する」「C# でバーコード AR スキャンを設定する」「追跡中のすべてのバーコードに四角形のハイライトを表示する」「バーコードデータを含む情報注釈を表示する」「ビープ音を消す」「ハイライトのタップに反応する」「円形のハイライトに切り替える」）→ references/integration.md を読み、記載された手順に従ってください。
• 既存の MatrixScan AR 統合を移行またはアップグレードする場合（例：「v7 から v8 にアップグレードする」「Scandit .NET SDK を v8 に上げる」「BarcodeAr に関して SDK バージョン間で何が変わったか」「8.x に移行するときに BarcodeAr のコードを変更する必要があるか」）→ references/migration.md を読み、記載された手順に従ってください。

API の使用ポリシー

以下の Scandit リファレンスに明示的に記載された API のみを使用してください。メソッドのシグネチャ、パラメーター、プロパティ名を創作したり、推測したりしないでください。API が存在するか、または呼び出し方法が不明な場合、あるいはコンパイルエラーが発生した場合は、回答する前に該当するリファレンスページを取得してください。ユーザーに自分でドキュメントを確認するよう伝えてはいけません。回答後は、ユーザーがさらに調べられるよう、必ず関連リンクを含めてください。

ドキュメントの URL を決して組み立てたり、推測したりしないでください。 特定のクラスまたはプロパティの API ページが必要な場合：

1. まず、すでに取得したページにそのページへの直接リンクがないか確認してください。トピックページには関連する API シンボルへの直接リンクがあります。取得を依頼する際は、必ずリンクも含めるようにしてください。
2. 直接リンクが見つからない場合は、API インデックス（以下の表の API リファレンス全体 を参照）を取得し、そこから実際のリンクを抽出して開いてください。

URL の構造は変わることがあります（例：api/ui/ サブディレクトリ）。推測すると 404 エラーにつながります。

ライセンスキー

スキャンには Scandit のライセンスキーが必要です。このスキルでは、ライセンスの製品は native、プラットフォームは android です。

以下の順に進めてください。MCP の利用可否を理由にユーザーを待たせてはいけません。

1. Scandit MCP サーバーが接続されている場合 — 製品に native、プラットフォームに android を指定して ensure_scanner_setup を呼び出し、次に get_license_env_command が返すコマンドを実行して、キーをプロジェクトの .env に書き込みます。チャットに表示するのは、最大でも一部を伏せたプレビューのみとし、キー全体を決して表示しないでください。

2. 接続されていない場合 — 一度接続する方法を案内し、その後は手順 1 に進んでください。

   • Claude Code：claude mcp add --transport http scandit https://ssl.scandit.com/mcp
   • Cursor：{"mcpServers": {"scandit": {"url": "https://ssl.scandit.com/mcp"}}} を ~/.cursor/mcp.json に追加します
   • VS Code：MCP ユーザー設定に {"servers": {"scandit": {"type": "http", "url": "https://ssl.scandit.com/mcp"}}} を追加します

   認証はブラウザー経由のため、ヘッドレス環境または CI ではサポートされていません。サーバーが発行するのはトライアルキーのみです。本番用ライセンスの作成、取り消し、変更は行いません。

3. ユーザーが希望しない場合、または MCP クライアントがない場合 — https://ssl.scandit.com でキーを自分で生成してもらいます（アカウントをまだお持ちでない場合：https://ssl.scandit.com/dashboard/sign-up?p=test）。生成したキーを貼り付けてもらってください。

次に、プレースホルダーをキーに置き換えてコードに設定してください。 .env にキーを書き込んだだけでは、アプリには反映されません。.NET は .env を自動で読み込まないため、以下の最も簡単な方法を使用してください。どのプラットフォームでも最も簡単な方法は、.env を読み込み、ライセンスキーの呼び出しにキーを直接指定することです。この場合も、チャットに表示するのは一部を伏せたプレビューのみとしてください。

参考資料

質問に応じて、ユーザーを適切なリソースに案内してください。

トピック	リソース
はじめに	はじめに（.NET for Android）
高度なトピック（カスタムハイライト、カスタムアノテーション、タップ操作、ポップオーバー、フィルター）	高度な設定
メジャー SDK バージョン間の移行	6 → 7 · 7 → 8
API リファレンス全体	BarcodeAr API（.NET Android）

このスキルがカバーする API の範囲

公式 RST ドキュメント（docs/source/barcode-capture/api/barcode-ar*.rst および api/ui/barcode-ar-*.rst）で :available: dotnet.android と記載されているすべてのクラスについては、references/integration.md で説明しています。

• BarcodeAr — new BarcodeAr(DataCaptureContext?, BarcodeArSettings), Feedback（取得／設定）、ApplySettingsAsync(BarcodeArSettings) → Task、AddListener(IBarcodeArListener) / RemoveListener(IBarcodeArListener)、event EventHandler<BarcodeArEventArgs> SessionUpdated、静的な RecommendedCameraSettings、Dispose。
• BarcodeArSettings — new BarcodeArSettings()、EnableSymbology(Symbology, bool)、EnableSymbologies(ICollection<Symbology>)、GetSymbologySettings(Symbology)、EnabledSymbologies（取得）、ExpectsOnlyUniqueBarcodes（取得／設定）、SetProperty / GetProperty<T> / TryGetProperty<T>、Dispose。
• IBarcodeArListener — 単一のメソッド OnSessionUpdated(BarcodeAr, BarcodeArSession, IFrameData)。（OnObservation* コールバックはありません。）
• BarcodeArSession — AddedTrackedBarcodes（IReadOnlyList<TrackedBarcode>）、RemovedTrackedBarcodes（IReadOnlyList<int>）、TrackedBarcodes（IReadOnlyDictionary<int, TrackedBarcode>）、Reset()。
• BarcodeArEventArgs — BarcodeAr、Session、FrameData。
• BarcodeArFeedback — new BarcodeArFeedback()（サイレント）、静的な DefaultFeedback（デフォルト）、Scanned / Tapped（Core.Common.Feedback.Feedback）、Dispose。
• BarcodeArView — static Create(View parentView, BarcodeAr, DataCaptureContext, BarcodeArViewSettings, CameraSettings?)、HighlightProvider（IBarcodeArHighlightProvider? の取得／設定）、AnnotationProvider（IBarcodeArAnnotationProvider? の取得／設定）、ShouldShowTorchControl / ShouldShowZoomControl / ShouldShowCameraSwitchControl、TorchControlPosition / ZoomControlPosition / CameraSwitchControlPosition（Anchor）、Start()、Stop()、Pause()、Reset()、GetNotificationPresenter()、OnResume() / OnPause()（Android のみ）、event EventHandler<HighlightForBarcodeTappedEventArgs> HighlightForBarcodeTapped、Android.Views.View への暗黙的な変換、Dispose。
• BarcodeArViewSettings — SoundEnabled（デフォルトは true）、HapticEnabled（デフォルトは true）、DefaultCameraPosition（デフォルトは WorldFacing）。
• HighlightForBarcodeTappedEventArgs — BarcodeAr、Barcode、Highlight（IBarcodeArHighlight）。
• ハイライト：IBarcodeArHighlight : IDisposable、IBarcodeArHighlightProvider.HighlightForBarcodeAsync(Barcode) → Task<IBarcodeArHighlight?>、BarcodeArRectangleHighlight(Barcode) の Barcode / Brush / Icon、BarcodeArCircleHighlight(Barcode, BarcodeArCircleHighlightPreset) の Barcode / Brush / Icon / Size、BarcodeArCircleHighlightPreset enum（Dot、Icon）。
• アノテーション：IBarcodeArAnnotation : IDisposable（AnnotationTrigger を宣言）、IBarcodeArAnnotationProvider.AnnotationForBarcodeAsync(Barcode) → Task<IBarcodeArAnnotation?>。
  • BarcodeArStatusIconAnnotation(Barcode) — AnnotationTrigger、HasTip、Icon、Text、TextColor、BackgroundColor。
  • BarcodeArInfoAnnotation(Barcode) — HasTip、EntireAnnotationTappable、Anchor（BarcodeArInfoAnnotationAnchor）、AnnotationTrigger、Width（BarcodeArInfoAnnotationWidthPreset）、Body（IReadOnlyCollection<BarcodeArInfoAnnotationBodyComponent>）、Header（BarcodeArInfoAnnotationHeader?）、Footer（BarcodeArInfoAnnotationFooter?）、BackgroundColor、Listener（IBarcodeArInfoAnnotationListener?）。
  • BarcodeArPopoverAnnotation(Barcode, IList<BarcodeArPopoverAnnotationButton>) — AnnotationTrigger、EntirePopoverTappable、Listener（IBarcodeArPopoverAnnotationListener?）、Buttons。
  • BarcodeArPopoverAnnotationButton(ScanditIcon, string) — Text、TextSize、Typeface、TextColor、Enabled、Icon。
  • BarcodeArAnnotationTrigger enum：HighlightTapAndBarcodeScan、HighlightTap。
• 情報アノテーションのサブパッケージ（Scandit.DataCapture.Barcode.Ar.UI.Annotations.Info）：BarcodeArInfoAnnotationBodyComponent（Text、TextColor、TextSize、Typeface、StyledTextFormatted、LeftIcon、RightIcon、LeftIconTappable、RightIconTappable、TextAlignment）、BarcodeArInfoAnnotationHeader（Text、TextSize、Typeface、TextColor、Icon、BackgroundColor）、BarcodeArInfoAnnotationFooter（Text、TextSize、Typeface、TextColor、Icon、BackgroundColor）、BarcodeArInfoAnnotationAnchor enum（Left、Right、Bottom、Top）、BarcodeArInfoAnnotationWidthPreset enum（Small、Medium、Large）、IBarcodeArInfoAnnotationListener（OnInfoAnnotationHeaderTapped、OnInfoAnnotationFooterTapped、OnInfoAnnotationLeftIconTapped、OnInfoAnnotationRightIconTapped、OnInfoAnnotationTapped）。
• IBarcodeArPopoverAnnotationListener — OnPopoverButtonTapped、OnPopoverTapped。
• TrackedBarcode（Scandit.DataCapture.Barcode.Batch.Data 内）— Barcode、Identifier、Location。