matrixscan-batch-ios

MatrixScan Batch iOS スキル

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

学習データに含まれる Scandit SDK API は、古い情報や誤った情報である可能性があります。BarcodeBatch API は SDK のメジャーバージョン間で変更されており、イニシャライザーのシグネチャ、オーバーレイのコンストラクター、デリゲートメソッド名はいずれも変化しています（例：BarcodeTracking → BarcodeBatch）。

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

注意すべき iOS 固有の落とし穴：

• BarcodeBatch(context: context, settings: settings) は直接呼び出す簡易イニシャライザーであり、Android の BarcodeBatch.forDataCaptureContext(...) のようなファクトリーメソッドではありません。nil 以外のコンテキストを渡すと、モードはそのコンテキストに自動的に追加されます。
• カメラの設定は手動で行います。Camera.default を取得し、context.setFrameSource(camera, completionHandler: nil) を呼び出してから、camera?.apply(BarcodeBatch.recommendedCameraSettings, completionHandler: nil) を呼び出します。カメラは viewWillAppear ／ viewWillDisappear から制御します。
• BarcodeBatchListener.barcodeBatch(_:didUpdate:frameData:) はバックグラウンドキューで呼び出され、メインスレッドでは呼び出されません。UI の処理は DispatchQueue.main.async {} 経由でディスパッチします。
• コールバックの外で BarcodeBatchSession.trackedBarcodes、addedTrackedBarcodes、updatedTrackedBarcodes、removedTrackedBarcodes への参照を保持しないでください。コールバックが戻る前にデータをコピーします。
• BarcodeBatchBasicOverlay(barcodeBatch:view:) と BarcodeBatchAdvancedOverlay(barcodeBatch:view:) は、オーバーレイを DataCaptureView に自動的に追加します。別途 addOverlay を呼び出す必要はありません。
• DataCaptureView は手動で addSubview する必要があります。BarcodeArView とは異なり、DataCaptureView は親ビューに自動追加されません。
• バーコードごとのブラシのカスタマイズ（barcodeBatchBasicOverlay(_:brushFor:)、setBrush(_:for:)）には、MatrixScan AR アドオンのライセンスが必要です。デリゲートを使わない一様なデフォルトブラシには必要ありません。
• BarcodeBatchAdvancedOverlay には、MatrixScan AR アドオンのライセンスが必要です。
• 組み込みのフィードバックはありません。BarcodeBatch 自体がサウンドを再生したり、振動したりすることはありません（BarcodeCapture ／ SparkScan とは異なります）。リスナーのコールバック内から（メインスレッドにディスパッチして）Feedback.default.emit() を手動で実行します。毎フレーム鳴らないよう、session.addedTrackedBarcodes を条件にします。
• session.removedTrackedBarcodes は、フレーム外に出たバーコードのトラッキング識別子を格納した [Int] であり、TrackedBarcode オブジェクトではありません。addedTrackedBarcodes ／ updatedTrackedBarcodes は [TrackedBarcode] です。
• iOS のシンボロジーケースはキャメルケースです。Android の EAN13_UPCA ／ CODE128 ／ QR のような表記ではなく、.ean13UPCA、.code128、.qr を使います。
• iOS のデリゲートメソッドは Swift の命名規則に従います。barcodeBatchBasicOverlay(_:didTap:) を使い、Android の onTrackedBarcodeTapped は使いません。barcodeBatchAdvancedOverlay(_:viewFor:) を使い、viewForTrackedBarcode は使いません。
• BarcodeBatchAdvancedOverlayDelegate が使うのは UIView です。Android の View や SwiftUI のビューではありません。
• SwiftUI：DataCaptureView は UIView なので、SwiftUI に直接配置できません。UIKit のビューコントローラーを UIViewControllerRepresentable でラップし、すべての BarcodeBatch API をそのビューコントローラー内に配置します。
• クリーンアップ：BarcodeBatchListener は弱参照で保持されるため、removeListener を呼び忘れてもメモリリークは発生しません。ただし、ライフサイクルを明確にするため、deinit で barcodeBatch.removeListener(self) を呼び出します。共有シングルトン（DataCaptureContext.shared）を使う場合、モードはアプリの存続期間中コンテキストに追加されたままなので、removeCurrentMode() や dispose() を呼び出す必要はありません。明示的に終了したい場合は、これらのメソッドを DataCaptureContext で使用できます。
• DataCaptureContext には、使用可能なイニシャライザーが 2 つあります。DataCaptureContext.initialize(licenseKey:) と .shared（7.1.0/7.6.0 で追加された最新のシングルトンパターンで、このスキルで使用する方法）、および従来の DataCaptureContext(licenseKey:) 簡易イニシャライザー（現在も非推奨ではなく、docs.scandit.com の UIKit Get Started ページで紹介されている方法）です。シングルトン形式を推奨します。

意図のルーティング

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

• MatrixScan Batch を一から統合する、設定を行う、追跡対象のバーコードを処理する、オーバーレイをカスタマイズする、フィードバックを追加する、またはライフサイクルを管理する場合 → references/integration.md を読み、そこに記載された手順に従ってください。コードを書く前に、プロジェクトが UIKit と SwiftUI のどちらを使用しているかを確認し（import SwiftUI、@main の App 構造体、SceneDelegate／AppDelegate、.storyboard／.xib ファイルなどを確認）、以下のリファレンステーブルにある該当する「はじめに」ページを使用してください。プロジェクトですでに BarcodeBatch が組み込まれている場合は、コンテキスト、モード、ビュー、ライフサイクルを作り直さないでください。既存のものを見つけ（BarcodeBatch、次に DataCaptureView を検索）、ユーザーが依頼した変更だけを行ってください。
• Scandit SDK のバージョンをアップグレードする場合（例：v6→v7、v7→v8、または「最新バージョンにアップグレード」）→ references/migration.md を読んでください。MatrixScan Batch における v6→v7 の主な変更点は、BarcodeTracking から BarcodeBatch への名称変更です。このガイドでは、コンテキストとカメラの最新化についても説明しています。ユーザーに尋ねる前に、Package.resolved／Podfile.lock からインストール済みのバージョンを確認してください。
• 別のバーコードスキャナーを MatrixScan Batch に置き換える場合（AVFoundation の AVCaptureMetadataOutput、VisionKit の DataScannerViewController、または他社製のマルチバーコード SDK）→ references/third-party-migration.md を読み、その後 references/integration.md に従って BarcodeBatch を統合してください。

API の使用ポリシー

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

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

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

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

ライセンスキー

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

以下の手順を順番に進めてください。MCP の利用をユーザーに強制してはいけません。

1. Scandit MCP サーバーが接続されている場合 — 製品を native、プラットフォームを ios に指定し、app_identifier（アプリのバンドル ID またはアプリケーション ID。Web の場合は本番ドメインで、localhost は不可）と env_var SCANDIT_LICENSE_KEY を指定して ensure_scanner_setup を呼び出します。返されたコマンドは実行しないでください。その後、この結果または list_license_keys から取得したキーの ID を指定して get_license_key を呼び出します。list_license_keys でそのキーがトライアルではないと確認できた場合は、取得する前にユーザーに確認してください。チャットにはマスクしたプレビューのみを表示し、キー全体を出力してはいけません。

2. 接続されていない場合 — ユーザーに一度だけ、MCP クライアントでリモート Scandit MCP サーバー https://ssl.scandit.com/mcp に接続できることを伝えてから、手順 1 に進みます。MCP クライアントの設定を自分で編集してはいけません。

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

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

次に、キーをコードに設定します：プレースホルダーの代わりに、ライセンスキー呼び出しへキーを記述します。キーは get_license_key が返したもの、またはユーザーが貼り付けるか伝えたものを使い、チャットには引き続きマスクしたプレビューのみを表示してください。プロジェクト、そのファイル、環境内からキーを検索してはいけません。

参考資料

トピック	リソース
UIKit との統合	使い始める（UIKit） · サンプル
SwiftUI との統合	使い始める（SwiftUI）
AR オーバーレイ（BasicOverlay ブラシ、AdvancedOverlay ビュー）	AR オーバーレイの追加
バージョン移行（v6→v7→v8）	6→7 の移行 · 7→8 の移行
API リファレンス全体	BarcodeBatch API