FACEIO とは
FACEIO は、 PixLab ↗ が提供する顔認証プラットフォームです。対応する最新ブラウザの一般的な Web カメラやスマートフォンのカメラを使用し、FACEIO のフロー内でパスワード、OTP、専用の生体認証センサーを必要とせずに、ユーザーの登録と認証を実行できます。
クライアント側では fio.jsを使用します。主なメソッドは、新規登録用の enroll() と、サインイン用の authenticate() です。複数の処理を同じページで行うための restartSession() も利用できます。FACEIO は認証フローを調整し、アプリケーション所有者が選択した顔認識エンジンが顔照合と生体認証ハッシュの管理を行います。Web サイトや Web アプリには、ユーザーの Facial ID と登録時に関連付けた payload
が返されます。
FACEIO を初めて使用する場合
まず 5 分セットアップガイド に沿って最初のアプリケーションを作成し、 FACEIO Console ↗で設定を確認してください。
fio.js ライブラリの導入
fio.js は、対応する最新ブラウザの一般的な Web カメラやスマートフォンのカメラで動作し、 専用の生体認証センサーは不要です。JavaScript ライブラリはフレームワークに依存せず、React、Vue、Angular、Next.js、または JavaScript のみの構成で利用できます。
1
fio.js を Web サイトに追加
顔認証を使用するページで、次のコードを終了タグ </body> の前に貼り付けます。ライブラリは FACEIO の
CDN ↗
から読み込まれます。セルフホスティングには対応していないため、サポート対象の fio.js 更新は FACEIO CDN から配信されます。
-
fio.jsは必ず cdn.faceio.net ↗ から読み込んでください。セルフホスティングには対応していません。 - ビルドツールを使用する場合は、 公式 NPM パッケージ ↗を使用してください。
- React、Vue、Angular、Next.js 向けのガイドは、 コミュニティチュートリアル のセクションにあります。
2
faceIO オブジェクトを作成
faceIO() を、アプリケーションの Public IDを指定して作成します。この ID は FACEIO Console ↗ の Application Manager で確認できます。
続行する前に、次の項目を確認してください。
- FACEIO Console ↗ で FACEIO アプリケーションを作成し、顔認識エンジンを選択済みであること。
- セキュリティオプション (PIN Code ポリシーとドメイン制限)を セキュリティのベストプラクティス で確認済みであること。
- プライバシーに関する推奨事項 で、 Facial ID の取り扱いを プライバシーのベストプラクティス で確認済みであること。
3 Widget を起動
fio.js を読み込み、 faceIO() インスタンスを作成したら、クラスが提供する次のメソッドのいずれかを呼び出します。
顔認識で新規ユーザーを登録します。従来のユーザー登録をパスワードレスに置き換えるメソッドです。
登録済みユーザーを認証します。従来のサインインをパスワードレスに置き換えるメソッドです。
リファレンステンプレート
HTML テンプレート では、両方のメソッドとエラー処理を含む実装例を確認できます。
enroll() - 新規ユーザーの登録
FACEIO Widget を起動し、顔認識で新規ユーザーを登録します。従来の登録フローをパスワードレスに置き換えるメソッドです。成功すると、
userInfo オブジェクトを含む Promise が返されます。このオブジェクトにはユーザー固有の Facial ID、登録時刻、性別と年齢の推定値が含まれます。
構文
promise = faceio.enroll({ parameters })
enrol()
register()
record()
userInfo オブジェクトで解決され、失敗すると fioErrCode で reject されます。
説明
呼び出すと、FACEIO Widget は必要に応じてユーザーの同意を求め、カメラへのアクセスを要求し、取得した画像をアプリケーション所有者が選択した顔認識エンジンへ送信します。
FACEIO は生体認証ハッシュを保存、処理、参照しません。選択された顔認識エンジンが照合用の生体認証ハッシュを作成して管理し、Web サイトや Web アプリには結果の Facial ID と登録データが返されます。
payload パラメータでは、メールアドレス、userId、名前などの任意データを登録ユーザーに関連付けます。このデータは、 認証が成功するたびに返されます
。最大サイズは 16 KB です。非 ASCII データやバイナリデータは Base64 でエンコードしてください。
パラメータ
1 つの任意オブジェクトを受け取ります。すべてのプロパティは省略可能です。
戻り値
Promise です。成功すると userInfo オブジェクトで解決され、失敗すると エラーコード で reject されます。
例
- 返された
facialIdをユーザー固有の認証キーとしてデータベースに保存します。 -
payloadは、以降のauthenticate()呼び出しでそのまま返されます。 - 詳細は HTML テンプレート で動作する実装例を確認してください。
authenticate() - ユーザー認証
FACEIO Widget を起動し、登録済みユーザーを確認します。従来のサインインをパスワードレスに置き換えるメソッドです。成功すると、
userData オブジェクトを含む Promise が返されます。このオブジェクトにはユーザーの Facial ID、認証時刻、登録時に関連付けた payload が含まれます。
構文
promise = faceio.authenticate({ parameters })
auth()
recognize()
identify()
userData オブジェクトで解決され、失敗すると fioErrCode で reject されます。
説明
呼び出すと FACEIO Widget がカメラへのアクセスを求め、取得した画像をアプリケーションの登録済み顔インデックスと比較します。所要時間はカメラ権限、画質、liveness チェック、ネットワーク状態、設定したフローによって異なります。
顔照合は選択された顔認識エンジンが実行します。FACEIO は生体認証ハッシュを保存、処理、参照しません。クライアント側の統合では、返された認証結果を使用します。
enroll() で関連付けた payload は、返された userData
オブジェクト内にそのまま含まれます。facialId を検証し、Web サイトや Web アプリのセッションを作成する前に、独自のサーバー側認可ルールを適用してください。
パラメータ
1 つの任意オブジェクトを受け取ります。すべてのプロパティは省略可能です。
戻り値
Promise です。成功すると userData オブジェクトで解決され、失敗すると エラーコード で reject されます。
例
- 返された
facialIdをデータベースと照合してからセッションを認可します。 - 登録時の
payload(メールアドレスや userId など)はuserData.payloadで参照できます。セッションの検証は backend で行ってください。 - 詳細は HTML テンプレート で一通り実装された例を確認してください。
restartSession() - セッションをリセット
現在の FACEIO セッションをリセットし、同じページで新しい
enroll() または
authenticate()
呼び出しをページ全体の再読み込みなしで実行できるようにします。共有端末、イベント受付など、複数のユーザーが同じブラウザセッションを順番に使用するフローで利用できます。
構文
boolean = faceio.restartSession()
true、それ以外は false を返します。説明
enroll() または authenticate() が resolve または reject されると、FACEIO の内部セッションは使用済みになります。同じ faceIO インスタンスでリセットせずに次のメソッドを呼び出すと、直ちに fioErrCode.SESSION_IN_PROGRESS で reject されます。
restartSession() を呼び出すとこの状態が解除され、次の認識処理を実行できます。
- キオスクや共有端末 - 同じ端末で複数のユーザーを、ページを再読み込みせずに順番に認証します。
- 登録後に認証するフロー - ユーザーを登録し、セッションをリセットしてから同じページで認証します。
- エラー後の再試行 - 処理に失敗した後でリセットし、ページ更新なしで再試行できるようにします。
faceIO インスタンスにのみ適用されます。複数の faceIO オブジェクトを作成した場合(非推奨)、それぞれが独立したセッション状態を持ちます。Premium 機能
動的なセッション生成は Premium プラン で利用できます。この機能を使用するには、 FACEIO Console ↗ からアプリケーションのプランを変更してください。
戻り値
true - セッションがリセットされ、インスタンスで新しい enroll() または authenticate() を呼び出せます。false 。新しいセッションを作成できなかった場合に返されます。エラーコード - fioErrCode
enroll() または authenticate() が失敗すると、Promise は数値の fioErrCode で reject されます。 .catch() ハンドラー内で値を判定してください。 restartSession()では、返された boolean(true または false)を確認してください。
エラー処理のベストプラクティス
ユーザーが理解できるメッセージとともにエラー処理を実装してください。 switch または if-else でエラーコードごとの処理を行います。たとえば fioErrCode.UNRECOGNIZED_FACE が返された場合は登録フローへ案内します。
HTML テンプレート
enroll() と
authenticate()
とエラー処理を含む実装例です。統合の出発点として利用してください。
重要
app-public-id を、FACEIO Console ↗ で取得した実際の Public ID に置き換えてください。
リファレンステンプレート
実装上の注意
-
enroll()の呼び出し(31 行目)では、サンプルユーザーデータを含むpayloadを指定しています。Web サイトや Web アプリの要件に合わせて変更してください。 -
返された
facialIdをデータベースに保存し、以降の認証で参照できるようユーザーアカウントと関連付けます。 - エラーハンドラー(60 行目)は一般的なエラーコードに対応しています。メッセージは Web サイトや Web アプリに合わせて変更してください。
-
このテンプレートには稼働中の HTTP サーバーが必要です。
fio.jsはブラウザのセキュリティ制限により、ローカルファイルから直接読み込めません。 - 本番環境へ導入する前に、 セキュリティのベストプラクティス と プライバシーのベストプラクティス を確認してください。
コミュニティチュートリアル
コミュニティが公開した次のガイドでは、 fio.js を React、Vue、Angular、Next.js、JavaScript のみの構成で実装する方法や、React Native と Flutter の例を確認できます。
JavaScript のビルドツールやフレームワーク向けの公式パッケージです。
NPM で表示質問への回答を探し、FACEIO 開発者と実装経験を共有できます。
フォーラムを開くパスワードレスログイン、年齢確認、liveness 検出を 1 つの構成で扱うガイドです。
チュートリアルを表示FACEIO と JavaScript のみで出席管理フローを構築します。
チュートリアルを表示Next.js で顔認証付き旅行計画チャットボットを構築します。
チュートリアルを表示React と Tailwind CSS のアプリケーションに顔認識を追加します。
チュートリアルを表示Vue.js アプリケーションへ FACEIO の顔認証を実装するチュートリアルです。
チュートリアルを表示React アプリに顔認識認証を追加する freeCodeCamp のガイドです。
チュートリアルを表示顔認識を使用した Web アプリ向けの認証パターンを解説します。
チュートリアルを表示FACEIO の実装とベストプラクティスを詳しく解説します。
チュートリアルを表示フレームワークを使わず、JavaScript のみで顔認識ログインを構築します。
チュートリアルを表示FACEIO の顔認識を使用して出席管理システムを構築します。
チュートリアルを表示FACEIO の実装チュートリアルを開発者コミュニティと共有できます。
お問い合わせ