@faceio/fiojs 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +307 -0
- package/index.js +71 -0
- package/package.json +11 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright [yyyy] [name of copyright owner]
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
# Overview
|
|
2
|
+
|
|
3
|
+
The FACEIO Widget is a simple and elegant interface to provide **secure facial authentication experience to your users** via simple calls to the `enroll()` & `authenticate()` methods. The Widget is powered by the `fio.js `JavaScript library, which is simple enough to [integrate](https://faceio.net/integration-guide#fiojs-integration) in a matter of minutes while being flexible enough to support highly customized setups. Once implemented on your website or web-based application, you'll be able to authenticate your existing users, enroll new ones securely, with maximum convenience on their favorite browser, and at real-time thanks to passwordless experience powered by face recognition.
|
|
4
|
+
|
|
5
|
+
# `fio.js` LIBRARY INTEGRATION
|
|
6
|
+
|
|
7
|
+
`fio.js` works with regular webcams, and smartphones frontal camera on all modern browsers, **does not require biometric sensors**, and works seemingly with all websites and web applications regardless of the underlying front-end technology used (ie. React, Vue, jQuery, Vanilla Javascript, static HTML, etc.) or server-side language or framework (eg. PHP, Python, Node.js, Rust, Elixir, etc.).
|
|
8
|
+
|
|
9
|
+
It’s super quick to get FACEIO Up & Running with just few lines of code. Follow the walkthrough below to implement `fio.js` on your site.
|
|
10
|
+
|
|
11
|
+
> ## STEP 1 - IMPORT `fio.js` TO YOUR SITE
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
import faceIO from '@tobechanged/fio.js'
|
|
15
|
+
|
|
16
|
+
const faceio = new faceIO('app-public-id') // Get the application Public ID at https://console.faceio.net.
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
👉 You shouldn't run `fio.js` functions right after initiating it.
|
|
20
|
+
|
|
21
|
+
💡 Take a look to our **community contributed tutorials** [listed here](https://faceio.net/integration-guide#community-tutorials). They should help you implement `fio.js` on your website or web application using your favorite JavaScript framework whether it is React, Vue, Angular, Next or Vanilla JavaScript.
|
|
22
|
+
|
|
23
|
+
> ## STEP 2 - INVOKE THE WIDGET
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
import faceIO from '@tobechanged/fio.js'
|
|
27
|
+
|
|
28
|
+
const faceio = new faceIO('app-public-id'); // Get the application Public ID at https://console.faceio.net.
|
|
29
|
+
|
|
30
|
+
function App() {
|
|
31
|
+
return (
|
|
32
|
+
<div className="App">
|
|
33
|
+
<button onClick={enrollNewUser}>Enroll New User</button>
|
|
34
|
+
<button onClick={authenticateUser}>Authenticate User</button>
|
|
35
|
+
</div>
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
async function enrollNewUser() {
|
|
40
|
+
// call to faceio.enroll() here will automatically trigger the on-boarding process
|
|
41
|
+
}
|
|
42
|
+
async function authenticateUser(){
|
|
43
|
+
// call to faceio.authenticate() here will automatically trigger the facial authentication process
|
|
44
|
+
}
|
|
45
|
+
function handleError(errCode){
|
|
46
|
+
// Handle error here
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export default App;
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
> ## `ENROLL()` - ENROLL NEW USER
|
|
53
|
+
|
|
54
|
+
> ### SYNTAX
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
const userInfo = await faceio
|
|
58
|
+
.enroll({ parameters })
|
|
59
|
+
.catch(errCode => {
|
|
60
|
+
/* handle the error */
|
|
61
|
+
})
|
|
62
|
+
|
|
63
|
+
console.log(userInfo)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
> ### ALIAS
|
|
67
|
+
`enrol()`, `register()`, `record()`
|
|
68
|
+
|
|
69
|
+
> ### PARAMETERS
|
|
70
|
+
`enroll()` takes a **single, optional `parameters` object** with the properties to be configured. The table below lists all possible `properties` of the parameters object:
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
| Property Name | Type | Default Value | Description | |
|
|
75
|
+
|--------------------|-----------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
|
|
76
|
+
| `payload` | Any Serializable JSON | NULL | **An arbitrary set of data, you want to associate with the user being enrolled**. Example of useful payloads includes *Email Address, Name, ID, Token*, and so on. This payload will be **forwarded back to you** upon successful [future authentication](https://faceio.net/integration-guide#authenticate_return) of this particular user. Maximum payload size per user is set to 16KB. | |
|
|
77
|
+
| `permissionTimeout` | Number | 27 Seconds | **Total number of seconds to wait for the user to grant camera access permission**. Passing this delay, the ongoing `enroll()` operation is aborted and the promise is rejected with the `fioErrCode.PERMISSION_REFUSED` [error code](https://faceio.net/integration-guide#error-codes). | |
|
|
78
|
+
| `termsTimeout` | Number | 10 Minutes | **Total number of minutes to wait for the user to accept FACEIO/Host Application Terms of Service**. Passing this delay, the ongoing `enroll()` operation is aborted and the promise is rejected with the `fioErrCode.TERMS_NOT_ACCEPTED` [error code](https://faceio.net/integration-guide#error-codes). | |
|
|
79
|
+
| `idleTimeout` | Number | 27 Seconds | **Total number of seconds to wait before giving up if no faces were detected during the enrollment process**. Passing this delay, the ongoing operation is aborted and the promise is rejected with the `fioErrCode.NO_FACES_DETECTED` [error code](https://faceio.net/integration-guide#error-codes). | |
|
|
80
|
+
| `replyTimeout` | Number | 40 Seconds | **Total number of seconds to wait before giving up if the remote FACEIO processing node does not return a response (a very unlikely scenario)**. Passing this delay, the ongoing operation is aborted and the promise is rejected with the `fioErrCode.TIMEOUT` [error code](https://faceio.net/integration-guide#error-codes). | |
|
|
81
|
+
| `enrollIntroTimeout` | Number | 15 Seconds | Enrollment Widget introduction/instruction screen display delay. | |
|
|
82
|
+
| `locale` | String | auto | **Default interaction language for the Widget display**. If this value is missing or set to auto, then the interaction language will be deducted from the [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) HTTP request header. Otherwise, just pass the **BCP 47, two letter, language code** of your choice (en, ar, es, ja, de, etc.). If the requested interaction language is not supported, the fallback, default interaction language is **US English: en-us**. | |
|
|
83
|
+
| `userConsent` | Boolean | false | **If you have already collected user consent before enrollment** (eg. When the user create a new account on your Website and accept the terms), you can **set this parameter** to true. In which case, the Terms of Use consent screen is not displayed for the end user being enrolled. **It is your responsibility to explicitly ask for consent before enrolling a new user**. For additional information, please consult our Privacy Best Practices for applications. | |
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
> ### RETURN VALUE
|
|
88
|
+
|
|
89
|
+
**A Promise whose fulfillment handler receives a `userInfo` object when the user has successfully been enrolled**. On failure, the promise is rejected with one of the possible **error codes** [listed below](https://faceio.net/integration-guide#error-codes).
|
|
90
|
+
|
|
91
|
+
The table below lists all fields of the `userInfo` object returned to your web application by `enroll()` when its promise is fulfilled:
|
|
92
|
+
|
|
93
|
+
| Property Name | Type | Description | | |
|
|
94
|
+
|---------------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|---|
|
|
95
|
+
| `facialId` | UUID (String) | **A Universally Unique Identifier assigned to this particular user**. FACEIO recommend that your rely on this [Facial ID](https://faceio.net/facialid) (*which is automatically generated for each enrolled user on your application*), if you plan to uniquely identify all enrolled users on your backend for example. The Facial ID is discussed in details [here](https://faceio.net/facialid). | | |
|
|
96
|
+
| `timestamp` | Timestamp (String) | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), enrollment completion date & time. | | |
|
|
97
|
+
| `details` | Object | An object with two fields: gender and age which respectively corresponds to the Gender and Age approximation of the enrolled user. | | |
|
|
98
|
+
|
|
99
|
+
> ### EXAMPLE
|
|
100
|
+
|
|
101
|
+
```js
|
|
102
|
+
import faceIO from '@tobechanged/fio.js'
|
|
103
|
+
|
|
104
|
+
const faceio = new faceIO('app-public-id'); // Get the application Public ID at https://console.faceio.net.
|
|
105
|
+
|
|
106
|
+
function App() {
|
|
107
|
+
return (
|
|
108
|
+
<div className="App">
|
|
109
|
+
<button onClick={enrollNewUser}>Enroll New User</button>
|
|
110
|
+
</div>
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
async function enrollNewUser() {
|
|
115
|
+
const userInfo = await faceio.enroll({
|
|
116
|
+
"locale": "auto", // Default user locale
|
|
117
|
+
"payload": {
|
|
118
|
+
/* The payload we want to associate with this particular user which is forwarded back to us upon future authentication of this user.*/
|
|
119
|
+
"whoami": 123456, // Dummy ID linked to this particular user
|
|
120
|
+
"email": "john.doe@example.com"
|
|
121
|
+
}
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
alert(
|
|
125
|
+
`User Successfully Enrolled! Details:
|
|
126
|
+
Unique Facial ID: ${userInfo.facialId}
|
|
127
|
+
Enrollment Date: ${userInfo.timestamp}
|
|
128
|
+
Gender: ${userInfo.details.gender}
|
|
129
|
+
Age Approximation: ${userInfo.details.age}`
|
|
130
|
+
);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
export default App;
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
> ## `AUTHENTICATE()` - IDENTIFY/RECOGNIZE ENROLLED USERS
|
|
137
|
+
|
|
138
|
+
> ### SYNTAX
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
const userInfo = await faceio
|
|
142
|
+
.authenticate({ parameters })
|
|
143
|
+
.catch(errCode => {
|
|
144
|
+
/* handle the error */
|
|
145
|
+
})
|
|
146
|
+
|
|
147
|
+
console.log(userInfo)
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
> ### ALIAS
|
|
151
|
+
`auth()`, `recognize()`, `identify()`
|
|
152
|
+
|
|
153
|
+
> ### PARAMETERS
|
|
154
|
+
|
|
155
|
+
`authenticate()` takes a **single, optional `parameters` object** with the properties to be configured. The table below lists all possible properties of the `parameters` object:
|
|
156
|
+
|
|
157
|
+
| **Property Name** | **Type** | **Default Value** | **Description** | |
|
|
158
|
+
|-------------------|--------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
|
|
159
|
+
| `permissionTimeout` | Number | 27 Seconds | **Total number of seconds to wait for the user to grant camera access permission**. Passing this delay, the ongoing `authenticate()` operation is aborted and the promise is rejected with the `fioErrCode.PERMISSION_REFUSED` [error code](https://faceio.net/integration-guide#error-codes). | |
|
|
160
|
+
| `idleTimeout` | Number | 27 Seconds | **Total number of seconds to wait before giving up if no faces were detected during the authentication process**. Passing this delay, the ongoing operation is aborted and the promise is rejected with the `fioErrCode.NO_FACES_DETECTED` [error code](https://faceio.net/integration-guide#error-codes). | |
|
|
161
|
+
| `replyTimeout` | Number | 40 Seconds | **Total number of seconds to wait before giving up if the remote FACEIO processing node does not return a response (a very unlikely scenario)**. Passing this delay, the ongoing operation is aborted and the promise is rejected with the `fioErrCode.TIMEOUT` [error code](https://faceio.net/integration-guide#error-codes). | |
|
|
162
|
+
| `locale` | String | auto | **Default interaction language of the FACEIO Widget**. If this value is missing or set to auto, then the interaction language will be deducted from the [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) HTTP request header. Otherwise, just pass the **BCP 47, two letter, language code** of your choice (en, ar, es, ja, de, etc.). If the requested interaction language is not supported, the fallback, default interaction language is US **English: en-us**. | |
|
|
163
|
+
|
|
164
|
+
> ### RETURN VALUE
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
**A Promise whose fulfillment handler receives a `userData` object when the user has successfully been identified**. On failure, the promise is rejected with one of the possible **error codes** [listed below](https://faceio.net/integration-guide#error-codes).
|
|
169
|
+
|
|
170
|
+
The table below lists all fields of the `userData` object returned to your web application by `authenticate()` when its promise is fulfilled:
|
|
171
|
+
|
|
172
|
+
| **Property Name** | **Type** | **Description** | | |
|
|
173
|
+
|---------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|---|
|
|
174
|
+
| payload | *Any* | The arbitrary data you have already linked (if any) to this particular user during his enrollment via the payload parameter of the enroll() method. | | |
|
|
175
|
+
| `facialId` | *UUID (String)* | **The Universally Unique Identifier assigned to this particular user**. FACEIO recommend that your rely on this [Facial ID](https://faceio.net/facialid) (*which is automatically generated for each enrolled user on your application*), if you plan to uniquely identify all enrolled users on your backend for example. The Facial ID is discussed in details [here](https://faceio.net/facialid). | | |
|
|
176
|
+
| | | | | |
|
|
177
|
+
| | | | | |
|
|
178
|
+
|
|
179
|
+
> ### EXAMPLE
|
|
180
|
+
|
|
181
|
+
```js
|
|
182
|
+
import faceIO from '@tobechanged/fio.js'
|
|
183
|
+
|
|
184
|
+
const faceio = new faceIO('app-public-id'); // Get the application Public ID at https://console.faceio.net.
|
|
185
|
+
|
|
186
|
+
function App() {
|
|
187
|
+
return (
|
|
188
|
+
<div className="App">
|
|
189
|
+
<button onClick={authenticateUser}>Authenticate User</button>
|
|
190
|
+
</div>
|
|
191
|
+
);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
async function authenticateUser() {
|
|
195
|
+
const userData = await faceio.authenticate({
|
|
196
|
+
"locale": "auto", // Default user locale
|
|
197
|
+
});
|
|
198
|
+
|
|
199
|
+
console.log("Success, user identified")
|
|
200
|
+
// Grab the facial ID linked to this particular user which will be same
|
|
201
|
+
// for each of his successful future authentication. FACEIO recommend
|
|
202
|
+
// that your rely on this Facial ID if you plan to uniquely identify
|
|
203
|
+
// all enrolled users on your backend for example.
|
|
204
|
+
console.log("Linked facial Id: " + userData.facialId)
|
|
205
|
+
// Grab the arbitrary data you have already linked (if any) to this particular user
|
|
206
|
+
// during his enrollment via the payload parameter of the enroll() method.
|
|
207
|
+
console.log("Payload: " + JSON.stringify(userData.payload)) // {"whoami": 123456, "email": "john.doe@example.com"} from the enroll() example above
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
export default App;
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
> ## `RESTARTSESSION()` - REQUEST NEW USER SESSION
|
|
214
|
+
|
|
215
|
+
> ### SYNTAX
|
|
216
|
+
|
|
217
|
+
```js
|
|
218
|
+
const boolean = await faceio.restartSession({})
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
> ### PARAMETERS
|
|
222
|
+
|
|
223
|
+
*None*
|
|
224
|
+
|
|
225
|
+
> ### RETURN VALUE
|
|
226
|
+
|
|
227
|
+
`true` if the request for a new session have been granted, and ready for another round of calls to [enroll()](https://faceio.net/integration-guide#enroll) or [authenticate()](https://faceio.net/integration-guide#authenticate) for the same user. false otherwise.
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
> ## ERROR CODES
|
|
231
|
+
|
|
232
|
+
The table below lists all possible error codes that are returned from either the `enroll()` or the `authenticate()` methods when **their promises are rejected respectively**.
|
|
233
|
+
|
|
234
|
+
| **Error Code** | **Description** | **Effect on `enroll()` or `authenticate()`** | | |
|
|
235
|
+
|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|---|
|
|
236
|
+
| `fioErrCode.PERMISSION_REFUSED` | Access to the camera stream was **denied** by the end user. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
237
|
+
| `fioErrCode.TERMS_NOT_ACCEPTED` | Terms & Conditions set out by FACEIO/host application **rejected** by the end user. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
238
|
+
| `fioErrCode.SESSION_IN_PROGRESS` | Another [authentication](https://faceio.net/integration-guide#authenticate) or [enrollment](https://faceio.net/integration-guide#enroll) operation is processing. This can happen when your application logic calls more than once `enroll()` or `authenticate()` due to poor UI implementation on your side (eg. User taps twice the same button triggering the facial authentication process). **Starting with [fio.js 1.9](https://blog.pixlab.io/2022/10/fiojs-190-released-with-face-duplication-prevention), it is possible now to restart the current user session without reloading the entire HTML page via simple call to the [`restartSession()`](https://faceio.net/integration-guide#restart_sess) method**. | Ongoing operation is **still processing** and the FACEIO Widget **continue** running. Your error handler routine should probably **ignore this error code** as the operation is still ongoing. | | |
|
|
239
|
+
| `fioErrCode.FACE_DUPLICATION` | **This error code is raised when the same user tries to enroll a second time on your application. That is, his facial features are already recorded due to previous enrollment, and can no longer enroll again due to the security settings: *Prevent Same User from Enrolling Twice* or *More* being activated**. | Ongoing `enroll()` operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
240
|
+
| `fioErrCode.TIMEOUT` | **Ongoing operation timed out** (eg, camera Access Permission, ToS Accept, Face not yet detected, Server Reply, etc.). | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
241
|
+
| `fioErrCode.NO_FACES_DETECTED` | **No faces were detected** during the enroll or authentication process. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
242
|
+
| `fioErrCode.UNRECOGNIZED_FACE` | **Unrecognized/unknown face** on this application Facial Index. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
243
|
+
| `fioErrCode.MANY_FACES` | **Two or more faces** were detected during the [enroll](https://faceio.net/integration-guide#enroll) or [authentication](https://faceio.net/integration-guide#authenticate) process. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
244
|
+
| `fioErrCode.PAD_ATTACK` | Presentation attack (PAD), better know as face spoofing attempt is detected during the authentication process. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
245
|
+
| `fioErrCode.UNIQUE_PIN_REQUIRED` | Supplied PIN Code **must be unique** among other PIN's on this application. This warning code is **raised only from the `enroll()` method**, and only if you have enabled the *Enforce PIN Code Uniqueness* [Security Option](https://faceio.net/security-best-practice). | Ongoing `enroll()` operation is **still processing** until the user being enrolled **input a unique PIN code**. | | |
|
|
246
|
+
| `fioErrCode.FACE_MISMATCH` | Calculated Facial Vectors of the **user being [enrolled](https://faceio.net/integration-guide#enroll) do not matches**. This error code **is raised only from the `enroll()` method**. | Ongoing `enroll()` operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
247
|
+
| `fioErrCode.WRONG_PIN_CODE` | **Wrong PIN Code supplied** by the user being [authenticated](https://faceio.net/integration-guide#authenticate). This error code is **raised only from the `authenticate()` method**. | Ongoing `authenticate()` operation is **immediately aborted after three trials** and control is transferred to the host application. | | |
|
|
248
|
+
| `fioErrCode.NETWORK_IO` | Error while establishing network connection with the FACEIO processing node. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
249
|
+
| `fioErrCode.PROCESSING_ERR` | Server side error. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
250
|
+
| `fioErrCode.UNAUTHORIZED` | Your application is not allowed to perform the requested operation (eg. *Invalid ID, Blocked, Paused*, etc.). Refer to the [FACEIO Console](https://console.faceio.net/) for additional information. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
251
|
+
| `fioErrCode.UI_NOT_READY` | The FACEIO `fio.js` library could not be injected onto the client DOM. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
252
|
+
| `fioErrCode.TOO_MANY_REQUESTS` | Widget instantiation requests exceeded for freemium applications. **Does not apply for premium applications as `fio.js` instantiation is unmetered**. | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
253
|
+
| `fioErrCode.EMPTY_ORIGIN` | *Origin* or *Referer* HTTP request header is **empty or missing** while instantiating `fio.js`. This error is **raised only if you have enforced** the *Reject Empty Origin* [Security Option](https://faceio.net/security-best-practice#rejectMissingHeaders). | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
254
|
+
| `fioErrCode.FORBIDDDEN_ORIGIN` | Domain origin is forbidden from instantiating `fio.js`. This error is **raised only if you have created a white list of authorized domain names** via the [FACEIO Console](https://console.faceio.net/). | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
255
|
+
| `fioErrCode.FORBIDDDEN_COUNTRY` | Country ISO-3166-1 Code is forbidden from instantiating `fio.js`. This error is **raised only if you have created a white list of authorized countries** via the [FACEIO Console](https://console.faceio.net/). | Ongoing operation is **immediately aborted** and control is transferred to the host application. | | |
|
|
256
|
+
|
|
257
|
+
> ## REACTJS INTEGRATION BOILERPLATE
|
|
258
|
+
|
|
259
|
+
```js
|
|
260
|
+
import faceIO from '@tobechanged/fio.js'
|
|
261
|
+
|
|
262
|
+
const faceio = new faceIO('app-public-id');
|
|
263
|
+
|
|
264
|
+
function App() {
|
|
265
|
+
return (
|
|
266
|
+
<div className="App">
|
|
267
|
+
<button onClick={enrollNewUser}>Enroll New User</button>
|
|
268
|
+
<button onClick={authenticateUser}>Authenticate User</button>
|
|
269
|
+
</div>
|
|
270
|
+
);
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
async function enrollNewUser() {
|
|
274
|
+
const userInfo = await faceio.enroll({
|
|
275
|
+
"locale": "auto", // Default user locale
|
|
276
|
+
"payload": {
|
|
277
|
+
/* The payload we want to associate with this particular user which is forwarded back to us upon future authentication of this user.*/
|
|
278
|
+
"whoami": 123456, // Dummy ID linked to this particular user
|
|
279
|
+
"email": "john.doe@example.com"
|
|
280
|
+
}
|
|
281
|
+
});
|
|
282
|
+
|
|
283
|
+
alert(
|
|
284
|
+
`User Successfully Enrolled! Details:
|
|
285
|
+
Unique Facial ID: ${userInfo.facialId}
|
|
286
|
+
Enrollment Date: ${userInfo.timestamp}
|
|
287
|
+
Gender: ${userInfo.details.gender}
|
|
288
|
+
Age Approximation: ${userInfo.details.age}`
|
|
289
|
+
);
|
|
290
|
+
}
|
|
291
|
+
async function authenticateUser() {
|
|
292
|
+
const userData = await faceio.authenticate({
|
|
293
|
+
"locale": "auto", // Default user locale
|
|
294
|
+
});
|
|
295
|
+
|
|
296
|
+
console.log("Success, user identified")
|
|
297
|
+
// Grab the facial ID linked to this particular user which will be same
|
|
298
|
+
// for each of his successful future authentication. FACEIO recommend
|
|
299
|
+
// that your rely on this Facial ID if you plan to uniquely identify
|
|
300
|
+
// all enrolled users on your backend for example.
|
|
301
|
+
console.log("Linked facial Id: " + userData.facialId)
|
|
302
|
+
// Grab the arbitrary data you have already linked (if any) to this particular user
|
|
303
|
+
// during his enrollment via the payload parameter of the enroll() method.
|
|
304
|
+
console.log("Payload: " + JSON.stringify(userData.payload)) // {"whoami": 123456, "email": "john.doe@example.com"} from the enroll() example above
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
export default App;```
|
package/index.js
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/*eslint no-undef: 0*/
|
|
2
|
+
let internalCDN;
|
|
3
|
+
|
|
4
|
+
module.exports = class faceio {
|
|
5
|
+
constructor(appID){
|
|
6
|
+
if(internalCDN) return;
|
|
7
|
+
|
|
8
|
+
let script = document.createElement('script')
|
|
9
|
+
|
|
10
|
+
script.setAttribute('src', 'https://cdn.faceio.net/fio.js');
|
|
11
|
+
|
|
12
|
+
document.head.appendChild(script);
|
|
13
|
+
|
|
14
|
+
script.addEventListener('load', () => {
|
|
15
|
+
internalCDN = new faceIO(appID)
|
|
16
|
+
})
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Enroll new user.
|
|
20
|
+
* @param {Object} parameters enroll() takes a single, optional parameters object with the properties to be configured.
|
|
21
|
+
* @param {Object} parameters.payload An arbitrary set of data, you want to associate with the user being enrolled.
|
|
22
|
+
* @param {Number} parameters.permissionTimeout Total number of seconds to wait for the user to grant camera access permission.
|
|
23
|
+
* @param {Number} parameters.termsTimeout Total number of minutes to wait for the user to accept FACEIO/Host Application Terms of Service.
|
|
24
|
+
* @param {Number} parameters.idleTimeout Total number of seconds to wait before giving up if no faces were detected during the enrollment process.
|
|
25
|
+
* @param {Number} parameters.replyTimeout Total number of seconds to wait before giving up if the remote FACEIO processing node does not return a response (a very unlikely scenario).
|
|
26
|
+
* @param {Number} parameters.enrollIntroTimeout Enrollment Widget introduction/instruction screen display delay.
|
|
27
|
+
* @param {String} parameters.locale Default interaction language for the Widget display.
|
|
28
|
+
* @param {Boolean} parameters.userConsent If you have already collected user consent before enrollment (eg. When the user create a new account on your Website and accept the terms), you can set this parameter to true.
|
|
29
|
+
* @returns {String} facialId: A Universally Unique Identifier assigned to this particular user.
|
|
30
|
+
* @returns {String} timestamp: ISO 8601, enrollment completion date & time.
|
|
31
|
+
* @returns {Object} details: An object with two fields: gender and age which respectively corresponds to the Gender and Age approximation of the enrolled user.
|
|
32
|
+
* @example
|
|
33
|
+
* faceio.enroll({
|
|
34
|
+
* "locale": "auto", // Default user locale
|
|
35
|
+
* "payload": {
|
|
36
|
+
* "whoami": 123456, // Dummy ID linked to this particular user
|
|
37
|
+
* "email": "john.doe@example.com"
|
|
38
|
+
* }
|
|
39
|
+
* });
|
|
40
|
+
*/
|
|
41
|
+
async enroll(parameters) {
|
|
42
|
+
return await internalCDN.enroll(parameters)
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Transactionally authenticate previously enrolled users.
|
|
47
|
+
* @param {Object} parameters authenticate() takes a single, optional parameters object with the properties to be configured.
|
|
48
|
+
* @param {Number} parameters.permissionTimeout Total number of seconds to wait for the user to grant camera access permission.
|
|
49
|
+
* @param {Number} parameters.idleTimeout Total number of seconds to wait before giving up if no faces were detected during the authentication process.
|
|
50
|
+
* @param {Number} parameters.replyTimeout Total number of seconds to wait before giving up if the remote FACEIO processing node does not return a response (a very unlikely scenario)
|
|
51
|
+
* @param {String} parameters.locale Default interaction language of the FACEIO Widget.
|
|
52
|
+
* @returns {any} payload: The arbitrary data you have already linked (if any) to this particular user during his enrollment via the payload parameter of the enroll() method.
|
|
53
|
+
* @returns {String} facialId: A Universally Unique Identifier assigned to this particular user.
|
|
54
|
+
* @example
|
|
55
|
+
* faceio.authenticate({
|
|
56
|
+
* "locale": "auto" // Default user locale
|
|
57
|
+
* });
|
|
58
|
+
*/
|
|
59
|
+
async authenticate(parameters) {
|
|
60
|
+
return await internalCDN.authenticate(parameters)
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Purge the current session and request a new one.
|
|
65
|
+
* @returns true if the request for a new session have been granted, and ready for another round of calls to enroll() or authenticate() for the same user. false otherwise.
|
|
66
|
+
*/
|
|
67
|
+
|
|
68
|
+
async restartSession() {
|
|
69
|
+
return await internalCDN.restartSession()
|
|
70
|
+
}
|
|
71
|
+
}
|
package/package.json
ADDED