FACEIOを使い始める

アプリケーションを作成して設定する手順：

1

FACEIO Console ↗にアクセスします。

2

Consoleのメイン画面で新しいアプリケーションを選択し、Application Wizardを開きます。

3

Application Wizardの案内に従い、アプリケーション名とプライバシーポリシーのURLを入力します。次に、顔認識エンジン、クラウドの保存リージョンまたはオンプレミス環境、セキュリティ設定、ウィジェットの外観を指定します。

Application Wizardを開く

4

設定内容を確認して送信します。アプリケーションの作成後、 Application Manager ↗が開き、手順付きの統合ガイドとともに新しいアプリケーションを管理できます。

1 fio.js をサイトに読み込む

fio.jsを使用するHTMLページで、終了</body>タグの直前に次のスニペットを貼り付けます。

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

上記のスニペットは fio.js を非同期で読み込みます。基本的なHTMLページでは、次のようにライブラリを初期化できます。

<html>
  <head>
    <title>顔認識でログイン</title>
  </head>
  <body>
    <div id="faceio-modal"></div>
    <script src="https://cdn.faceio.net/fio.js"></script>
  </body>
</html>

2 faceIO オブジェクトを作成

fio.jsを初期化するには、新しいfaceIO()オブジェクトを作成し、アプリケーションのPublic IDを渡します。次の例のように記述します。このスニペットはステップ1の読み込みコードの直後にも追加できます。完全な例はHTML Boilerplateをご覧ください。

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

enroll() メソッド

• 新規ユーザーを登録するには、先ほど作成したfaceIOオブジェクトのenroll()メソッドを呼び出します。このメソッドを使うと、アプリケーション内で新規ユーザーをトランザクション単位で登録できます。この処理は一般にonboardingと呼ばれ、従来のユーザー登録フローに相当します。

• enroll()を呼び出すとFACEIO Widgetが開き、必要に応じてユーザーの同意とカメラへのアクセスを求め、登録に必要な顔データを取得します。選択した顔認識エンジンが、今後の認証に使用する生体認証ハッシュを生成してインデックス化します。

• enroll()は複数のオプションパラメーターを受け取ります。たとえば、localeは操作言語、permissionTimeoutはカメラアクセスの待機時間、payloadはユーザーに関連付ける任意のデータ（メールアドレス、名前、IDなど）を指定します。 このpayloadは、今後の認証に成功したときに返されます。

• enroll()はPromiseを返し、登録に成功するとuserInfoオブジェクトで解決されます。返り値にはFacial ID、登録日時、details.ageとdetails.genderの推定値が含まれます。Facial IDは、対応するバックエンドアカウントを検索するキーとして使用できます。

• ユーザーがカメラへのアクセスまたは利用規約を拒否すると、Promiseは対応するエラーコードでrejectされます（fioErrCode.PERMISSION_REFUSED、fioErrCode.TERMS_NOT_ACCEPTEDなど）。完全な一覧はエラーコードセクションをご覧ください。

• enroll()メソッドのパラメーター、戻り値、エラー処理については、統合ガイドをご覧ください。

authenticate() メソッド

• 登録済みユーザーを認証して識別するには、faceIOオブジェクトのauthenticate()メソッドを呼び出します。このメソッドは登録済みユーザーに対してトランザクション単位の認証と識別を実行し、従来のログインフローに相当します。

• authenticate()を呼び出すとFACEIO Widgetが開き、必要に応じてカメラへのアクセスを求め、設定されたlivenessチェックと顔認識を実行して認証結果を返します。

• アプリケーションの セキュリティ設定によっては、顔認識エンジンがユーザーを識別した後、 登録時に設定したPIN Codeの確認が必要です。確認後に authenticate() メソッドが成功します。

• authenticate()は、カメラアクセスの待機時間を指定するpermissionTimeout、操作言語を指定するlocaleなどのオプションを受け取ります。すべての項目はauthenticate()のドキュメントで確認できます。

• authenticate()はPromiseを返し、識別に成功するとuserDataオブジェクトで解決されます。主なプロパティは、登録時に関連付けたデータを含むpayloadと、ユーザー固有の識別子であるfacialIdです。これらをバックエンドの検索キーとして使用し、ユーザー固有のデータを取得できます。

• authenticate()メソッドのパラメーター、戻り値、エラー処理については、統合ガイドをご覧ください。

新規ユーザーを登録

新規ユーザーの登録では、同意を取得した後に顔特徴を抽出してインデックス化します。enroll()を呼び出すだけで開始できます。

// アプリケーションのPublic IDでfaceIOオブジェクトを作成
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);
    })
}

• 初期化：アプリケーションのPublic IDでfaceIOオブジェクトを作成します。"app-public-id"をFACEIO Console ↗で取得した実際のPublic IDに置き換えます。

• 登録の呼び出し：enroll()を呼び出すと登録が始まり、必要に応じてユーザーの同意とカメラへのアクセスを求め、顔特徴を抽出します。payloadパラメーターを使って、ユーザーID（whoami）やメールアドレスなどのデータをユーザーに関連付けられます。 このpayloadは、今後の認証に成功したときに返されます。

• 登録結果：登録に成功すると、PromiseはuserInfoオブジェクトで解決され、一意のFacial ID、登録日時、details.genderとdetails.ageの推定値が返されます。Facial IDをデータベースに保存して、今後の認証をこのユーザーに関連付けてください。

• エラー処理：登録の失敗を捕捉し、handleError() 関数を実装して各エラーコードを適切に処理してください。すべてのコードは エラーコードのドキュメント で確認できます。

既存ユーザーを認証

同様に、登録済みユーザーの認証はauthenticate()を呼び出すだけで開始できます。

const faceio = new faceIO("app-public-id"); // アプリケーションのPublic IDで初期化
function authenticateUser(){
    faceio.authenticate({
        "locale": "auto" // ユーザーのデフォルト言語
    }).then(userData => {
        console.log("ユーザーの識別に成功")
        // このユーザーに返されたFacial IDを取得。同じアプリケーションでは
        // 認証に成功するたびに同じ値が返されます。
        // 対応するバックエンドアカウントの検索キーとして保存します。
        console.log("関連付けられたFacial ID：" + userData.facialId)
        // このユーザーに関連付け済みの任意データがあれば取得
        // enroll()のpayloadパラメーターを通じて登録時に設定したデータです。
        console.log("Payload: " + JSON.stringify(userData.payload)) // 上記のenroll()例で設定したpayloadデータ
    }).catch(errCode => {
        handleError(errCode)
    })
}

• 初期化：登録例と同様に、アプリケーションのPublic IDでfaceIOオブジェクトを初期化します。

• 認証の呼び出し：authenticate()を呼び出すと認証が始まり、必要に応じてカメラへのアクセスを求め、顔認識を実行します。locale パラメーターはウィジェットの操作言語を指定します。

• 認証結果：認証に成功すると、PromiseはuserDataオブジェクトで解決されます。userData.facialIdは、すべての認証で同じ値を保つユーザー固有の識別子です。バックエンドでユーザーを検索する主キーとして使用してください。userData.payloadには、登録時に関連付けたデータが含まれます。例：{"whoami": 123456, "email": "john.doe@example.com"}。

• エラー処理：認証の失敗を捕捉し、handleError()関数で返されたエラーコードを処理してください。詳しくはエラーコードのドキュメント で確認できます。