公式インテグレーションガイド Web サイト・Web アプリ向け

JavaScript ライブラリの fio.js と FACEIO Widget を Web サイトや Web アプリに組み込みます。新規ユーザーの登録には enroll()、登録済みユーザーが顔認証で再度ログインする際には authenticate() を使用します。

quick-start.js
JavaScript
// 1. HTML の </body> の前に追加
<div id="faceio-modal"></div>
<script src="https://cdn.faceio.net/fio.js"></script>

// 2. Public ID を指定してインスタンスを作成
const faceio = new faceIO("app-public-id");

// 3. 新規ユーザーを登録
faceio.enroll({ "locale": "auto",
         "payload": { "email": "user@example.com" }
}).then(userInfo => {
  console.log(`登録完了: ${userInfo.facialId}`);
}).catch(err => handleError(err));

// 4. 登録済みユーザーを認証
faceio.authenticate({ "locale": "auto" })
.then(userData => {
  console.log("Payload:", JSON.stringify(userData.payload));
}).catch(err => handleError(err));

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 から配信されます。

index.html
HTML
<div id="faceio-modal"></div>
<script src="https://cdn.faceio.net/fio.js"></script>

2 faceIO オブジェクトを作成

faceIO() を、アプリケーションの Public IDを指定して作成します。この ID は FACEIO Console ↗ の Application Manager で確認できます。

app.js
JavaScript
<script type="text/javascript">
  /*  fio.js を、アプリケーションの Public ID */
  const faceio = new faceIO("app-public-id");
</script>

続行する前に、次の項目を確認してください。

3 Widget を起動

fio.js を読み込み、 faceIO() インスタンスを作成したら、クラスが提供する次のメソッドのいずれかを呼び出します。

enroll()

顔認識で新規ユーザーを登録します。従来のユーザー登録をパスワードレスに置き換えるメソッドです。

authenticate()

登録済みユーザーを認証します。従来のサインインをパスワードレスに置き換えるメソッドです。

app.js
JavaScript
<button onclick="enrollNewUser()">新規ユーザーを登録</button>
<button onclick="authenticateUser()">ユーザーを認証</button>

<script type="text/javascript">
  const faceio = new faceIO("app-public-id");

  function enrollNewUser() {
    // faceio.enroll() で登録フローを開始
  }

  function authenticateUser() {
    // faceio.authenticate() で認証フローを開始
  }

  function handleError(errCode) {
    // ここでエラーを処理
  }
</script>

リファレンステンプレート

HTML テンプレート では、両方のメソッドとエラー処理を含む実装例を確認できます。


enroll() - 新規ユーザーの登録

FACEIO Widget を起動し、顔認識で新規ユーザーを登録します。従来の登録フローをパスワードレスに置き換えるメソッドです。成功すると、 userInfo オブジェクトを含む Promise が返されます。このオブジェクトにはユーザー固有の Facial ID、登録時刻、性別と年齢の推定値が含まれます。

構文

シグネチャ
promise = faceio.enroll({ parameters })
Alias
enrol() register() record()
戻り値
Promise です。成功すると userInfo オブジェクトで解決され、失敗すると fioErrCode で reject されます。

説明

動作

呼び出すと、FACEIO Widget は必要に応じてユーザーの同意を求め、カメラへのアクセスを要求し、取得した画像をアプリケーション所有者が選択した顔認識エンジンへ送信します。

FACEIO は生体認証ハッシュを保存、処理、参照しません。選択された顔認識エンジンが照合用の生体認証ハッシュを作成して管理し、Web サイトや Web アプリには結果の Facial ID と登録データが返されます。

PIN
登録時に、ユーザーは 4 桁から 16 桁の PIN Codeを設定します。顔の類似が検出された場合、照合信頼度が 99% をわずかに下回った場合、または Web サイトや Web アプリが PIN Code の確認を必須にしている場合、認証時に PIN Code が求められることがあります。
Payload
payload パラメータでは、メールアドレス、userId、名前などの任意データを登録ユーザーに関連付けます。このデータは、 認証が成功するたびに返されます 。最大サイズは 16 KB です。非 ASCII データやバイナリデータは Base64 でエンコードしてください。
Webhook
Webhookを設定している場合、FACEIO は登録データを endpoint へ POST し、backend とリアルタイムで同期します。

パラメータ

1 つの任意オブジェクトを受け取ります。すべてのプロパティは省略可能です。

プロパティ Type デフォルト 説明
payload JSON null ユーザーに関連付け、以降の認証で返される任意データです。最大 16 KB。非 ASCII データは Base64 でエンコードします。
permissionTimeout Number 27 sec カメラ権限を待機する秒数です。タイムアウトすると fioErrCode.PERMISSION_REFUSED で中止します。
termsTimeout Number 10 min 利用規約への同意を待機する分数です。タイムアウトすると fioErrCode.TERMS_NOT_ACCEPTED で中止します。
idleTimeout Number 27 sec 顔が検出されない場合に待機する秒数です。タイムアウトすると fioErrCode.NO_FACES_DETECTED で中止します。
replyTimeout Number 40 sec サーバーの応答を待機する秒数です。タイムアウトすると fioErrCode.TIMEOUT で中止します。
enrollIntroTimeout Number 12 sec 登録の案内画面を表示する秒数です。
locale String auto Widget の表示言語です。 auto はブラウザの言語を検出します。BCP 47 コード(en、ar、es、ja、de など)も指定できます。未対応の場合は en-US を使用します。
userConsent Boolean false true に設定すると、アカウント作成時などに同意を取得済みの場合に利用規約の同意画面を省略できます。 新規ユーザーを登録する前に、明示的な同意を取得する責任はアプリケーション所有者にあります。 詳細は プライバシーのベストプラクティスをご覧ください。
showAbortBtn Boolean false true に設定すると、閉じるボタンを常に表示します。ユーザーがクリックすると fioErrCode.ABORTED_BY_USER が発生します。

戻り値

userInfo

Promise です。成功すると userInfo オブジェクトで解決され、失敗すると エラーコード で reject されます。

プロパティ Type 説明
facialId String (UUID) 顔認識エンジンが割り当てる一意の識別子です。詳細は Facial IDをご覧ください。
timestamp String ISO 8601 ↗ 登録完了時刻です。
details Object 登録ユーザーの gender と age の推定値が含まれます。

例

使用例
app.js
JavaScript
// アプリケーションの Public ID で fio.js を初期化
const faceio = new faceIO("app-public-id");
function enrollNewUser(){
faceio.enroll({
  "locale": "auto", // ユーザーのデフォルト言語
  "payload": {
      /* このユーザーに関連付け、以後の認証時に返す payload。 */
      "whoami": 123456, // このユーザーに関連付けるサンプル ID
      "email": "john.doe@example.com"
      }
  }).then(userInfo => {
      // ユーザー登録に成功 
      alert(
          `ユーザー登録に成功しました。詳細:
           一意の Facial ID: ${userInfo.facialId}
           登録日時: ${userInfo.timestamp}
           推定性別: ${userInfo.details.gender}
           推定年齢: ${userInfo.details.age}`
      );
     console.log(userInfo);
     // 成功時の処理、Facial ID の保存、ダッシュボードへの移動などを実装
  }).catch(errCode => {
     // 登録時のエラーを記録
     handleError(errCode);
  })
}
注意事項
  • 返された facialId をユーザー固有の認証キーとしてデータベースに保存します。
  • payload は、以降の authenticate() 呼び出しでそのまま返されます。
  • 詳細は HTML テンプレート で動作する実装例を確認してください。

authenticate() - ユーザー認証

FACEIO Widget を起動し、登録済みユーザーを確認します。従来のサインインをパスワードレスに置き換えるメソッドです。成功すると、 userData オブジェクトを含む Promise が返されます。このオブジェクトにはユーザーの Facial ID、認証時刻、登録時に関連付けた payload が含まれます。

構文

シグネチャ
promise = faceio.authenticate({ parameters })
Alias
auth() recognize() identify()
戻り値
Promise です。成功すると userData オブジェクトで解決され、失敗すると fioErrCode で reject されます。

説明

動作

呼び出すと FACEIO Widget がカメラへのアクセスを求め、取得した画像をアプリケーションの登録済み顔インデックスと比較します。所要時間はカメラ権限、画質、liveness チェック、ネットワーク状態、設定したフローによって異なります。

顔照合は選択された顔認識エンジンが実行します。FACEIO は生体認証ハッシュを保存、処理、参照しません。クライアント側の統合では、返された認証結果を使用します。

PIN
顔の類似が検出された場合、照合信頼度が 99% をわずかに下回った場合、または Web サイトや Web アプリが PIN Code の確認を必須にしている場合 を FACEIO Console のセキュリティオプションで必須にしている場合は、PIN Code の入力を求めることがあります。
Payload
enroll() で関連付けた payload は、返された userData オブジェクト内にそのまま含まれます。facialId を検証し、Web サイトや Web アプリのセッションを作成する前に、独自のサーバー側認可ルールを適用してください。
Webhook
Webhook を設定している場合、認証成功後に FACEIO が認証イベントデータを endpoint へ POST します。

パラメータ

1 つの任意オブジェクトを受け取ります。すべてのプロパティは省略可能です。

プロパティ Type デフォルト 説明
permissionTimeout Number 27 sec カメラ権限を待機する秒数です。タイムアウトすると fioErrCode.PERMISSION_REFUSED で中止します。
idleTimeout Number 27 sec 顔が検出されない場合に待機する秒数です。タイムアウトすると fioErrCode.NO_FACES_DETECTED で中止します。
replyTimeout Number 40 sec サーバーの応答を待機する秒数です。タイムアウトすると fioErrCode.TIMEOUT で中止します。
locale String auto Widget の表示言語です。 auto はブラウザの言語を検出します。BCP 47 コード(en、ar、es、ja、de など)も指定できます。未対応の場合は en-US.

戻り値

userData

Promise です。成功すると userData オブジェクトで解決され、失敗すると エラーコード で reject されます。

プロパティ Type 説明
facialId String (UUID) 登録時に割り当てられる一意の識別子です。詳細は Facial ID ドキュメントをご覧ください。
payload Any 登録時にユーザーへ関連付けたメールアドレスや userId などの任意データです。

例

使用例
app.js
JavaScript
const faceio = new faceIO("app-public-id"); // アプリケーションの Public ID で初期化
function authenticateUser(){
  faceio.authenticate({
      "locale": "auto" // ユーザーのデフォルト言語
  }).then(userData => {
      console.log("成功: ユーザーを識別しました")
      // ユーザーに関連付けられた Facial ID を取得します。この値は
      // 以降の認証でも同じです。FACEIO では、backend で 
      // 登録ユーザーを一意に識別する場合に、この Facial ID を 
      // 使用することを推奨します。
      console.log("関連付けられた Facial ID: " + userData.facialId)
      // 登録時にユーザーへ関連付けた任意データを取得
      // enroll() の payload パラメータで設定したデータです。
      console.log("Payload: " + JSON.stringify(userData.payload)) // 上の enroll() 例で設定したデータ
  }).catch(errCode => {
      handleError(errCode)
  })
}
注意事項
  • 返された 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() を呼び出すとこの状態が解除され、次の認識処理を実行できます。

使用例
  • キオスクや共有端末 - 同じ端末で複数のユーザーを、ページを再読み込みせずに順番に認証します。
  • 登録後に認証するフロー - ユーザーを登録し、セッションをリセットしてから同じページで認証します。
  • エラー後の再試行 - 処理に失敗した後でリセットし、ページ更新なしで再試行できるようにします。
適用範囲
リセットは 1 つの faceIO インスタンスにのみ適用されます。複数の faceIO オブジェクトを作成した場合(非推奨)、それぞれが独立したセッション状態を持ちます。
Premium 機能

動的なセッション生成は Premium プラン で利用できます。この機能を使用するには、 FACEIO Console ↗ からアプリケーションのプランを変更してください。

戻り値

成功
true - セッションがリセットされ、インスタンスで新しい enroll() または authenticate() を呼び出せます。
失敗
false 。新しいセッションを作成できなかった場合に返されます。

エラーコード - fioErrCode

enroll() または authenticate() が失敗すると、Promise は数値の fioErrCode で reject されます。 .catch() ハンドラー内で値を判定してください。 restartSession()では、返された boolean(true または false)を確認してください。

コード 定数 説明
1 fioErrCode.PERMISSION_REFUSED ユーザーがカメラへのアクセスを拒否しました。ブラウザの設定で許可するよう案内してください。
2 fioErrCode.NO_FACES_DETECTED 待機時間内に顔が検出されませんでした。カメラに対する位置を調整して再試行するよう案内してください。
3 fioErrCode.UNRECOGNIZED_FACE 取得した顔が、アプリケーションに登録済みのユーザーと一致しませんでした。認証時のみ発生します。
4 fioErrCode.MANY_FACES 複数の顔が同時に検出されました。フレーム内に 1 人だけが映るようにしてください。
5 fioErrCode.FACE_DUPLICATION すでに顔が登録されているユーザーが再登録しようとしました。 "Prevent Same User from Enrolling Twice" セキュリティ設定が FACEIO Console ↗で有効な場合に発生します。登録を中止し、認証フローへ案内してください。
6 fioErrCode.MINORS_NOT_ALLOWED 設定された最低年齢ポリシーにより登録が拒否されました。適切なメッセージを表示し、アプリケーション所有者のアクセスポリシーに従ってください。
7 fioErrCode.PAD_ATTACK 実際の顔の代わりに写真、動画、マスクなどが提示された可能性があります。セキュリティシグナルとして扱い、再試行または確認ポリシーを適用してください。すべての試行を検出できるなりすまし防止システムはありません。詳細は ライブネス検出 ↗をご覧ください。
8 fioErrCode.FACE_MISMATCH 登録時に取得した顔ベクトルが互いに一致しませんでした。 enroll()でのみ発生します。ユーザーに登録の再試行を案内してください。
9 fioErrCode.NETWORK_IO ネットワークエラーが発生しました。接続を確認して再試行してください。
10 fioErrCode.WRONG_PIN_CODE 認証時に入力された PIN Code が正しくありません。 authenticate()でのみ発生します。3 回失敗すると中止されるため、認証を最初からやり直せるようにしてください。
11 fioErrCode.PROCESSING_ERR サーバー内部エラーです。一時的な可能性があるため、少し待ってから再試行してください。
12 fioErrCode.UNAUTHORIZED Public ID が無効か、FACEIO Console でアプリケーションが有効化されていません。
13 fioErrCode.TERMS_NOT_ACCEPTED ユーザーが termsTimeoutで指定された時間内に利用規約へ同意しませんでした。登録時のみ発生します。
14 fioErrCode.UI_NOT_READY FACEIO Widget の初期化が完了していません。DOM の読み込みが完了してからメソッドを呼び出してください。
15 fioErrCode.UNIQUE_PIN_REQUIRED PIN Code の一意性チェックが有効な場合、ユーザーごとに異なる PIN Code が必要です。
16 fioErrCode.TIMEOUT サーバーが replyTimeoutで指定された時間内に応答しませんでした。接続を確認して再試行してください。
17 fioErrCode.TOO_MANY_REQUESTS リクエスト上限を超えました。再試行前に exponential backoff を実装してください。
18 fioErrCode.EMPTY_ORIGIN リクエストの origin ヘッダーがありません。 fio.js が有効なドメインから配信されていることを確認してください。
19 fioErrCode.FORBIDDEN_ORIGIN リクエスト元が許可リストにありません。FACEIO Console のセキュリティオプションでドメインを追加してください。
20 fioErrCode.FORBIDDEN_COUNTRY FACEIO Console で設定された地域制限により、ユーザーの国がブロックされています。
21 fioErrCode.SESSION_IN_PROGRESS 別の登録または認証が進行中です。 enroll() または authenticate() がダブルクリックなどで複数回呼び出された場合に発生します。 restartSession() を使用すると、ページを再読み込みせずに新しいセッションを開始できます。Widget が動作中の場合は、別の処理を開始せずにこの状態を処理してください。
22 fioErrCode.ABORTED_BY_USER ユーザーが中止または閉じるボタンをクリックしました。このボタンは showAbortBtn: true の場合にのみ表示されます。

エラー処理のベストプラクティス

ユーザーが理解できるメッセージとともにエラー処理を実装してください。 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 の例を確認できます。

公式 NPM パッケージ

JavaScript のビルドツールやフレームワーク向けの公式パッケージです。

NPM で表示
コミュニティフォーラム

質問への回答を探し、FACEIO 開発者と実装経験を共有できます。

フォーラムを開く
プライバシーを重視したパスワードレス認証

パスワードレスログイン、年齢確認、liveness 検出を 1 つの構成で扱うガイドです。

チュートリアルを表示
顔認識による出席管理(Vanilla JS)

FACEIO と JavaScript のみで出席管理フローを構築します。

チュートリアルを表示
顔認証付き AI チャットボット(Next.js)

Next.js で顔認証付き旅行計画チャットボットを構築します。

チュートリアルを表示
React と Tailwind による顔認識

React と Tailwind CSS のアプリケーションに顔認識を追加します。

チュートリアルを表示
Vue.js での顔認識

Vue.js アプリケーションへ FACEIO の顔認証を実装するチュートリアルです。

チュートリアルを表示
React でユーザーを認証(freeCodeCamp)

React アプリに顔認識認証を追加する freeCodeCamp のガイドです。

チュートリアルを表示
最新の Web 認証パターン

顔認識を使用した Web アプリ向けの認証パターンを解説します。

チュートリアルを表示
FACEIO 総合ガイド

FACEIO の実装とベストプラクティスを詳しく解説します。

チュートリアルを表示
顔認識ログイン(Vanilla JS)

フレームワークを使わず、JavaScript のみで顔認識ログインを構築します。

チュートリアルを表示
FACEIO による出席管理

FACEIO の顔認識を使用して出席管理システムを構築します。

チュートリアルを表示
チュートリアルを共有する

FACEIO の実装チュートリアルを開発者コミュニティと共有できます。

お問い合わせ

5 分で FACEIO を導入

FACEIO アプリケーションを作成して Public ID を取得し、fio.js を読み込みます。 enroll() と authenticate() を Web サイトや Web アプリの登録ボタンとサインインボタンに接続してください。

クレジットカード不要
5 分で導入
フレームワーク非依存