onfido ios sdk
32.1.0
Onfido Smart Capture SDK は、アプリケーションがユーザー ID 検証フローを実装できるようにする一連の画面と機能を提供します。各 SDK には次のものが含まれています。
すべての Onfido Smart Capture SDK は Onfido Studio ワークフローを使用して調整されますが、利用可能なプラットフォーム間のカスタマイズの違いはわずかです。
Onfido SDK 統合をサポートするために 2 つの環境が存在します。
使用される環境は、必要な SDK トークンの生成に使用される API トークンによって決まります。
統合に満足し、ライブを開始する準備ができたら、Onfido のカスタマー サポートに連絡してライブ API トークンを取得してください。コード内のサンドボックス トークンをライブ トークンに置き換える必要があります。
公開する前に、Onfido ダッシュボード内に正しい請求詳細を入力していることを確認してください。
iOS SDK は以下をサポートします。
注: Xcode 11.5-12 をサポートする最新の SDK バージョンは iOS SDK バージョン 22 で、Xcode 14 以降は iOS SDK バージョン 29 です。必要に応じて、Xcode の古いバージョンに対する回避策があります。詳細については、Onfido のカスタマー サポート チームにお問い合わせください。
注: iOS SDK では、(NFC を使用するかどうかに関係なく) CoreNFC を実行する必要があります。 Xcode 12 以降、 libnfshared.dylibがシミュレーターから欠落するバグがあります。この問題の解決策については、「スタック オーバーフロー」を参照してください。
注: NFC 機能を無効にした場合、実行時の構成に関係なく、NFC 関連のコードは SDK バイナリの一部であるため、Apple は NFC の使用法を示すビデオの提供を求める場合があります。この問題の恒久的な解決策に取り組んでいますが、それまでの間、Onfido のカスタマー サポートに連絡してビデオを入手してください。
SDK は、ユーザーのデバイスのカメラ (ドキュメントと顔のキャプチャ用) とマイク (ビデオとモーション キャプチャ用) を利用します。アプリケーションのInfo.plistファイルには次のキーが必要です。
NSCameraUsageDescriptionNSMicrophoneUsageDescription< key >NSCameraUsageDescription</ key >
< string >Required for document and face capture</ string >
< key >NSMicrophoneUsageDescription</ key >
< string >Required for video capture</ string >注: アプリの送信にはすべてのキーが必要です。
SDK は Swift Package Manager で利用でき、次のパッケージ リポジトリ URL を追加することでプロジェクトに SDK を含めることができます。
dependencies: [
. package ( url : " https://github.com/onfido/onfido-ios-sdk.git " , . branch ( " master " ) )
] SDK は CocoaPods でも利用でき、以下を Podfile に追加することでプロジェクトに含めることができます。
pod 'Onfido' pod install実行して SDK を取得します。
SDK は GitHub の [リリース] タブで入手でき、圧縮されたフレームワークをダウンロードできます。最新リリースはここでご覧いただけます。
Onfido.xcframeworkを含む圧縮 zip ファイルをダウンロードします。Onfido.xcframeworkアーティファクトをプロジェクト フォルダーに移動します。Onfido.xcframework 、iOS アプリ ターゲットのGeneralタブのEmbedded binariesセクションに追加します。アプリが Swift ベースでない場合は、プロジェクト内に新しい Swift ファイルを作成する必要があります。このファイルは、Onfido iOS SDK の実行に必要な Swift ランタイム ライブラリを Xcode に強制的にパッケージ化するために必要です。
次の内容の Swift ファイルを作成します。
import Foundation
import AVFoundation
import CoreImage
import UIKit
import Vision
func fixLibSwiftOnoneSupport ( ) {
// from https://stackoverflow.com/a/54511127/2982993
print ( " Fixes dyld: Library not loaded: @rpath/libswiftSwiftOnoneSupport.dylib " )
}プロジェクト設定で [ Always Embed Swift Standard Libraries Yesに設定します。
️ 次の SDK 初期化ドキュメントは、Onfido Studio を使用して調整された ID 検証ワークフローに適用されます。検証手順が手動で定義および構成されている統合については、以下の「高度なフローのカスタマイズ」セクションを参照してください。
iOS SDK には、統合を容易にしながら、統合に柔軟性を提供する複数の初期化およびカスタマイズのオプションがあります。
Onfido Studio は、Onfido SDK で使用する再利用性の高い ID 検証ワークフローを作成するために使用されるプラットフォームです。ワークフローの操作の概要については、「スタート ガイド」または「Onfido Studio 製品ガイド」を参照してください。
SDK セッションは、セッション固有のworkflow_run_idによって調整されます。この workflow_run_id 自体は、特定のワークフローの一意の識別子であるworkflow_idから派生します。
workflow_run_id生成する方法の詳細については、Onfido API リファレンスのPOST /workflow_runs/エンドポイント定義を参照してください。
SDK のコンテキストでは、
workflow_run_idプロパティはworkflowRunIdと呼ばれることに注意してください。
ワークフローを定義して ID 検証を作成するときは、再利用できるように特定のユーザーに対してapplicant_id保存することを強くお勧めします。これは、同じ個人に対して複数の ID 検証を実行する場合、またはユーザーが検証フローに戻って再開するシナリオでユーザーを追跡するのに役立ちます。
SDK は SDK トークンを使用して認証されます。 Onfido Studio は、ワークフロー実行の作成時に API によって返されるワークフロー実行ペイロードで SDK トークンを生成し、公開します。
Studio 用の SDK トークンは、生成された特定のワークフロー実行と一緒にのみ使用でき、有効期限は 5 週間です。
注: API トークンは、悪意のあるユーザーがソース コード内で発見する可能性があるため、アプリケーションのフロントエンドでは絶対に使用しないでください。これらはサーバー上でのみ使用してください。
SDK を使用するには、生成された SDK トークンとワークフロー実行 ID を使用して、クライアント オブジェクトのインスタンスを取得する必要があります。
let workflowConfiguration = WorkflowConfiguration ( workflowRunId : " <WORKFLOW_RUN_ID> " , sdkToken : " <YOUR_SDK_TOKEN> " ) let onfidoRun = OnfidoFlow ( workflowConfiguration : orchestrationConfig )
customerViewController . present ( try onfidoRun . run ( ) , animated : true , completion : nil )
// listen for the result最近のパスポート、国民 ID カード、および滞在許可証には、近距離無線通信 (NFC) を使用してアクセスできるチップが含まれています。 Onfido SDK は、この情報を抽出し、その信頼性を検証し、その結果の検証をドキュメント レポートの一部として提供するための一連の画面と機能を提供します。
Onfido iOS SDK のバージョン 29.1.0 以降では、NFC がデフォルトで有効になり、ドキュメントとデバイスの両方が NFC をサポートしている場合にエンド ユーザーに提供されます。
NFC の設定方法とサポートされるドキュメントのリストの詳細については、ドキュメント レポート用の NFC ガイドを参照してください。
この機能には、アプリターゲットにNear Field Communication Tag Reading機能が必要です。これまでに追加したことがない場合は、Apple のドキュメントの手順に従ってください。
NFC PACE ドキュメントをサポートするには、アプリの資格を編集する必要があります。
Near Field Communication Tag Reader Session Formatsキーの下にネストされた新しいエントリを追加します。Password Authenticated Connection Establishment (PACE)を選択します。< key >com.apple.developer.nfc.readersession.formats</ key >
< array >
< string >PACE</ string >
< string >TAG</ string >
</ array >アプリケーションのInfo.plistファイルに次のキーが必要です。
< key >NFCReaderUsageDescription</ key >
< string >Required to read ePassports</ string >Info.plistファイルに以下のエントリを含める必要があります。 <key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
<array>
<string>12FC</string>
</array>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
<string>A0000002472001</string>
<string>00000000000000</string>
<string>D2760000850101</string>
</array>
Onfido Studio を使用して NFC を構成するには、ワークフロー ビルダーで次のオプションのいずれかを使用できます。
optional ): 可能であれば、NFC 読み取りが試行されます。コードで NFC を構成するには、上記のオプションを使用してOnfidoConfigを構成するときにwithNFC()関数を呼び出します (以下の「高度なフローのカスタマイズ」セクションを参照)。
️ Studio とは異なり、NFC がコードでrequiredに応じて構成されている場合、SDK はエンド ユーザーのエクスペリエンスを最適化するために、NFC に対応していないドキュメント タイプを除外せず、ここにリストされている NFC 対応のドキュメント タイプのみを公開するか、Studio の使用を優先します。
iOS SDK は、SDK フローで使用される色、フォント、文字列のカスタマイズをサポートしています。
SDK のルック アンド フィールをカスタマイズするには、必要な CSS 値をWorkflowConfigurationオブジェクトのルートにあるAppearanceオブジェクトに渡すことができます。
let appearance = Appearance ( )
appearance . primaryColor = < DESIRED_UI_COLOR_HERE >
appearance . primaryTitleColor = < DESIRED_UI_COLOR_HERE > ONAppearance *appearance = [[ONAppearance alloc ] init ];
appearance.primaryColor = <DESIRED_UI_COLOR_HERE>;
appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>;このプロパティで設定できるサポートされている UI オプションの詳細については、SDK カスタマイズ ドキュメントを参照してください。
iOS SDK はダークテーマのカスタマイズをサポートしています。デフォルトでは、ユーザーのアクティブなデバイスのテーマが自動的に Onfido SDK に適用されます。ただし、実行時の動的なテーマの切り替えをオプトアウトし、代わりに以下に示すようにビルド時にテーマを静的に設定することができます。この場合、フローはユーザーのデバイスのテーマに関係なく、常に選択したテーマで表示されます。
interfaceStyle使用すると、それぞれ.darkと.lightを介してライト モードまたはダーク モードを強制できます。デフォルトでは、 .unspecifiedに設定されており、システムのインターフェイス スタイルに従います。
注:以前の属性supportDarkModeは非推奨になりました。代わりにinterfaceStyle使用してください。
たとえば、インターフェイス スタイルを.darkに設定するには、以下のコードを使用できます。
let appearance = Appearance ( )
appearance . setUserInterfaceStyle ( . dark ) ONAppearance *appearance = [ONAppearance new ];
[appearance setUserInterfaceStyle: UIUserInterfaceStyleDark];外観を適用するには、以下の方法を使用できます。
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withAppearance ( appearance ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withAppearance: appearance];Onfido SDK では、Onfido 画面の下部にある Onfido ロゴの表示に影響を与える 2 つの共同ブランド オプションが可能です。
cobrand {Object} - オプション
フッターのウォーターマークにブランドを追加する最も効果的な方法は、 enterpriseFeaturesのcobrandプロパティを使用することです。このプロパティはtextパラメータを受け取ります。
let companyName = " MyCompany "
let enterpriseFeatures = EnterpriseFeatures . builder ( )
. withCobrandingText ( companyName )
. build ( ) NSString *companyName = @" MyCompany " ;
ONEnterpriseFeaturesBuilder *enterpriseFeatures = [ONEnterpriseFeatures builder ];
[enterpriseFeatures withCobrandingText: companyName];
[enterpriseFeatures build ];注: テキストの共同ブランド化は Onfido で有効にする必要があります。この機能を有効にするには、ソリューション エンジニアまたはカスタマー サクセス マネージャーに問い合わせてください。
logoCobrand {Object} - オプション
cobrandの代わりに、 enterpriseFeaturesの下のlogoCobrandプロパティで定義される一連の画像を指定することもできます。 「ダーク」モードで使用する画像へのパスを指定し、「ライト」モードで使用する別の画像へのパスを指定する必要があります。どちらの画像も解像度が 144x32 である必要があります。
let onfidoEnterpriseFeatures = EnterpriseFeatures . builder ( )
. withCobrandingLogo (
UIImage ( named : " imageName_for_lightmode " ) ! ,
cobrandingLogoDarkMode : UIImage ( named : " imageName_for_darkmode " ) !
)
. build ( ) ONEnterpriseFeaturesBuilder *enterpriseFeatures = [ONEnterpriseFeatures builder ];
[enterpriseFeatures withCobrandingLogo:
[UIImage imageNamed: @" onfido-logo-white " ] cobrandingLogoDarkMode: [UIImage imageNamed: @" onfido-logo-grey " ]
];
[enterpriseFeatures build ];注: ロゴの共同ブランド化は、Onfido によって有効にする必要があります。この機能を有効にするには、ソリューション エンジニアまたはカスタマー サクセス マネージャーに問い合わせてください。
共同ブランドを適用するには、エンタープライズ機能オブジェクトをOnfidoConfigに追加します。
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withEnterpriseFeatures ( enterpriseFeatures ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withEnterpriseFeatures: enterpriseFeatures];Onfido SDK は、40 を超える言語の翻訳をサポートおよび維持します。
SDK 内で使用される文字列は、アプリ内に目的の言語のLocalizable.stringsを用意し、構成ビルダーのwithCustomLocalization()メソッドを使用してフローを構成することでカスタマイズできます。
- ( void ) withCustomLocalization {
[ self . configBuilder withCustomLocalization ] ; // will look for localizable strings in your Localizable.strings file
}Onfido でサポートされている言語のリストについては、SDK カスタマイズ ドキュメントを参照してください。
注: 言語が選択されていない場合、SDK はエンド ユーザーのデバイス言語設定を検出して使用します。デバイスの言語がサポートされていない場合、SDK はデフォルトで英語 ( en_US ) に設定されます。
SDK は、Onfido が現在サポートしていないロケールのカスタム言語で表示することもできます。完全な翻訳または部分的な翻訳を提供できます。翻訳のないキーの場合は、サポートされているデフォルトの言語が使用されます。
カスタム翻訳を追加するときは、 Localizable.stringsファイルに含まれるキーのセット全体を追加する必要があります。
必要に応じて、翻訳されたキーを含む文字列ファイルに名前を付けることができますが、ファイルの名前はwithCustomLocalization()メソッドのパラメーターとして SDK に提供する必要があります。
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE") (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE"]; (目的-C)さらに、文字列ファイルを読み取るバンドルを指定できます。
withCustomLocalization(andTableName: "MY_CUSTOM_STRINGS_FILE", in: myBundle) (Swift)[configBuilder withCustomLocalizationWithTableName:@"MY_CUSTOM_STRINGS_FILE" in: myBundle]; (目的-C)注記：
新しい言語の翻訳をリクエストする場合、または提供された翻訳についてフィードバックや提案を提供する場合は、Onfido のカスタマー サポートにお問い合わせください。
Onfido SDK セッションが終了すると、さまざまなコールバック関数がトリガーされることがあります。
ユーザー分析と送信されたメディアの返却に使用される高度なコールバックについては、このドキュメントの「高度なコールバック」セクションを参照してください。
完了したワークフローから結果を受け取るには、 OnfidoFlowのインスタンスにコールバックを渡す必要があります。次のコードが例として提供されています。
onfidoRun . with ( responseHandler : { ( response : OnfidoResponse ) in
switch response {
case . success :
// User completed the flow
case . cancel ( let cancellationReason ) :
// Flow cancelled by user
print ( cancellationReason )
case . error ( let error ) :
// Error occurred
print ( error )
}
} ,
dismissFlowOnCompletion : true )
// Dismiss the whole flow when the user completes it, and return back to the integrator view| 属性 | 注意事項 |
|---|---|
| 。成功 | ワークフロー内のすべての対話型タスクが完了したときに起動されるコールバック。 Webhook を構成している場合、成功すると、ワークフローの実行が完了したことを確認する通知がバックエンドに送信されます。これはワークフローによって直接処理されるため、バックエンドを使用してチェックを作成する必要はありません。 |
| .error(エラー) | エラー発生時に起動されるコールバック |
| 。キャンセル | ユーザーがワークフローを途中で終了したときに起動されるコールバック。理由は.userExitまたは.consentDeniedです。 |
OnfidoResponse.error(Error)の一部として返されるErrorオブジェクトのタイプはOnfidoFlowErrorです。これは、エラーの種類に応じて複数のケースがある列挙型です。
switch response {
case let OnfidoResponse . error ( error ) :
switch error {
case OnfidoFlowError . cameraPermission :
// This happens if the user denies permission to the SDK during the flow
case OnfidoFlowError . failedToWriteToDisk :
// This happens when the SDK tries to save capture to disk, maybe due to a lack of space
case OnfidoFlowError . microphonePermission :
// This happens when the user denies permission for microphone usage by the app during the flow
case OnfidoFlowError . upload ( let OnfidoApiError ) :
// This happens when the SDK receives an error from an API call.
// See https://documentation.onfido.com/api/latest#errors for more information
case OnfidoFlowError . exception ( withError : let error , withMessage : let message ) :
// This happens when an unexpected error occurs.
// Please email [Customer support](mailto:supportonfido.com) when this happens
case OnfidoFlowError . versionInsufficient :
// This happens when you are using an older version of the iOS SDK and trying
// to access a new functionality from workflow. You can fix this by updating the SDK
default : // necessary because of Swift
}
}SDK はユーザーのメディアとデータのキャプチャとアップロードを担当しますが、本人確認レポート自体は Onfido Studio を使用して作成されたワークフローに基づいて生成されます。
Onfido Studio と SDK を使用して ID 検証を作成する手順については、クイック スタート ガイドを参照してください。
このドキュメントの「高度なカスタマイズ」セクションで定義されたオプションを使用してアプリケーションが Onfido iOS SDK を初期化する場合は、Onfido API を使用して手動でチェックを作成し、レポート結果を取得できます。レポート結果が生成されたときに非同期に通知されるように Webhook を構成することもできます。
「高度なカスタマイズ」に関するこのセクションでは、Onfido Studio を使用せずに Onfido iOS SDK を初期化するプロセスについて説明します。このプロセスでは、検証ステップとその構成を手動で定義する必要があります。
これらのフロー ステップ パラメーターはworkflowRunIdと相互に排他的であるため、クライアントをインスタンス化してフローを開始する別の方法が必要です。
新機能の大部分は Studio ワークフロー専用にリリースされているため、この初期化プロセスは推奨されないことに注意してください。
SDK は SDK トークンを使用して認証されます。各 SDK トークンは特定の申請者およびセッションに固有である必要があるため、Onfido iOS SDK を初期化するたびに新しいトークンを生成する必要があります。
| パラメータ | 注意事項 |
|---|---|
applicant_id | 必須 SDK インスタンスの申請者を指定します。 |
application_id | 必須 開発時に設定されたアプリケーション ID (iOS の場合は「アプリケーション バンドル ID」)。 iOS の場合、これは通常、 com.your-company.app-nameの形式になります。必ず有効なapplication_id使用してください。使用しないと 401 エラーが発生します。 |
SDK トークンを手動で生成する方法の詳細については、Onfido API リファレンスのPOST /sdk_token/定義を参照してください。
注: API トークンは、悪意のあるユーザーがソース コード内で発見する可能性があるため、アプリケーションのフロントエンドでは絶対に使用しないでください。これらはサーバー上でのみ使用してください。
expireHandlerを使用した SDK トークンの有効期限の管理SDK トークンを手動で生成する場合は、90 分後に期限切れになることに注意することが重要です。
これを念頭に置いて、SDK トークン構成関数でオプションのexpireHandlerパラメーターを使用して、有効期限が切れたときに新しい SDK トークンを生成して渡すことをお勧めします。これにより、SDK トークンの有効期限が切れた後でも SDK がフローを継続できるようになります。
例えば：
func getSDKToken ( _ completion : @escaping ( String ) -> Void ) {
// Your network request logic to retrieve SDK token goes here
completion ( myNewSDKtoken )
}
let config = try OnfidoConfig . builder ( )
. withSDKToken ( " <YOUR_SDK_TOKEN> " , expireHandler : getSDKToken ) -( void ) getSDKToken: ( void (^)( NSString *)) handler {
// <Your network request logic to retrieve SDK token goes here>
handler (sdkToken);
}
ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withSdkToken: @" YOUR_SDK_TOKEN " expireHandler: ^( void (^ handler)( NSString * expireHandler)) {
[ self getSDKToken: handler];
}];SDK の依存関係を追加し、申請者 ID を取得したら、SDK フローのステップを手動で構成できます。
let config = try OnfidoConfig . builder ( )
. withSDKToken ( " <YOUR_SDK_TOKEN> " )
. withWelcomeStep ( )
. withDocumentStep ( )
. withProofOfAddressStep ( )
. withFaceStep ( ofVariant : . photo ( withConfiguration : nil ) )
. build ( )
let onfidoFlow = OnfidoFlow ( withConfiguration : config )
. with ( responseHandler : { results in
// Callback when flow ends
} ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withSdkToken: @" YOUR_SDK_TOKEN " ];
[configBuilder withWelcomeStep ];
[configBuilder withDocumentStep ];
[configBuilder withProofOfAddressStep ];
NSError *variantConfigError = NULL ;
Builder *variantBuilder = [ONFaceStepVariantConfig builder ];
[variantBuilder withPhotoCaptureWithConfig: NULL ];
[configBuilder withFaceStepOfVariant: [variantBuilder buildAndReturnError: &variantConfigError]];
if (variantConfigError == NULL ) {
NSError *configError = NULL ;
ONFlowConfig *config = [configBuilder buildAndReturnError: &configError];
if (configError == NULL ) {
ONFlow *onFlow = [[ONFlow alloc ] initWithFlowConfiguration: config];
[onFlow withResponseHandler: ^(ONFlowResponse *response) {
// Callback when flow ends
}];
}
} try onfidoRun . run ( from : yourViewController , animated : true ) NSError *runError = NULL ;
[onFlow runFrom: yourViewController animated: YES error: &runError completion: nil ];
if (runError != NULL ) {
// do fallback logic
}SDK のルック アンド フィールをカスタマイズするには、必要な CSS 値をOnfidoConfig.builder()オブジェクトのルートにあるAppearanceオブジェクトに渡すことができます。
let appearance = Appearance ( )
appearance . primaryColor = < DESIRED_UI_COLOR_HERE >
appearance . primaryTitleColor = < DESIRED_UI_COLOR_HERE > ONAppearance *appearance = [[ONAppearance alloc ] init ];
appearance.primaryColor = <DESIRED_UI_COLOR_HERE>;
appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>;外観を適用するには、以下の方法を使用できます。
let configBuilder = OnfidoConfig . builder ( )
configBuilder . withAppearance ( appearance ) ONFlowConfigBuilder *configBuilder = [ONFlowConfig builder ];
[configBuilder withAppearance: appearance];このプロパティで設定できるサポートされている UI オプションの詳細については、SDK カスタマイズ ドキュメントを参照してください。
SDK フローにステップを追加することで、SDK のフローをカスタマイズできます。
考えられる手順は次のとおりです。
| ステップ | 説明 |
|---|---|
withWelcomeStep | ユーザーに表示されるようこそ画面と、事前の手順。カスタマイズ オプションには、テキスト要素の変更やユーザーに表示される指示が含まれます。 |
withDocumentStep | 写真によるキャプチャまたはユーザーのドキュメントのアップロードを制御する一連の画面。ユーザーに表示されるドキュメント リストと全体的なキャプチャ エクスペリエンスを定義するために、多数のカスタマイズ オプションを使用できます。 |
withFaceStep | ユーザーのセルフィー、ビデオ、またはモーション キャプチャのキャプチャを制御する一連の画面。カスタマイズ オプションを使用すると、キャプチャ バリアントを選択できます。 |
withProofOfAddressStep | ユーザーが住所を確認するために発行国と書類の種類を選択する画面。 |
このステップはSDKの導入画面です。プロセスを紹介し、ユーザーが完了する必要がある手順を準備できるようにします。
この画面はオプションですが、独自の本人確認のようこそ画面がすでに設置されている場合にのみ削除することをお勧めします。
ようこそ画面を表示するには、Swift のconfigBuilder.withWelcomeStep()または Objective-C の[configBuilder withWelcomeStep]を呼び出します。
