sumsub-integrate-msdk

Sumsub — モバイル SDK の統合（iOS と Android）

IdensicMobileSDK フレームワーク（メインクラスは SNSMobileSDK）を使って、Sumsub KYC を既存のネイティブアプリに組み込みます。依存関係のインストールから、本人確認フローの表示／起動までを扱います。対象は iOS（Swift）または Android（Kotlin）です。

ここでは共通部分を扱います。まず以下の常時参照セクション（情報の確認、質問と実行の使い分け）を読み、プラットフォームを特定してから、判断表を使って、プラットフォーム、プロジェクト、ユーザーの回答に合う分岐ファイルのみを開いてください。

最初に確認する3つの質問

プロジェクトのファイルに触れる前に、次の3つをまとめて質問してください。

1. 起動元。「Sumsub のフローをどの画面から開きますか？クラス名を教えるか、画面について説明してください。」— iOS： ViewController または SwiftUI ビュー、Android： Activity、Fragment、または Composable。

2. アクセストークンの取得元。「アプリには、バックエンドから Sumsub アクセストークンを取得する方法がすでにありますか？（ある場合は、関数名、エンドポイント URL、またはサービスクラスを教えてください。ない場合は、バックエンドの準備ができたときに記入できるプレースホルダーを追加します。）」

3. オプションモジュール。「基本 SDK は標準的な本人確認フローをカバーしており、常にインストールされます。これに加えて、次のアドオンが必要ですか？

   • NFC（パスポート／eMRTD チップの読み取り）— iOS： MRTDReader、Android： nfc モジュール — 生体認証パスポートのチップを読み取ります
   • VideoIdent — モデレーターとのライブビデオ通話
   • EID — ドイツの eID カードの読み取り
   • Fisherman / Device Intelligence — 不正利用の検知シグナル (iOS：オプションモジュール、Android：1.43.0 以降は基本 SDK にバンドル済み — 追加は不要です) 不明な場合は選択しなくてもかまいません。後から追加できます。」

   モジュールは追加機能のみです。複数選択の場合はモジュールのみを列挙してください。何も選択しない場合は「基本 SDK のみ」を意味するため、「基本 SDK のみ」を選択肢として追加しないでください。

App Token やシークレットキーについては質問しないでください。これらはサーバー側の情報であり、アプリには一切関係しません。

質問と実行の使い分け — 承認を適切に求める

• 読み取り専用の操作は、確認不要です — Info.plist、AndroidManifest.xml、ビルドファイルをスキャン／grep／読み取りできます。
• 変更はまとめて1回の承認を求めてください。行ごとに承認を求めないでください（「次の3つの Info.plist キー［一覧］と、この呼び出し箇所［差分］を追加します。適用しますか？」）。
• 明示的に確認するのは次の場合のみです： 既存アプリコードの編集、プロジェクトを変更するコマンド（pod install、Gradle の同期など）、取り消せない操作、情報確認の段階で判断できなかった事項。

プラットフォームの特定（分岐ファイルを開く前に実行）

これは iOS プロジェクトか Android プロジェクトかを判断します。インストール手順、権限モデル、生成する言語がそれぞれ異なります。読み取り専用で行ってください。

# iOS markers
find . -maxdepth 3 \( -name '*.xcodeproj' -o -name '*.xcworkspace' -o -name 'Podfile' -o -name 'Package.swift' \) 2>/dev/null
# Android markers
find . -maxdepth 3 \( -name 'build.gradle' -o -name 'build.gradle.kts' -o -name 'settings.gradle*' -o -name 'AndroidManifest.xml' \) 2>/dev/null

• iOS のみ（.xcodeproj／Package.swift／Podfile があり、Gradle はない）→ iOS トラック。
• Android のみ（build.gradle[.kts]／AndroidManifest.xml があり、Xcode はない）→ Android トラック。
• 両方がある（モノレポ、またはネイティブフォルダーを含む React-Native／Flutter シェル）→ 両方を報告し、どちらのプラットフォームを統合するか質問してください。1回の実行で対象にするプラットフォームは1つです。（React Native／Flutter のラッパー自体は対象外です。このスキルの対象はネイティブ SDK です。Step-1 のスキャンではラッパーを検出すると処理を中断します。）
• どちらもない → アプリのソースルートをユーザーに指定してもらってください。

判定に曖昧さがあった場合は、特定したプラットフォームを確認してから、該当するトラックに進んでください。

このスキルの進め方

情報確認の後、特定したプラットフォーム、プロジェクト（Step 1 で特定）、ユーザーの回答に合う行のみを開いてください。各分岐ファイルは単体で完結しており、末尾に次の手順へのポインターがあります。アルファベット付きの番号（2A／2B、6A／6B）は分岐を示すため、いずれか1つを選んでください。通常の番号は順番に進めます。

iOS の手順

ステップ	条件	参照
1. スキャン	常に（最初に、受付後）	ios/stages/1-scan.md
2A. インストール — CocoaPods	CocoaPods を選択（ステップ 1 に従う）	ios/stages/2a-install-cocoapods.md
2B. インストール — SPM	SPM を選択（ステップ 1 に従う。デフォルト）	ios/stages/2b-install-spm.md
3. 権限と機能	常に	ios/stages/3-permissions.md
4. インテグレーションファイル	常に	ios/stages/4-integration-code.md
5. ターゲットに組み込む	常に（ファイルの作成直後）	ios/stages/5-wire-target.md
6A. 起動 — UIKit	ホストが UIKit の ViewController	ios/stages/6a-launch-uikit.md
6B. 起動 — SwiftUI	ホストが SwiftUI のビュー	ios/stages/6b-launch-swiftui.md

Android の手順

ステップ	条件	参照
1. スキャン	常に（最初に、受付後）	android/stages/1-scan.md
2. インストール — 依存関係	常に	android/stages/2-install-dependencies.md
3. インテグレーションファイル	常に（Gradle が自動コンパイルするため、ターゲットに組み込む手順は不要）	android/stages/3-integration-code.md
4. 起動	常に	android/stages/4-launch.md

フォールバック（最終手段のみ）。 このスキルとその分岐ファイルが主な情報源です。通常は外部ドキュメントを参照しないでください。これらで解決できない重大な問題に直面した場合に限り、Sumsub のドキュメントを参照してください： iOS · Android.

ツリーをたどったら、ガードレールと引き継ぎのためにここに戻ってください。

ガードレール — このスキルが決して行ってはならないこと

• 最初にプラットフォームを検出する — Android プロジェクトに Swift を、iOS プロジェクトに Kotlin を出力してはいけません。両方が存在する場合は、どちらに統合するか確認してください。
• 既存のアプリコードは編集しない — インテーク時にユーザーが承認した、対象の呼び出し箇所 1 か所を除きます。
• （iOS）SwiftUI でも SDK 自身に表示させる。 常に SumsubVerification.start()（sdk.present() / sdk.present(from:)）で起動してください。フローの間、SDK やその mainVC を強参照してはいけません。また、sdk.mainVC を SwiftUI の .fullScreenCover / .sheet にブリッジしてはいけません。mainVC は SDK を強参照し、SDK はそのコントローラーの dealloc から onDidDismiss を呼び出します。自分で保持すると終了処理が遅れ、「1 回おきにしか開かない」問題や、再度開く際のクラッシュを引き起こします。表示も終了も SDK に任せてください。所有者は 1 つだけにし、クリーンに再度開けるようにします。
• （Android）カメラ／マイクの権限や実行時の許可プロンプトを追加しない — SDK が自ら宣言し、要求します。独自に追加すると、プロンプトが二重に表示されたり、競合したりする可能性があります。
• （Android）トークン更新ハンドラーは同期処理です — onTokenExpired() はバックグラウンドスレッドでトークンを返す必要があります。iOS の非同期／コールバック方式ではなく、runBlocking で suspend 関数によるトークン取得をブリッジしてください。
• 現在のメッセージでユーザーから明示的な許可を得ずに、プロジェクトを変更するコマンドを実行しない（pod install、Gradle の同期／ビルドなど）。
• App Token やシークレットキーを尋ねたり、言及したりしない — トークンはサーバー側で発行されます。
• アプリ内のファイルに App Token やシークレットキーを保存したり、記述したりしない。
• 既存の Info.plist / AndroidManifest の値を黙って上書きしない — 現在の値を必ず示し、先に確認してください。
• このスキルではテーマを変更しない — スタイリングは sumsub-theme-msdk で行います。
• アプリ内コールバックでアクセスを制御しない — 正式な判定結果は SDK コールバックではなく、バックエンド（webhook + applicant GET）から取得します。

引き継ぎ

すべての変更が完了したら、以下を明確にまとめてください。

1. 作成／変更したファイル — それぞれについて、1 行で説明を添えて列挙します。
2. 実装が必要なスタブ — トークン取得処理がプレースホルダーの場合は、その旨を明記し、ユーザーが実装すべき内容を説明します。（Android では、単一の SumsubTokenProvider.fetchAccessToken suspend 関数です。ランチャーはセッション中の更新にもこれを再利用します。）
3. ビルド手順 — iOS：「pod install を実行し、.xcworkspace を開いてビルド」または「ビルドして実行 — SPM パッケージは自動的に解決されます」。Android：「Gradle を同期してから、ビルドして実行」。
4. テスト方法 — バックエンドからサンドボックスのアクセストークンを取得する（または一時的にハードコードする）こと、起動ポイントから認証を開始すること（iOS：SumsubVerification.start(…)。Android：エフェクトによって画面から SumsubLauncher.present(…) が呼び出される ViewModel のアクション）、そして Sumsub のフローが表示されることを確認することを説明します。（NFC モジュールの利用には実機が必要です。iOS シミュレーター／Android エミュレーターでは利用できません。）
5. 信頼できる情報源 — 最終的な認証結果は SDK コールバックではなく、バックエンドの webhook + applicant read から取得することをユーザーに改めて伝えます。
6. 次のステップ — スタイリングについては sumsub-theme-msdk（iOS と Android）を案内します。