SDK インストールガイド

MIZUHIKI アイデンティティ SDK は、MIZUHIKI 上に構築されたプロジェクトが MIZUHIKI ID の機能をアプリケーションに直接統合できるようにします。マイナンバーカードを通じてユーザーのアイデンティティを認証し、MIZUHIKI Verified（本人認証済み）ソウルバウンドトークンをミントすることで EVM アドレスへの証明を発行します。

注記

SDK はプライベートベータリリース中です。アクセスを取得するにはお問い合わせください。

認証情報を受け取ったら、本ガイドに従ってプロジェクトの MIZUHIKI アイデンティティ SDK をセットアップしてください。

前提条件

MIZUHIKI アイデンティティ SDK を開始する前に、以下をご確認ください：

iOS
Android

iOS 開発の場合：
- Xcode 16.0 以降
- iOS 16.0 以上のデプロイメントターゲット
- NFC 対応デバイス：テスト用に iPhone 8 以降
- Apple Developer Program メンバーシップ（NFC 機能に必要）（こちらから登録）

共通要件：
- MIZUHIKI チームからのプロジェクト認証情報
- プライベートパッケージレジストリ用アクセストークン
- マイナンバーカード（本番テスト用）または互換性のある NFC カード（モックテスト用）

用語集

用語	定義
eKYC	Electronic Know Your Customer — デジタル本人確認プロセス
SBT	Soulbound Token（ソウルバウンドトークン）— 本人確認済みアイデンティティを証明する転送不可能な NFT
MyNumber Card	NFC チップ内蔵の日本国民 ID カード（マイナンバーカード）
EIP-191	署名済みメッセージフォーマットに関する Ethereum 規格
Mock Environment	シミュレートされたカードとテストデータを使用するテスト環境
Production Environment	実際のマイナンバーカードを使用するライブ環境
FeliCa	日本の IC カードで使用される NFC 通信技術
EVM	Ethereum Virtual Machine — ブロックチェーンの実行環境
PII	Personally Identifiable Information（個人識別情報）— 氏名、住所、ID 番号など特定の個人を識別するために使用できるデータ

環境設定

MIZUHIKI アイデンティティ SDK には mock と production の 2 つのバージョンがあります。開発フェーズに応じて適切な環境を選択してください：

モック環境

目的： 実際のマイナンバーカードを使用しないテストおよび開発

設定：

iOS
Android

SDK バージョン： mizuhiki-identity（iOS SDK には 1 つのパッケージに両バージョンが含まれています）
テストカード： FeliCa カード（交通系 IC、Edy、WAON など）または ISO/IEC 14443-4 Type-A カード（タッチ決済対応クレジットカード）
テストパスワード： ABC123（すべてのモックカードに共通のパスワード）
制限事項： モック環境では実際のマイナンバーカードは使用できません
ユースケース： 開発、統合テスト、CI/CD パイプライン

SDK バージョン： io.mizuhiki.identity-adapter-mock
テストカード： FeliCa カード（交通系 IC、Edy、WAON など）または ISO/IEC 14443-4 Type-A カード（タッチ決済対応クレジットカード）
テストパスワード： ABC123（すべてのモックカードに共通のパスワード）
制限事項： モック環境では実際のマイナンバーカードは使用できません
ユースケース： 開発、統合テスト、CI/CD パイプライン

対応テストカード：

カード種別	例	NFC 規格
FeliCa カード	Suica、Pasmo、Edy、WAON	FeliCa（Sony）
Type-A カード	タッチ決済対応クレジットカード、一部の交通系カード	ISO/IEC 14443-4 Type-A

本番環境

目的： ライブアプリケーション向けの実際のマイナンバーカード認証

設定：

iOS
Android

SDK バージョン： mizuhiki-identity（iOS SDK には 1 つのパッケージに両バージョンが含まれています）
必要なカード： 日本政府が発行した正規のマイナンバーカードのみ
パスワード： ユーザーの実際のマイナンバーカード暗証番号（6〜16 文字）
セキュリティ： 政府システムとの実際の暗号認証
ユースケース： 本番アプリケーション、実ユーザー認証

SDK バージョン： io.mizuhiki.identity-adapter-prod
必要なカード： 日本政府が発行した正規のマイナンバーカードのみ
パスワード： ユーザーの実際のマイナンバーカード暗証番号（6〜16 文字）
セキュリティ： 政府システムとの実際の暗号認証
ユースケース： 本番アプリケーション、実ユーザー認証

重要な注意事項：

⚠️ パスワード試行回数： 誤ったパスワード入力によりカードがロックされます
🏪 カードのロック解除： ロックされたカードはコンビニエンスストアまたは市区町村役場でロック解除が必要です
🔒 セキュリティ： すべての認証データは安全な政府チャネルを通じて処理されます

環境の切り替え：

iOS
Android

// Choose environment at compile time
#if MOCK
import MizuhikiIdentityMock
let client = MizuhikiIdentityMock.makeClient(projectId: "YOUR_PROJECT_ID")
#else
import MizuhikiIdentity  
let client = MizuhikiIdentity.makeClient(projectId: "YOUR_PROJECT_ID")
#endif

import io.mizuhiki.identity.adapter.prod.MizuhikiFactory
import io.mizuhiki.identity.adapter.mock.MizuhikiMockFactory

// Choose environment at runtime
val client = if (BuildConfig.FLAVOR == "mock") {
    MizuhikiMockFactory.makeClient(context, "YOUR_PROJECT_ID")
} else {
    MizuhikiFactory.makeClient(context, "YOUR_PROJECT_ID")
}

SDK のインストールとセットアップ

開発環境に応じたプラットフォーム別のセットアップ手順に従ってください：

1. SDK パッケージレジストリのセットアップ

iOS
Android

プライベートベータリリースのため、SDK はプライベートパッケージレジストリからダウンロードする必要があります。プロジェクトの Swift パッケージレジストリをセットアップしてください。その後、他のパッケージと同様に Xcode UI から MIZUHIKI アイデンティティ SDK をインストールできます。

ターミナルで以下のコマンドを実行します：

swift package-registry set --global https://swift.cloudsmith.io/mizuhiki/compliance/
swift package-registry login https://swift.cloudsmith.io/mizuhiki/compliance/ --token YOUR_TOKEN --no-confirm

YOUR_TOKEN をベータアクセスセットアップ時に提供されたトークンに置き換えてください。

プライベート MIZUHIKI Maven リポジトリへのアクセスを設定します。

settings.gradle.kts を設定します：

settings.gradle.kts
val repositoryReadUser = "token"
val repositoryReadPassword = System.getenv("MIZUHIKI_TOKEN") // Set this environment variable

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://dl.cloudsmith.io/basic/mizuhiki/compliance/maven/")
            credentials {
                username = "$repositoryReadUser"
                password = "$repositoryReadPassword"
            }
        }
    }
}

環境変数を設定します：

# Add to your shell profile (.zshrc, .bashrc)
export MIZUHIKI_TOKEN="your_token_here"

2. SDK のインストール

iOS
Android

Xcode でプロジェクトを開きます
File → Add Package Dependencies... に進みます
検索フィールドに mizuhiki と入力します
プロンプトが表示された場合はキーチェーンパスワードを入力します（プライベートレジストリアクセスに必要）
パッケージを選択してターゲットに追加します。iOS の場合、モックと本番 SDK は同じパッケージに含まれています。

パッケージ概要：

パッケージ	目的	必須
`io.mizuhiki.identity-core`	コア SDK インターフェースとモデル	✅ 常時必須
`io.mizuhiki.identity-ui`	KYC 用のプリビルド UI コンポーネント	✅ 推奨
`io.mizuhiki.identity-adapter-mock`	テスト用モック環境	🔧 開発時
`io.mizuhiki.identity-adapter-prod`	本番環境	🚀 本番時

オプション A：バージョンカタログを使用する（推奨）

libs.versions.toml に追加します：

libs.versions.toml
[versions]
mizuhiki = "+" # To dowload the latest version. If you want to use a specific version use the version in the following format "x.x.x"

[libraries]
mizuhiki-identity-core = { group = "io.mizuhiki", name = "identity-core", version.ref = "mizuhiki" }
mizuhiki-identity-ui = { group = "io.mizuhiki", name = "identity-ui", version.ref = "mizuhiki" }
mizuhiki-identity-adapter-mock = { group = "io.mizuhiki", name = "identity-adapter-mock", version.ref = "mizuhiki" }
mizuhiki-identity-adapter-prod = { group = "io.mizuhiki", name = "identity-adapter-prod", version.ref = "mizuhiki" }

build.gradle.kts (Module: app) に追加します：

build.gradle.kts (Module: app)
android {
  defaultConfig {
      minSdk = 26 // minimum SDK config
  }
  
  buildFeatures {
      buildConfig = true // to allow access to BuildConfig
  }
  
  // to switch between mock and production environment
  flavorDimensions += "env"
      productFlavors {
          create("mock") {
              dimension = "env"
              versionNameSuffix = "-mock"
          }
          create("prod") {
              dimension = "env"
          }
      }
}

dependencies {
    // Core functionality - always required
    implementation(libs.mizuhiki.identity.core)
    implementation(libs.mizuhiki.identity.ui)
    
    // Environment adapters - include both for flexibility
    implementation(libs.mizuhiki.identity.adapter.mock)    // Development/testing
    implementation(libs.mizuhiki.identity.adapter.prod)    // Production releases
}

オプション B：依存関係を直接指定する

build.gradle.kts (Module: app)
android {

  defaultConfig {
      minSdk = 26 // minimum SDK config
  }

  buildFeatures {
      buildConfig = true // to allow access to BuildConfig
  }

  // to switch between mock and production environment
  flavorDimensions += "env"
      productFlavors {
          create("mock") {
              dimension = "env"
              versionNameSuffix = "-mock"
          }
          create("prod") {
              dimension = "env"
          }
      }
}

dependencies {
    val mizuhikiVersion = "+" // To dowload the latest version. If you want to use a specific version use the version in the following format "x.x.x"
    
    implementation("io.mizuhiki:identity-core:$mizuhikiVersion")
    implementation("io.mizuhiki:identity-ui:$mizuhikiVersion")
    implementation("io.mizuhiki:identity-adapter-mock:$mizuhikiVersion")
    implementation("io.mizuhiki:identity-adapter-prod:$mizuhikiVersion")
}

3. NFC 機能の設定

iOS
Android

NFC タグ読み取り機能の追加：

プロジェクトナビゲーターでプロジェクトを選択します
TARGETS 配下のアプリターゲットを選択します
Signing & Capabilities タブに進みます
Apple Developer チームが選択されていることを確認します
+ Capability をクリックして Near Field Communication Tag Reading を追加します

Info.plist の設定：

Info タブを選択します
Custom iOS Target Properties の下に以下のエントリを追加します：

キー	タイプ	値
`Privacy - NFC Scan Usage Description`	String	`"Reading MyNumber cards for identity verification"`
`ISO18092 system codes for NFC Tag Reader Session`	Array	以下の値を参照

NFC システムコード（モック環境）：

0003（交通系 IC カード）
FE00（電子マネー）
88B4（FeliCa Lite-S）

注記

本番環境： 本番用の NFC システムコードは機密情報です。本番デプロイの準備が整ったら MIZUHIKI にお問い合わせください。

セットアップ参考画像：

Add NFC capability to your iOS project Configure the NFC capability for your project

iOS プロジェクトの NFC セットアップ

AndroidManifest.xml に NFC パーミッションを追加します：

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" 
    xmlns:tools="http://schemas.android.com/tools">
    
    <!-- NFC permission for MyNumber card scanning -->
    <uses-permission android:name="android.permission.NFC" />
    
    <!-- Declare NFC feature (optional: required=false for non-NFC devices) -->
    <uses-feature 
        android:name="android.hardware.nfc" 
        android:required="true" />
    
    <application android:name=".MyApplication">
        <!-- Your activities -->
    </application>
</manifest>

実行時の NFC チェック：

// Check if device supports NFC
val nfcAdapter = NfcAdapter.getDefaultAdapter(context)
if (nfcAdapter == null) {
    // Device doesn't support NFC
    showError("NFC is not available on this device")
    return
}

if (!nfcAdapter.isEnabled) {
    // NFC is disabled - prompt user to enable
    showError("Please enable NFC in device settings")
}

4. PII 暗号化キーのセットアップ

KYC 完了後、MIZUHIKI アイデンティティ SDK はユーザーの PII を暗号化された JWE データとして返します。本番稼働前に、インテグレーターのバックエンド用の公開鍵・秘密鍵ペアを生成してください。

鍵ペアを生成します（OpenSSL + RSA を使用した例）：

# Private key (keep this secret)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out mizuhiki-pii-private-key.pem

# Public key (share this with the MIZUHIKI team)
openssl rsa -pubout -in mizuhiki-pii-private-key.pem -out mizuhiki-pii-public-key.pem

秘密鍵はバックエンドのみに保管してください（例：KMS、シークレットマネージャー、暗号化ボールト）。
秘密鍵を git にコミットしたり、モバイルアプリのバンドルに含めたりしないでください。
公開鍵を MIZUHIKI チームと共有することで、暗号化された PII がお客様のシステムに返されます。

セキュリティ要件

秘密鍵はサーバーサイドのみに保管してください。
PII を復号するバックエンドサービスへのアクセスを制限してください。
漏洩が疑われる場合は直ちに鍵をローテーションしてください。

次のステップ

SDK のインストールとセットアップが完了したら、MIZUHIKI ID をアプリケーションに統合する準備が整いました。

続いて行うこと：

SDK の初期化 — アプリ内で MIZUHIKI アイデンティティ SDK クライアントをセットアップします
KYC フローの実装 — ユーザー認証機能を追加します
Verified SBT の発行 — ユーザーのアドレスにソウルバウンドトークンをミントします

次のページ： ユーザー認証ガイド →

はじめにチェックリスト

インストールのトラブルシューティング

よくある問題：

問題	プラットフォーム	解決策
パッケージレジストリの認証に失敗	iOS	正しいトークンで `swift package-registry login` を再実行
依存関係の解決に失敗	Android	環境変数 `MIZUHIKI_TOKEN` が設定されているか確認
NFC 機能がない	iOS	Apple Developer Program メンバーシップが有効かを確認

サポートが必要な場合：

📧 [email protected] までお問い合わせください
📚 実装の詳細についてはユーザー認証ガイドをご確認ください

前提条件​

用語集​

環境設定​

モック環境​

本番環境​

SDK のインストールとセットアップ​

1. SDK パッケージレジストリのセットアップ​

2. SDK のインストール​

3. NFC 機能の設定​

4. PII 暗号化キーのセットアップ​

次のステップ​

続いて行うこと：​

はじめにチェックリスト​

インストールのトラブルシューティング​