diff --git a/CHANGELOG.md b/CHANGELOG.md index a628d5d43..cd2ba619e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,17 +6,11 @@ This change log file is based on best practices from [Keep a Changelog](http://k This project adheres to [Semantic Versioning](http://semver.org/). Breaking changes result in a different MAJOR version. UI changes that might break customizations on top of the SDK will be treated as breaking changes too. This project adheres to the Node [default version scheme](https://docs.npmjs.com/misc/semver). -## [next-version] +## [14.15.0] ### Changed -## [13.6.1] - 2023-10-24 - -### Changed - -### Fixed - -- Fix disabled submit button in country selection in PoA step +- Overall architecture. See [MIGRATION.md](./MIGRATION.md) for more details. ## [13.6.0] - 2023-10-24 @@ -1652,8 +1646,7 @@ Install with `npm install onfido-sdk-ui@0.12.0-rc.1` - NPM (commonjs2) style of importing the library now works -[next-version]: https://github.com/onfido/onfido-sdk-ui/compare/13.6.1...development -[13.6.1]: https://github.com/onfido/onfido-sdk-ui/compare/13.6.0...13.6.1 +[next-version]: https://github.com/onfido/onfido-sdk-ui/compare/13.6.0...development [13.6.0]: https://github.com/onfido/onfido-sdk-ui/compare/13.5.1...13.6.0 [13.5.1]: https://github.com/onfido/onfido-sdk-ui/compare/13.5.0...13.5.1 [13.5.0]: https://github.com/onfido/onfido-sdk-ui/compare/13.4.0...13.5.0 diff --git a/MIGRATION.md b/MIGRATION.md index fbe1f5e0f..18a4b4adb 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,1626 +1,50 @@ -# Onfido Web SDK Migration Guide +# Breaking Changes -The guides below are provided to ease the transition of existing applications using the Onfido SDK from one version to another that introduces breaking API changes. +This documents the breaking changes between the Web SDK v13.7.0 and the Web SDK v14+. -## `next` +## General changes -The `uploadFallback` option has been removed. Users with mobile devices that do not have a camera or lack camera browser support will not be able to complete the flow. Please reach out to your CSM for details. +- The "split bundle" library will no longer be available on `npm`. Please use the default `npm` package instead. +- The separate `style.css` import is no longer required as the Onfido stylesheet is included in the main library. -`tearDown` is deprecated in favor of `safeTearDown` which is a promise that you can await to know when the sdk tear down is complete. +## Visual & Flow changes -For all supported language the copy for the following string(s) has been added: - -## Added strings - -- `avc_face_capture:alert:mic_conflict_title` -- `doc_auto_capture:footer:manual_fallback_generic_document_back` -- `doc_auto_capture:footer:manual_fallback_generic_document_front` -- `doc_auto_capture:footer:position_generic_document_back` -- `doc_auto_capture:footer:position_generic_document_front` -- `doc_confirmation:body_generic_document` -- `doc_submit:title_generic_document_back` -- `doc_submit:title_generic_document_front` -- `photo_upload:body_id_back` -- `photo_upload:body_id_front` -- `profile_data:components::id_type_select::aus_specific::other` -- `profile_data:components::id_type_select::bra_specific::other` -- `profile_data:components::id_type_select::bra_specific::tax_id` -- `profile_data:components::id_type_select::driving_license` -- `profile_data:components::id_type_select::esp_specific::identity_card` -- `profile_data:components::id_type_select::gha_specific::social_insurance` -- `profile_data:components::id_type_select::identity_card` -- `profile_data:components::id_type_select::ind_specific::tax_id` -- `profile_data:components::id_type_select::ken_specific::other` -- `profile_data:components::id_type_select::nga_specific::identity_card` -- `profile_data:components::id_type_select::nga_specific::other` -- `profile_data:components::id_type_select::nga_specific::tax_id` -- `profile_data:components::id_type_select::other` -- `profile_data:components::id_type_select::passport` -- `profile_data:components::id_type_select::placeholder` -- `profile_data:components::id_type_select::tax_id` -- `profile_data:components::id_type_select::voter_id` -- `profile_data::field_labels::arg_specific::national_id_value` -- `profile_data::field_labels::can_specific::national_id_value` -- `profile_data::field_labels::chl_specific::national_id_value` -- `profile_data::field_labels::chn_specific::national_id_value` -- `profile_data::field_labels::col_specific::national_id_value` -- `profile_data::field_labels::dnk_specific::national_id_value` -- `profile_data::field_labels::fin_specific::national_id_value` -- `profile_data::field_labels::hkg_specific::national_id_value` -- `profile_data::field_labels::ita_specific::national_id_value` -- `profile_data::field_labels::jpn_specific::national_id_value` -- `profile_data::field_labels::lux_specific::national_id_value` -- `profile_data::field_labels::national_id_type` -- `profile_data::field_labels::national_id_value` -- `profile_data::field_labels::phl_specific::national_id_value` -- `profile_data::field_labels::pol_specific::national_id_value` -- `profile_data::field_labels::prt_specific::national_id_value` -- `profile_data::field_labels::tur_specific::national_id_value` -- `profile_data::field_validation::arg_specific::invalid_national_id_value` -- `profile_data::field_validation::arg_specific::required_national_id_value` -- `profile_data::field_validation::bra_specific::invalid_other` -- `profile_data::field_validation::bra_specific::invalid_tax_id` -- `profile_data::field_validation::bra_specific::required_other` -- `profile_data::field_validation::bra_specific::required_tax_id` -- `profile_data::field_validation::can_specific::invalid_national_id_value` -- `profile_data::field_validation::can_specific::required_national_id_value` -- `profile_data::field_validation::chl_specific::invalid_national_id_value` -- `profile_data::field_validation::chl_specific::required_national_id_value` -- `profile_data::field_validation::chn_specific::invalid_national_id_value` -- `profile_data::field_validation::chn_specific::required_national_id_value` -- `profile_data::field_validation::col_specific::invalid_national_id_value` -- `profile_data::field_validation::col_specific::required_national_id_value` -- `profile_data::field_validation::dnk_specific::invalid_national_id_value` -- `profile_data::field_validation::dnk_specific::required_national_id_value` -- `profile_data::field_validation::esp_specific::invalid_identity_card` -- `profile_data::field_validation::esp_specific::invalid_other` -- `profile_data::field_validation::esp_specific::required_identity_card` -- `profile_data::field_validation::esp_specific::required_other` -- `profile_data::field_validation::fin_specific::invalid_national_id_value` -- `profile_data::field_validation::fin_specific::required_national_id_value` -- `profile_data::field_validation::gha_specific::invalid_social_insurance` -- `profile_data::field_validation::gha_specific::required_social_insurance` -- `profile_data::field_validation::hkg_specific::invalid_national_id_value` -- `profile_data::field_validation::hkg_specific::required_national_id_value` -- `profile_data::field_validation::invalid_driving_license` -- `profile_data::field_validation::invalid_voter_id` -- `profile_data::field_validation::required_id_type` -- `profile_data::field_validation::required_id_value` -- `profile_data::field_validation::required_passport` -- `profile_data::field_validation::required_driving_license` -- `profile_data::field_validation::required_voter_id` -- `profile_data::field_validation::ita_specific::invalid_national_id_value` -- `profile_data::field_validation::jpn_specific::invalid_national_id_value` -- `profile_data::field_validation::jpn_specific::required_national_id_value` -- `profile_data::field_validation::ken_specific::invalid_other` -- `profile_data::field_validation::ken_specific::required_other` -- `profile_data::field_validation::lux_specific::invalid_national_id_value` -- `profile_data::field_validation::lux_specific::required_national_id_value` -- `profile_data::field_validation::mex_specific::invalid_identity_card` -- `profile_data::field_validation::mex_specific::invalid_tax_id` -- `profile_data::field_validation::mex_specific::required_identity_card` -- `profile_data::field_validation::mex_specific::required_tax_id` -- `profile_data::field_validation::mys_specific::invalid_national_id_value` -- `profile_data::field_validation::mys_specific::required_national_id_value` -- `profile_data::field_validation::nga_specific::invalid_identity_card` -- `profile_data::field_validation::nga_specific::invalid_other` -- `profile_data::field_validation::nga_specific::invalid_tax_id` -- `profile_data::field_validation::nga_specific::required_identity_card` -- `profile_data::field_validation::nga_specific::required_other` -- `profile_data::field_validation::nga_specific::required_tax_id` -- `profile_data::field_validation::phl_specific::invalid_national_id_value` -- `profile_data::field_validation::phl_specific::required_national_id_value` -- `profile_data::field_validation::pol_specific::invalid_national_id_value` -- `profile_data::field_validation::pol_specific::required_national_id_value` -- `profile_data::field_validation::prt_specific::invalid_national_id_value` -- `profile_data::field_validation::prt_specific::required_national_id_value` -- `profile_data::field_validation::reference::translation` -- `profile_data::field_validation::sgp_specific::invalid_national_id_value` -- `profile_data::field_validation::sgp_specific::required_national_id_value` -- `profile_data::field_validation::swe_specific::invalid_national_id_value` -- `profile_data::field_validation::swe_specific::required_national_id_value` -- `profile_data::field_validation::tur_specific::invalid_national_id_value` -- `profile_data::field_validation::tur_specific::required_national_id_value` -- `profile_data::national_id_number_title` -- `cross_device::button_primary_upload` -- `cross_device_intro::subtitle_upload` -- `profile_data::field_validation::rou_specific::invalid_national_id_value` -- `profile_data::field_validation::rou_specific::required_national_id_value` -- `profile_data::field_labels::rou_specific::national_id_value` - -## `11.0.0` - -The deprecated `useLiveDocumentCapture` document option has been removed from Onfido's SDK. Please remove it. -The deprecated `useWebcam` document option has been removed from Onfido's SDK. Please remove it. - -## Added strings - -- `profile_data.components.id_type_select.placeholder` -- `profile_data.components.id_type_select.identity_card` -- `profile_data.components.id_type_select.passport` -- `profile_data.components.id_type_select.driving_license` -- `profile_data.components.id_type_select.tax_id` -- `profile_data.components.id_type_select.voter_id` -- `profile_data.components.id_type_select.aus_specific.other` -- `profile_data.components.id_type_select.esp_specific.identity_card` -- `profile_data.components.id_type_select.other` -- `profile_data.components.id_type_select.bra_specific.tax_id` -- `profile_data.components.id_type_select.bra_specific.other` -- `profile_data.components.id_type_select.ind_specific.tax_id` -- `profile_data.field_labels.national_id_type` -- `profile_data.field_labels.national_id_value` -- `profile_data.field_labels.arg_specific.national_id_value` -- `profile_data.field_labels.can_specific.national_id_value` -- `profile_data.field_labels.chn_specific.national_id_value` -- `profile_data.field_labels.ita_specific.national_id_value` -- `profile_data.field_labels.sgp_specific.national_id_value` -- `profile_data.field_labels.swe_specific.national_id_value` -- `profile_data.field_labels.tur_specific.national_id_value` -- `profile_data.field_validation.arg_specific.invalid_national_id_value` -- `profile_data.field_validation.bra_specific.invalid_tax_id` -- `profile_data.field_validation.bra_specific.invalid_other` -- `profile_data.field_validation.can_specific.invalid_national_id_value` -- `profile_data.field_validation.chn_specific.invalid_national_id_value` -- `profile_data.field_validation.ita_specific.invalid_national_id_value` -- `profile_data.field_validation.mex_specific.invalid_identity_card` -- `profile_data.field_validation.mex_specific.invalid_tax_id` -- `profile_data.field_validation.sgp_specific.invalid_national_id_value` -- `profile_data.field_validation.esp_specific.invalid_identity_card` -- `profile_data.field_validation.esp_specific.invalid_other` -- `profile_data.field_validation.swe_specific.invalid_national_id_value` -- `profile_data.field_validation.tur_specific.invalid_national_id_value` -- `profile_data.field_validation.invalid_driving_license` -- `profile_data.field_validation.invalid_voter_id` -- `profile_data.field_validation.invalid_passport` -- `profile_data.field_validation.invalid_national_id_value` -- `profile_data.national_id_number_title` -- `profile_data.components.id_type_select.mex_specific.identity_card` -- `profile_data.components.id_type_select.mex_specific.tax_id` -- `profile_data.field_validation.arg_specific.required_national_id_value` -- `profile_data.field_validation.bra_specific.required_tax_id` -- `profile_data.field_validation.bra_specific.required_other` -- `profile_data.field_validation.can_specific.required_national_id_value` -- `profile_data.field_validation.chn_specific.required_national_id_value` -- `profile_data.field_validation.ita_specific.required_national_id_value` -- `profile_data.field_validation.mex_specific.required_identity_card` -- `profile_data.field_validation.mex_specific.required_tax_id` -- `profile_data.field_validation.sgp_specific.required_national_id_value` -- `profile_data.field_validation.esp_specific.required_identity_card` -- `profile_data.field_validation.esp_specific.required_other` -- `profile_data.field_validation.swe_specific.required_national_id_value` -- `profile_data.field_validation.tur_specific.required_national_id_value` -- `profile_data.field_validation.required_national_id_value` -- `profile_data.field_validation.required_national_id_type` -- `profile_data.field_validation.required_national_voter_id` -- `profile_data.field_validation.required_national_passport` -- `profile_data.field_validation.required_national_driving_license` -- `profile_data.field_validation.hkg_specific.required_national_id_value` -- `profile_data.field_validation.hkg_specific.invalid_national_id_value` -- `profile_data.field_labels.hkg_specific.national_id_value` -- `profile_data.field_validation.jpn_specific.required_national_id_value` -- `profile_data.field_validation.jpn_specific.invalid_national_id_value` -- `profile_data.field_labels.jpn_specific.national_id_value` -- `profile_data.field_validation.chl_specific.required_national_id_value` -- `profile_data.field_validation.chl_specific.invalid_national_id_value` -- `profile_data.field_labels.chl_specific.national_id_value` -- `profile_data.field_validation.col_specific.required_national_id_value` -- `profile_data.field_validation.col_specific.invalid_national_id_value` -- `profile_data.field_labels.col_specific.national_id_value` -- `profile_data.field_validation.fin_specific.required_national_id_value` -- `profile_data.field_validation.fin_specific.invalid_national_id_value` -- `profile_data.field_labels.fin_specific.national_id_value` -- `profile_data.field_validation.gha_specific.required_social_insurance` -- `profile_data.field_validation.gha_specific.invalid_social_insurance` -- `profile_data.components.id_type_select.gha_specific.social_insurance` -- `profile_data.field_validation.ken_specific.required_other` -- `profile_data.field_validation.ken_specific.invalid_other` -- `profile_data.components.id_type_select.ken_specific.other` -- `profile_data.field_validation.lux_specific.required_national_id_value` -- `profile_data.field_validation.lux_specific.invalid_national_id_value` -- `profile_data.field_labels.lux_specific.national_id_value` -- `profile_data.field_validation.mys_specific.required_national_id_value` -- `profile_data.field_validation.mys_specific.invalid_national_id_value` -- `profile_data.field_labels.mys_specific.national_id_value` -- `profile_data.field_validation.nga_specific.required_other` -- `profile_data.field_validation.nga_specific.invalid_other` -- `profile_data.components.id_type_select.nga_specific.other` -- `profile_data.field_validation.nga_specific.required_identity_card` -- `profile_data.field_validation.nga_specific.invalid_identity_card` -- `profile_data.components.id_type_select.nga_specific.identity_card` -- `profile_data.field_validation.nga_specific.required_tax_id` -- `profile_data.field_validation.nga_specific.invalid_tax_id` -- `profile_data.components.id_type_select.nga_specific.tax_id` -- `profile_data.field_validation.phl_specific.required_national_id_value` -- `profile_data.field_validation.phl_specific.invalid_national_id_value` -- `profile_data.field_labels.phl_specific.national_id_value` -- `profile_data.field_validation.pol_specific.required_national_id_value` -- `profile_data.field_validation.pol_specific.invalid_national_id_value` -- `profile_data.field_labels.pol_specific.national_id_value` -- `profile_data.field_validation.prt_specific.required_national_id_value` -- `profile_data.field_validation.prt_specific.invalid_national_id_value` -- `profile_data.field_labels.prt_specific.national_id_value` - -## `10.4.0` - -## Updated strings - -- `avc_intro:disclaimer` (ar, bg, cs, en_US, hr, hy, zh_CH, zh_TW) -- `doc_auto_capture:position_license_front` (en_GB) -- `avc_intro:button_primary_ready` (en_US) -- `avc_connection_error:button_secondary_restart_recording` (pl) -- `avc_no_face_detected:button_primary_restart` (pl) -- `welcome:trial_message` (pt) -- `welcome:info_original_document` (all) -- `avc_intro:disclaimer_camera_and_audio_on` (all) -- `nfc_scan:sheet:success` (all) - -## `10.1.0` -> `10.2.0` - -We have added new language(s): - -- Arabic -- Armenian -- Bulgarian -- Chinese (Simplified) -- Chinese (Traditional) -- Croatian -- Danish -- English (United States) -- Estonian -- Finnish -- French (Canadian) -- Greek -- Hebrew -- Hindi -- Hungarian -- Indonesian -- Japanese -- Korean -- Latvian -- Lithuanian -- Malay -- Norwegian -- Persian -- Portuguese (Brazil) -- Russian -- Serbian -- Slovak -- Spanish (Latin America) -- Swedish -- Thai -- Turkish -- Ukrainian -- Vietnamese - -## `9.1.4` -> `10.1.0` - -We have added new language(s): **Czech, Polish, and Romanian** -The `useLiveDocumentCapture` beta document option has been deprecated from Onfido's SDK. You should think about removing it before the next major version. -The `useWebcam` alpha document option has been deprecated from Onfido's SDK. You should think about removing it before the next major version. - -## Updated strings - -- `profile_data.field_validation.too_long_line1` - -## Added strings - -- doc_auto_capture.button_accessibility -- doc_auto_capture.footer.position_identity_card_front -- doc_auto_capture.footer.position_identity_card_back -- doc_auto_capture.footer.position_residence_permit_front -- doc_auto_capture.footer.position_residence_permit_back -- doc_auto_capture.footer.position_license_front -- doc_auto_capture.footer.position_license_back -- doc_auto_capture.footer.position_passport -- doc_auto_capture.footer.manual_fallback_identity_card_front -- doc_auto_capture.footer.manual_fallback_identity_card_back -- doc_auto_capture.footer.manual_fallback_residence_permit_front -- doc_auto_capture.footer.manual_fallback_residence_permit_back -- doc_auto_capture.footer.manual_fallback_license_front -- doc_auto_capture.footer.manual_fallback_license_back -- doc_auto_capture.footer.manual_fallback_passport -- doc_auto_capture.footer.capturing -- doc_auto_capture.footer.captured -- doc_auto_capture.frame.flip_document -- doc_auto_capture.frame.hold_still -- doc_auto_capture.frame.no_document - -## `9.1.1` -> `9.1.2` - -The **English**, **Spanish**, **German**, **French**, **Italian**, **Dutch** and **Portuguese** copy for the following string(s) has been added: - -### Added strings - -- `welcome.trial_message` -- `welcome.start_workflow_button_trial` - -## `8.2.0` -> `9.0.0` - -The **English**, **Spanish**, **German**, **French**, **Italian**, **Dutch** and **Portuguese** copy for the following string(s) has been added: - -### Added strings - -- `avc_confirmation.button_primary_upload` -- `avc_confirmation.subtitle` -- `avc_confirmation.title` -- `avc_connection_error.button_primary_retry_upload` -- `avc_connection_error.button_secondary_restart_recording` -- `avc_connection_error.subtitle` -- `avc_connection_error.title` -- `avc_face_alignment.feedback_move_back` -- `avc_face_alignment.feedback_move_closer` -- `avc_face_alignment.feedback_no_face_detected` -- `avc_face_alignment.feedback_not_centered` -- `avc_face_alignment.title` -- `avc_face_capture.alert.timeout_body` -- `avc_face_capture.alert.timeout_button_primary` -- `avc_face_capture.alert.timeout_title` -- `avc_face_capture.alert.too_fast_body` -- `avc_face_capture.alert.too_fast_button_primary` -- `avc_face_capture.alert_too_fast_title` -- `avc_face_capture.title` -- `avc_face_capture.title_completed` -- `avc_intro.button_primary_ready` -- `avc_intro.disclaimer` -- `avc_intro.list_item_one` -- `avc_intro.list_item_two` -- `avc_intro.subtitle` -- `avc_intro.title` -- `avc_no_face_detected.button_primary_restart` -- `avc_no_face_detected.list_item_eyes` -- `avc_no_face_detected.list_item_face` -- `avc_no_face_detected.list_item_lighting` -- `avc_no_face_detected.list_item_mask` -- `avc_no_face_detected.title` -- `avc_uploading.title` - -The **German, English, Spanish, French, Italian, Dutch, and Portuguese** copy for the following string(s) has been changed: - -## Added: - -- `doc_select.subtitle_entire_page` -- `doc_select.subtitle_front_back` -- `doc_select.subtitle_photo_page` -- `livenessV2.error_reload_instructions` -- `livenessV2.intro_note_no1` -- `livenessV2.intro_note_no2` -- `livenessV2.intro_ready_button` -- `livenessV2.intro_subtitle` -- `livenessV2.intro_warning` -- `livenessV2.success_main_button` -- `livenessV2.success_title` -- `outro.body_government_letter` -- `permission_recovery.subtitle_cam_old` -- `poa_cancel` -- `poa_err_invalid_file.message` -- `poa_err_invalid_file.ok` -- `poa_err_invalid_file.title` -- `profile_data.components.nationality_select.placeholder` -- `profile_data.components.pan.placeholder` -- `profile_data.components.ssn.placeholder` -- `profile_data.field_labels.email` -- `profile_data.field_labels.mobile_number` -- `profile_data.field_labels.nationality` -- `profile_data.field_labels.pan` -- `profile_data.field_labels.ssn` -- `profile_data.field_validation.required_email` -- `profile_data.field_validation.required_mobile_number` -- `profile_data.field_validation.required_nationality` -- `profile_data.field_validation.required_pan` -- `profile_data.field_validation.required_ssn` -- `profile_data.field_validation.too_short_first_name` -- `profile_data.field_validation.valid_email` -- `profile_data.field_validation.valid_mobile_number` -- `profile_data.field_validation.valid_pan` -- `profile_data.field_validation.valid_ssn` -- `profile_data.field_validation.gbr_specific.invalid_postcode` -- `retry_feedback.button_primary` -- `retry_feedback_id_expired.subtitle` -- `retry_feedback_id_expired.title` -- `retry_feedback_id_generic.subtitle` -- `retry_feedback_id_generic.title` -- `retry_feedback_id_unaccepted.subtitle` -- `retry_feedback_id_unaccepted.title` -- `retry_feedback_selfie_generic.subtitle` -- `retry_feedback_selfie_generic.title` -- `workflow_complete.pass.description` -- `workflow_complete.pass.title` -- `workflow_complete.reject.description` -- `workflow_complete.reject.title` - -## Deleted: - -- `profile_data.field_validation.usa_specific.required_postcode` -- `profile_data.field_validation.usa_specific.too_short_postcode` -- `profile_data.field_validation.usa_specific.too_long_postcode` -- `photo_upload.body_government_letter` - -## Updated: - -- `country_select.poa_alert.intro` -- `doc_select.section.input_placeholder_country` - -The **German** copy for the following string(s) has been changed: - -## Added: - -- `doc_capture.button_primary` -- `doc_select.pill` -- `doc_select.section.input_country_not_found` -- `generic.errors.expired_token.instruction` -- `generic.errors.expired_token.message` -- `selfie_capture.body` -- `selfie_capture.button_primary` -- `video_capture.body_stop` -- `welcome.doc_video_subtitle` -- `workflow_erros.generic_title` -- `workflow_erros.no_workflow_run_id` -- `workflow_erros.reload_app` -- `workflow_erros.task_not_completed` -- `workflow_erros.task_not_retrieved` -- `workflow_erros.task_not_supported` - -## Updated: - -- `doc_select.button_government_letter` -- `doc_select.button_government_letter_detail` -- `doc_submit.title_government_letter` -- `profile_data.field_validation.required_first_name` -- `doc_confirmation.body_id` -- `doc_confirmation.body_license` -- `doc_confirmation.body_passport` -- `doc_confirmation.body_permit` -- `poa_intro.list_most_recent` -- `poa_intro.list_shows_address` -- `doc_video_capture.header_step2` - -## Deleted: - -- `profile_data.field_validation.too_long__line2` -- `profile_data.field_validation.too_long__line3` -- `doc_select.section.input_placeholder_country_copy` - -The **English** copy for the following string(s) has been changed: - -## Added: - -- `doc_capture.button_primary` -- `doc_select.pill` -- `selfie_capture.body` -- `selfie_capture.button_primary` -- `video_capture.body_stop` -- `welcome.doc_video_subtitle` -- `doc_confirmation.body` -- `doc_select.button_bank_statement_non_uk` -- `profile_data.field_validation.too_long__line1` -- `profile_data.prompt.details_timeout` - -## Updated: - -- `welcome.start_workflow_button` -- `poa_guidance.subtitle_tax_letter` -- `poa_guidance.subtitle_benefits_letter` -- `cross_device_checklist.list_item_poa` -- `doc_confirmation.body_bank_statement` -- `doc_confirmation.body_benefits_letter` -- `doc_confirmation.body_bill` -- `doc_confirmation.body_tax_letter` -- `poa_guidance.subtitle_bank_statement` -- `poa_intro.list_matches_signup` -- `profile_data.address_title` -- `profile_data.personal_information_title` -- `workflow_erros.task_not_supported` - -## Deleted: - -- `profile_data.field_labels.usa_specific.ssn` -- `profile_data.field_validation.too_long_line1` -- `profile_data.field_validation.too_long_line2` -- `profile_data.field_validation.too_long_line3` -- `profile_data.field_validation.usa_specific.required_ssn` -- `profile_data.field_validation.usa_specific.invalid_ssn` -- `profile_data.prompt.detail_timeout` -- `cross_device_checklist.list_item_active_video` -- `poa_guidance.subtitle_government_letter` - -The **Spanish** copy for the following string(s) has been changed: - -## Added: - -- `doc_capture.button_primary` -- `doc_select.pill` -- `doc_select.section.input_country_not_found` -- `generic.errors.expired_token.instruction` -- `generic.errors.expired_token.message` -- `selfie_capture.body` -- `selfie_capture.button_primary` -- `video_capture.body_stop` -- `welcome.doc_video_subtitle` -- `workflow_erros.generic_title` -- `workflow_erros.no_workflow_run_id` -- `workflow_erros.reload_app` -- `workflow_erros.task_not_completed` -- `workflow_erros.task_not_retrieved` -- `workflow_erros.task_not_supported` - -## Updated: - -- `doc_select.button_government_letter` -- `doc_select.button_government_letter_detail` -- `doc_submit.title_government_letter` -- `profile_data.field_validation.required_first_name` -- `doc_confirmation.body_id` -- `doc_confirmation.body_license` -- `doc_confirmation.body_passport` -- `doc_confirmation.body_permit` -- `profile_data.field_validation.too_long_town` -- `welcome.start_workflow_button` -- `profile_data.country_of_residence_title` - -## Deleted: - -- `profile_data.field_validation.too_long__line2` -- `profile_data.field_validation.too_long__line3` -- `doc_select.section.input_placeholder_country_copy` - -The **French** copy for the following string(s) has been changed: - -## Added: - -- `doc_capture.button_primary` -- `doc_select.pill` -- `doc_select.section.input_country_not_found` -- `generic.errors.expired_token.instruction` -- `generic.errors.expired_token.message` -- `selfie_capture.body` -- `selfie_capture.button_primary` -- `video_capture.body_stop` -- `welcome.doc_video_subtitle` -- `workflow_erros.generic_title` -- `workflow_erros.no_workflow_run_id` -- `workflow_erros.reload_app` -- `workflow_erros.task_not_completed` -- `workflow_erros.task_not_retrieved` -- `workflow_erros.task_not_supported` - -## Updated: - -- `doc_select.button_government_letter` -- `doc_select.button_government_letter_detail` -- `doc_submit.title_government_letter` -- `profile_data.field_validation.required_first_name` -- `doc_confirmation.body_id` -- `doc_confirmation.body_license` -- `doc_confirmation.body_passport` -- `doc_confirmation.body_permit` -- `profile_data.field_validation.too_long_town` -- `poa_guidance.subtitle_tax_letter` -- `poa_guidance.subtitle_benefits_letter` -- `cross_device_session_linked.list_item_sent_by_you` - -## Deleted: - -- `profile_data.field_validation.too_long__line2` -- `profile_data.field_validation.too_long__line3` -- `doc_select.section.input_placeholder_country_copy` - -The **Italian** copy for the following string(s) has been changed: - -## Added: - -- `doc_capture.button_primary` -- `doc_select.pill` -- `doc_select.section.input_country_not_found` -- `generic.errors.expired_token.instruction` -- `generic.errors.expired_token.message` -- `selfie_capture.body` -- `selfie_capture.button_primary` -- `video_capture.body_stop` -- `welcome.doc_video_subtitle` -- `workflow_erros.generic_title` -- `workflow_erros.no_workflow_run_id` -- `workflow_erros.reload_app` -- `workflow_erros.task_not_completed` -- `workflow_erros.task_not_retrieved` -- `workflow_erros.task_not_supported` - -## Updated: - -- `doc_select.button_government_letter` -- `doc_select.button_government_letter_detail` -- `doc_submit.title_government_letter` -- `profile_data.field_validation.required_first_name` -- `doc_confirmation.body_id` -- `doc_confirmation.body_license` -- `doc_confirmation.body_passport` -- `doc_confirmation.body_permit` -- `profile_data.field_validation.too_long_town` -- `welcome.start_workflow_button` -- `poa_guidance.subtitle_tax_letter` -- `avc_uploading.title` - -## Deleted: - -- `profile_data.field_validation.too_long__line2` -- `profile_data.field_validation.too_long__line3` -- `doc_select.section.input_placeholder_country_copy` - -The **Portuguese** copy for the following string(s) has been changed: - -## Added: - -- `doc_capture.button_primary` -- `doc_select.pill` -- `doc_select.section.input_country_not_found` -- `generic.errors.expired_token.instruction` -- `generic.errors.expired_token.message` -- `selfie_capture.body` -- `selfie_capture.button_primary` -- `video_capture.body_stop` -- `welcome.doc_video_subtitle` -- `workflow_erros.generic_title` -- `workflow_erros.no_workflow_run_id` -- `workflow_erros.reload_app` -- `workflow_erros.task_not_completed` -- `workflow_erros.task_not_retrieved` -- `workflow_erros.task_not_supported` - -## Updated: - -- `doc_select.button_government_letter` -- `doc_select.button_government_letter_detail` -- `doc_submit.title_government_letter` -- `profile_data.field_validation.required_first_name` -- `doc_confirmation.body_id` -- `doc_confirmation.body_license` -- `doc_confirmation.body_passport` -- `doc_confirmation.body_permit` -- `profile_data.field_validation.too_long_town` -- `welcome.start_workflow_button` - -## Deleted: - -- `profile_data.field_validation.too_long__line2` -- `profile_data.field_validation.too_long__line3` -- `doc_select.section.input_placeholder_country_copy` - -The **Dutch** copy for the following string(s) has been changed: - -## Added: - -- `doc_select.section.input_country_not_found` -- `generic.errors.expired_token.instruction` -- `generic.errors.expired_token.message` -- `workflow_erros.generic_title` -- `workflow_erros.no_workflow_run_id` -- `workflow_erros.reload_app` -- `workflow_erros.task_not_completed` -- `workflow_erros.task_not_retrieved` -- `workflow_erros.task_not_supported` - -## Updated: - -- `doc_select.button_government_letter` -- `doc_select.button_government_letter_detail` -- `doc_submit.title_government_letter` -- `profile_data.field_validation.required_first_name` -- `profile_data.field_validation.too_long_town` -- `poa_intro.list_most_recent` -- `poa_intro.list_shows_address` - -## Deleted: - -- `profile_data.field_validation.too_long__line2` -- `profile_data.field_validation.too_long__line3` -- `doc_select.section.input_placeholder_country_copy` - -The **English**, **Spanish**, **German**, **French**, **Italian**, **Dutch** and **Portuguese** copy for the following string(s) has been added: - -### Added strings - -- `avc_confirmation.button_primary_upload` -- `avc_confirmation.subtitle` -- `avc_confirmation.title` -- `avc_connection_error.button_primary_retry_upload` -- `avc_connection_error.button_secondary_restart_recording` -- `avc_connection_error.subtitle` -- `avc_connection_error.title` -- `avc_face_alignment.feedback_move_back` -- `avc_face_alignment.feedback_move_closer` -- `avc_face_alignment.feedback_no_face_detected` -- `avc_face_alignment.feedback_not_centered` -- `avc_face_alignment.title` -- `avc_face_capture.alert.timeout_body` -- `avc_face_capture.alert.timeout_button_primary` -- `avc_face_capture.alert.timeout_title` -- `avc_face_capture.alert.too_fast_body` -- `avc_face_capture.alert.too_fast_button_primary` -- `avc_face_capture.alert_too_fast_title` -- `avc_face_capture.title` -- `avc_face_capture.title_completed` -- `avc_intro.button_primary_ready` -- `avc_intro.disclaimer` -- `avc_intro.list_item_one` -- `avc_intro.list_item_two` -- `avc_intro.subtitle` -- `avc_intro.title` -- `avc_no_face_detected.button_primary_restart` -- `avc_no_face_detected.list_item_eyes` -- `avc_no_face_detected.list_item_face` -- `avc_no_face_detected.list_item_lighting` -- `avc_no_face_detected.list_item_mask` -- `avc_no_face_detected.title` -- `avc_uploading.title` - -## `8.1.1` -> `8.2.0` - -The **English**, **Spanish**, **German**, **French**, **Italian**, **Dutch** and **Portuguese** copy for the following string(s) has been added: - -### Added strings - -- `welcome.start_workflow_button` -- `doc_multi_frame_capture.capture_progress_title` -- `doc_multi_frame_capture.instructions_title_front` -- `doc_multi_frame_capture.instructions_title_back` -- `profile_data.country_of_residence_title` -- `profile_data.personal_information_title` -- `profile_data.address_title` -- `profile_data.field_labels.first_name` -- `profile_data.field_labels.last_name` -- `profile_data.field_labels.dob` -- `profile_data.field_labels.country` -- `profile_data.field_labels.line1` -- `profile_data.field_labels.line2` -- `profile_data.field_labels.line3` -- `profile_data.field_labels.town` -- `profile_data.field_labels.postcode` -- `profile_data.field_labels.gbr_specific.town` -- `profile_data.field_labels.gbr_specific.postcode` -- `profile_data.field_labels.usa_specific.line1_helper_text` -- `profile_data.field_labels.usa_specific.line2_helper_text` -- `profile_data.field_labels.usa_specific.state` -- `profile_data.field_labels.usa_specific.postcode` -- `profile_data.field_validation.required_first_name` -- `profile_data.field_validation.required_last_name` -- `profile_data.field_validation.required_dob` -- `profile_data.field_validation.required_country` -- `profile_data.field_validation.required_line1` -- `profile_data.field_validation.required_postcode` -- `profile_data.field_validation.invalid` -- `profile_data.field_validation.invalid_dob` -- `profile_data.field_validation.too_short_last_name` -- `profile_data.field_validation.too_short_postcode` -- `profile_data.field_validation.too_long_last_name` -- `profile_data.field_validation.too_long_first_name` -- `profile_data.field_validation.too_long_postcode` -- `profile_data.field_validation.too_long__line1` -- `profile_data.field_validation.too_long__line2` -- `profile_data.field_validation.too_long__line3` -- `profile_data.field_validation.too_long_town` -- `profile_data.field_validation.gbr_specific.required_postcode` -- `profile_data.field_validation.gbr_specific.too_short_postcode` -- `profile_data.field_validation.gbr_specific.too_long_postcode` -- `profile_data.field_validation.usa_specific.required_state` -- `profile_data.field_validation.usa_specific.required_postcode` -- `profile_data.field_validation.usa_specific.too_short_postcode` -- `profile_data.field_validation.usa_specific.too_long_postcode` -- `profile_data.field_optional` -- `profile_data.button_continue` -- `profile_data.components.country_select.placeholder` -- `profile_data.components.state_select.placeholder` -- `profile_data.prompt.header_timeout` -- `profile_data.prompt.details_timeout` -- `profile_data.field_labels.usa_specific.ssn` -- `profile_data.field_validation.usa_specific.required_ssn` -- `profile_data.field_validation.usa_specific.invalid_ssn` -- `doc_select.section.header_country` -- `doc_select.section.input_country_not_found` -- `doc_select.section.input_placeholder_country` -- `doc_select.section.header_doc_type` -- `doc_select.subtitle_country` - -### Removed strings - -- `profile_data.personal_details_title` -- `profile_data.address_detials_title` -- `profile_data.button_submit` - -### Change in SDK Options - -- The deprecated `showCountrySelection` option has been removed. - -## `8.0.0` -> `8.1.1` - -### Added strings - -- `generic.errors.geoblocked_error.message` -- `generic.errors.geoblocked_error.instruction` - -## `6.20.0` -> `8.0.0` - -### Change in SDK Options - -- The `userConsent` step can't be added in the `steps` options anymore. This step is now enabled from your Onfido Dashboard. - -## `6.19.0` -> `6.20.0` - -### Change in UX flow for Proof of Address Step - -- Proof of Address step now has an Issuing Country Selection screen before the Document Type Selection screen. - -## `6.19.0` -> `6.20.0` - -The **English**, **Spanish**, **German**, **French**, **Italian**, **Dutch** and **Portuguese** copy for the follinw string(s) has changed: - -### Added strings - -- `permission_recovery.title_both` -- `permission_recovery.subtitle_both` -- `permission_recovery.list_header_both` -- `permission_recovery.list_item_how_to_both` -- `permission.title_both` -- `permission.subtitle_both` -- `permission.body_both` -- `permission.button_primary_both` - -### Changed strings - -- `permission_recovery.subtitle_cam` - -## `6.13.0` -> `6.14.0` - -The **English**, **Spanish**, **German**, **French**, **Italian** and **Portuguese** copy for the following string(s) has changed: - -### Added strings - -- `cross_device_session_linked.button_primary` -- `cross_device_session_linked.info` -- `cross_device_session_linked.list_item_desktop_open` -- `cross_device_session_linked.list_item_sent_by_you` -- `cross_device_session_linked.subtitle` -- `cross_device_session_linked.title` - -### Changed strings - -- `generic.errors.request_error.message` - -## `6.11.1` -> `6.12.0` - -The **English**, **Spanish**, **German**, **French**, **Italian** and **Portuguese** copy for the following string(s) has changed: - -### Changed strings - -- `video_intro.list_item_actions` - -## `6.10.2` -> `6.11.1` - -The **English**, **Spanish**, **German**, **French**, **Italian** and **Portuguese** copy for the following string(s) has changed: - -### Added strings - -- `doc_capture.detail.folded_doc_front` -- `doc_capture.header_folded_doc_front` -- `doc_capture.prompt.button_card` -- `doc_capture.prompt.button_paper` -- `doc_capture.prompt.title_id` -- `doc_capture.prompt.title_license` -- `doc_video_capture.button_primary_fallback` -- `doc_video_capture.button_primary_fallback_end` -- `doc_video_capture.detail_step2` -- `doc_video_capture.header` -- `doc_video_capture.header_paper_doc_step2` -- `doc_video_capture.header_passport` -- `doc_video_capture.header_passport_progress` -- `doc_video_capture.header_step1` -- `doc_video_capture.header_step2` -- `doc_video_capture.prompt.detail_timeout` -- `doc_video_capture.stepper` -- `doc_video_capture.success_accessibility` -- `doc_video_confirmation.button_secondary` -- `doc_video_confirmation.title` -- `video_capture.prompt.header_timeout` -- `video_confirmation.body` -- `video_confirmation.button_primary` -- `video_confirmation.button_secondary` -- `welcome.list_header_doc_video` -- `welcome.list_item_doc_video_timeout` - -## `6.9.0` -> `6.10.0` - -### Added strings - -- `doc_capture.detail.folded_doc_front` -- `doc_capture.header_folded_doc_front` -- `doc_capture.prompt.button_card` -- `doc_capture.prompt.button_paper` -- `doc_capture.prompt.title_id` -- `doc_capture.prompt.title_license` -- `doc_video_capture.button_primary_fallback` -- `doc_video_capture.button_primary_fallback_end` -- `doc_video_capture.detail_step2` -- `doc_video_capture.header` -- `doc_video_capture.header_paper_doc_step2` -- `doc_video_capture.header_passport` -- `doc_video_capture.header_passport_progress` -- `doc_video_capture.header_step1` -- `doc_video_capture.header_step2` -- `doc_video_capture.prompt.detail_timeout` -- `doc_video_capture.stepper` -- `doc_video_capture.success_accessibility` -- `doc_video_confirmation.button_secondary` -- `doc_video_confirmation.title` -- `video_capture.button_primary_start` -- `video_capture.prompt.header_timeout` -- `video_capture.header.challenge_turn_forward` -- `video_confirmation.body` -- `video_confirmation.button_primary` -- `video_confirmation.button_secondary` -- `welcome.subtitle` -- `welcome.list_header_doc_video` -- `welcome.list_header_webcam` -- `welcome.list_item_doc` -- `welcome.list_item_poa` -- `welcome.list_item_doc_video_timeout` -- `welcome.list_item_selfie` - -The **English**, **Spanish**, **German**, and **French** copy for the following string(s) has changed: - -### Changed strings - -- `video_capture.button_primary_finish` -- `video_capture.button_primary_next` -- `video_capture.header.challenge_turn_left` -- `video_capture.header.challenge_turn_right` -- `welcome.title` -- `welcome.next_button` -- `cross_device_checklist.list_item_doc_multiple` -- `cross_device_checklist.list_item_doc_one` -- `cross_device_checklist.list_item_selfie` -- `cross_device_checklist.list_item_video` -- `cross_device_checklist.subtitle` -- `cross_device_checklist.title` -- `doc_confirmation.alert.no_doc_detail` -- `doc_confirmation.alert.no_doc_title` -- `doc_confirmation.body_id` -- `doc_confirmation.body_license` -- `doc_confirmation.body_passport` -- `doc_confirmation.body_permit` -- `doc_confirmation.button_primary_upload` -- `doc_select.button_passport_detail` -- `doc_select.title` -- `generic.errors.no_face.instruction` -- `generic.errors.no_face.message` -- `get_link.subtitle_url` -- `outro.body` -- `outro.title` -- `permission.body_cam` -- `selfie_capture.alert.timeout.detail` -- `selfie_capture.title` -- `selfie_confirmation.subtitle` -- `selfie_confirmation.title` -- `selfie_intro.subtitle` -- `upload_guide.button_primary` -- `video_capture.body` -- `video_capture.body_record` -- `video_confirmation.title` -- `video_intro.button_primary` -- `video_intro.list_item_actions` -- `video_intro.list_item_speak` - -Only the **Spanish**, **German**, and **French** copy for the following string(s) has changed: - -- `country_select.search.input_placeholder` - -### Removed strings - -- `video_capture.body_next` -- `video_capture.body_stop` -- `video_capture.button_stop_accessibility` -- `video_capture.header.challenge_turn_template` -- `welcome.description_p_1` -- `welcome.description_p_2` - -## `6.8.0` -> `6.9.0` - -The **English**, **Spanish**, **German**, and **French** copy for the following string(s) has changed: - -### Added strings - -- `auth_accessibility.back_button` -- `auth_cam_encrypt.loader` -- `auth_cam_start.loader` -- `auth_capture_start.body` -- `auth_capture_start.button_primary` -- `auth_capture_start.title` -- `auth_capture_start.feedback.center_face` -- `auth_capture_start.feedback.conditions_too_bright` -- `auth_capture_start.feedback.conditions_too_dark` -- `auth_capture_start.feedback.head_not_upright` -- `auth_capture_start.feedback.neutral_expression` -- `auth_capture_start.feedback.not_looking_straight` -- `auth_capture_start.feedback.remove_sunglasses` -- `auth_capture_start.feedback.steady_count_1` -- `auth_capture_start.feedback.steady_count_2` -- `auth_capture_start.feedback.steady_count_3` -- `auth_capture.feedback.center_face` -- `auth_capture.feedback.even_lighting` -- `auth_capture.feedback.eye_level` -- `auth_capture.feedback.face_not_found` -- `auth_capture.feedback.head_not_upright` -- `auth_capture.feedback.move_back` -- `auth_capture.feedback.move_close` -- `auth_capture.feedback.move_closer` -- `auth_capture.feedback.not_looking_straight` -- `auth_capture.feedback.steady` -- `auth_error.cam_encryption.body` -- `auth_error.cam_encryption.button_primary` -- `auth_error.cam_encryption.button_primary_firefox` -- `auth_error.cam_encryption.subtitle` -- `auth_error.cam_encryption.table_header_1` -- `auth_error.cam_encryption.table_header_2` -- `auth_error.cam_encryption.table_row_1_cell_1` -- `auth_error.cam_encryption.table_row_1_cell_1_firefox` -- `auth_error.cam_encryption.table_row_1_cell_2` -- `auth_error.cam_encryption.table_row_1_cell_2_firefox` -- `auth_error.cam_encryption.table_row_2_cell_1` -- `auth_error.cam_encryption.table_row_2_cell_2` -- `auth_error.cam_encryption.table_row_3_cell_1` -- `auth_error.cam_encryption.table_row_3_cell_2` -- `auth_error.cam_encryption.title` -- `auth_full_screen.body` -- `auth_full_screen.button_primary` -- `auth_full_screen.title` -- `auth_permission_denied.body_cam` -- `auth_permission_denied.button_primary_cam` -- `auth_permission.body_cam` -- `auth_permission.button_primary_cam` -- `auth_permission.title_cam` -- `auth_progress.loader` -- `auth_retry.body_blur` -- `auth_retry.body_neutral_expression` -- `auth_retry.body_too_bright` -- `auth_retry.button_primary` -- `auth_retry.subtitle` -- `auth_retry.title` -- `auth_upload_pass.body` - -### Changed strings - -The **English**, **Spanish**, **German**, and **French** copy for the following string(s) has changed: - -## `6.6.0` -> `6.8.0` - -### Added strings - -The **English** copy for the following string(s) has been added: - -`user_consent_load_fail.button_primary` -`user_consent_load_fail.detail` -`user_consent_load_fail.prompt.title` - -**Note**: The consent screen copy is only available in **English** - -## `6.5.0` -> `6.6.0` - -### Added strings - -The **English** copy for the following string(s) has been added: - -`user_consent.button_primary` -`user_consent.button_secondary` -`user_consent.prompt.button_primary` -`user_consent.prompt.button_secondary` -`user_consent.prompt.no_consent_detail` -`user_consent.prompt.no_consent_title` - -**Note**: The consent screen copy is only available in **English** - -## `6.4.0` -> `6.5.0` - -From version 6.5.0, TypeScript is officially supported. If you previously installed -[the DefinitelyTyped package](https://www.npmjs.com/package/@types/onfido-sdk-ui), -you can safely remove it because the distributed NPM package already contains -an `index.d.ts` declaration file. - -## `6.1.0` -> `6.2.0` - -### Changed strings - -The **English**, **Spanish**, **German**, and **French** copy for the following string(s) has changed: - -- `upload_guide.image_detail_blur_label` -- `upload_guide.image_detail_glare_label` -- `upload_guide.image_detail_good_label` - -## `6.0.1` -> `6.1.0` - -### Introduce `migrate_locales` script - -From version `6.1.0`, Web SDK will use a new locale key naming convention that better supports scalability. -As a result, many key names will be changed and this might affect the integrator's custom locale options. -The `migrate_locales` script will help integrators migrate from the older key name convention -to the new one with minimal hassle. - -To use the script: - -- Upgrade `onfido-sdk-ui` package to latest version `6.1.0` -- Create a JSON file containing custom locales which was fed to `Onfido.init()` method. For instance: +- The default screen size of the Web SDK has changed on desktop: + **Until version 13 `510px x 598px`** ```javascript - // your-custom-language.json - { - "locale": "en_US", // untouched keys - "phrases": { // required key - "capture": { - "driving_licence": { - "front": { - "instructions": "Driving license on web" - } - } - }, - "complete.message": "Complete message on web" - }, - "mobilePhrases": { // optional key - "capture.driving_licence.front.instructions": "Driving licence on mobile", - "complete": { - "message": "Complete message on mobile" - } - } - } + width: 94vw; + max-width: 32em; + height: 37.5em; + // Results in width: 510px, height: 598px (by 16px font-size) ``` -- Consume the script directly from `node_modules/.bin`: - - ```shell - $ migrate_locales --help # to see the script's usage - - $ migrate_locales --list-versions # to list all supported versions - - Supported versions: - * from v0.0.1 to v1.0.0 - - $ migrate_locales \ - --from-version v0.0.1 \ - --to-version v1.0.0 \ - --in-file your-custom-language.json \ - --out-file your-custom-language-migrated.json - ``` - -- The migrated data should look like this: + **From version 14 onwards - `600px x 800px`** ```javascript - // your-custom-language-migrated.json - { - "locale": "en_US", - "phrases": { - "new_screen": { // renamed key in nested object - "driving_licence": { - "front": { - "instructions": "Driving license on web" - } - } - }, - "screen_1.complete.message": "Complete message on web", // 2 generated keys from 1 old key - "screen_2.complete.message": "Complete message on web" - "mobilePhrases": { // force nesting because standalone `mobilePhrases` will be deprecated soon - "new_screen.driving_licence.front.instructions": "Driving licence on mobile", // renamed key in dot notation - "screen_1": { // 2 generated keys from 1 old key - "complete": { - "message": "Complete message on mobile" - } - }, - "screen_2": { - "complete": { - "message": "Complete message on mobile" - } - } - } - }, - } + width: 100%; + height: 100%; + max-width: 600px; + max-height: 800px; + min-height: 600px; ``` -- Notes: the script will preserve: - - - Order of the keys - - Format: if your old keys are nested as an object, the migrated keys will be nested too. Otherwise, - if your old keys are string with dot notation, the migrated keys will be string too. - -## `5.10.0` -> `6.0.0` - -### Change in UX flow for Document step - -- Document step now has a Issuing Country Selection screen after the Document Type Selection screen. This screen is never displayed for **passport** documents and is disabled by default when only 1 document is preselected using the `documentTypes` option. This screen can still be included in the document capture flow of non-passport preselected documents by enabling the `showCountrySelection` option in the Document step configuration. - -### Example of Document step with Country Selection for a preselected non-passport document - -```json -{ - "steps": [ - "welcome", - { - "type": "document", - "options": { - "documentTypes": { - "passport": false, - "driving_licence": false, - "national_identity_card": true - }, - "showCountrySelection": true - } - }, - "complete" - ] -} -``` - -### Example of Document step without Country Selection for a preselected non-passport document (default behaviour) - -```json -{ - "steps": [ - "welcome", - { - "type": "document", - "options": { - "documentTypes": { - "passport": false, - "driving_licence": false, - "national_identity_card": true - }, - "showCountrySelection": false - } - }, - "complete" - ] -} -``` - -### Example of Document step configurations with preselected documents where Country Selection will still be displayed - -```json -{ - "steps": [ - "welcome", - { - "type": "document", - "options": { - "documentTypes": { - "passport": true, - "driving_licence": true, - "national_identity_card": true - } - } - }, - "complete" - ] -} -``` - -```json -{ - "steps": [ - "welcome", - { - "type": "document", - "options": { - "documentTypes": { - "passport": true, - "national_identity_card": true, - "driving_licence": false - } - } - }, - "complete" - ] -} -``` - -### Added strings - -- `country_selection.error` -- `country_selection.dropdown_error` -- `country_selection.placeholder` -- `country_selection.search` -- `country_selection.submit` -- `country_selection.title` -- `capture.residence_permit.front.title` -- `capture.residence_permit.back.title` -- `confirm.residence_permit.message` -- `document_selector.identity.residence_permit_hint` -- `residence_permit` - -### Changed strings - -The **English**, **Spanish**, **German**, and **French** copy for the following string(s) has changed: - -- `document_selector.identity.title` -- `document_selector.identity.hint` - -### Changed keys - -The following keys have been renamed: - -- `errors.server_error.instruction` => `errors.request_error.instruction` -- `errors.server_error.message` => `errors.request_error.message` - -### Removed strings - -- `SMS_BODY` - -## `5.7.0` -> `5.10.0` - -### Added strings - -- `image_quality_guide.title` -- `image_quality_guide.sub_title` -- `image_quality_guide.all_good` -- `image_quality_guide.not_cut_off` -- `image_quality_guide.no_glare` -- `image_quality_guide.no_blur` -- `image_quality_guide.image_alt_text` -- `image_quality_guide.next_step` -- `mobilePhrases.image_quality_guide.title` -- `mobilePhrases.image_quality_guide.next_step` - -### Changed strings - -The **English** copy for the following string(s) has changed: - -- `errors.invalid_capture` - -## `5.6.0` -> `5.7.0` - -With release 5.7.0 there are breaking changes that will affect integrators with customised languages or UI copy. - -### Added strings - -- `capture.face.intro.title` -- `capture.face.intro.subtitle` -- `capture.face.intro.selfie_instruction` -- `capture.face.intro.glasses_instruction` -- `capture.face.intro.accessibility.selfie_capture_tips` - -- `continue` - -- `cross_device.intro.title` -- `cross_device.intro.sub_title` -- `cross_device.intro.description_li_1` -- `cross_device.intro.description_li_2` -- `cross_device.intro.description_li_3` -- `cross_device.intro.action` - -- `cross_device.link.sms_sub_title` -- `cross_device.link.copy_link_sub_title` -- `cross_device.link.qr_code_sub_title` -- `cross_device.link.options_divider_label` -- `cross_device.link.sms_option` -- `cross_device.link.copy_link_option` -- `cross_device.link.qr_code_option` - -- `cross_device.link.qr_code.help_label` -- `cross_device.link.qr_code.help_step_1` -- `cross_device.link.qr_code.help_step_2` - -- `cross_device.link.copy_link.action` -- `cross_device.link.copy_link.success` - -### Removed strings - -- `cross_device.intro.document.title` -- `cross_device.intro.document.take_photos` -- `cross_device.intro.document.action` - -- `cross_device.intro.face.title` -- `cross_device.intro.face.take_photos` -- `cross_device.intro.face.action` - -- `cross_device.link.sub_title` -- `cross_device.link.link_copy.action` -- `cross_device.link.link_copy.success` - -### Changed strings - -The **English** and **Spanish** copy for the following string(s) has changed: - -- `cross_device.link.copy_link_label` -- `cross_device.link.sms_label` - -## `5.0.0` -> `5.6.0` - -With release 5.6.0 there is a breaking change that will affect integrators with customised languages or UI copy. - -**Note:** The string custom translation version scheme has changed, going forward if the strings translations change it will result in a MINOR version change, therefore you are responsible for testing your translated layout in case you are using custom translations or copy. - -### Added strings - -- `capture.switch_device` - -### Removed strings - -- `cross_device.switch_device.submessage` - -### Changed strings - -The **English** and **Spanish** copy for the following string(s) has changed: - -- `capture.upload_file` -- `errors.invalid_size.message` -- `errors.invalid_size.instruction` - -The **English** copy for the following string(s) has changed: - -- `capture.driving_licence.front.title` -- `capture.driving_licence.back.title` -- `capture.national_identity_card.front.title` -- `capture.national_identity_card.back.title` -- `capture.passport.front.title` -- `capture.bank_building_society_statement.front.title` -- `capture.utility_bill.front.title` -- `capture.benefit_letters.front.title` -- `capture.council_tax.front.title` -- `errors.invalid_type.message` -- `errors.invalid_type.instruction` - -## `4.0.0` -> `5.0.0` - -We have changed the behaviour of the document step. If the document step is initialised with only one document type, the document selector screen will not be displayed. If your application relies on the document selector screen, even if you are picking only one document, you will have to implement that UI yourself. - -## `3.1.0` -> `4.0.0` - -### Import breaking changes - -We have changed how the SDK is exported, in order to reduce redundant transpiled code and to better trim dead code too. This led to a size reduction overall. - -However, this has potentially created a breaking change for those consuming the SDK with an ES style of import. Classic window style import and commonjs require should work the same. - -#### Example of old behaviour - -```js -import Onfido from 'onfido-sdk-ui' - -Onfido.init(...) -``` - -#### Example of new behaviour - -```js -import {init} from 'onfido-sdk-ui' -init(...) -``` - -or - -```js -import * as Onfido from 'onfido-sdk-ui' -Onfido.init(...) -``` - -### Style Breaking change - -- We have internally changed the CSS units used in the SDK to be relative (`em`) units. - -Therefore, if you previously set the font-size of `.onfido-sdk-ui-Modal-inner`, it is recommended that you remove this `font-size` override. - -This is because we are looking to make the SDK compatible with `em`, but first we need to remove media queries which are not really compatible with that unit. - -#### Example of old behaviour - -```css -.onfido-sdk-ui-Modal-inner { - font-size: 20px; -} -``` - -#### Example of new behaviour - -```css -.a-more-specific-selector { - font-size: 20px; -} -``` - -## `2.8.0` -> `3.0.0` - -### Breaking changes - -- Removed support for `buttonId`. From this version you will need to create a function that launches the SDK when a trigger element (ie a button) is clicked. - -### Example of old behaviour - -```html - - - - -
- -``` - -### Example of new behaviour - -```html - - - - - -
- -``` - -## `1.1.0` -> `2.0.0` - -### Breaking changes - -- Removed `onDocumentCapture` that used to be fired when the document had been successfully captured, confirmed by the user and uploaded to the Onfido API -- Removed `onFaceCapture` callbacks that used to be fired when the face has beed successfully captured, confirmed by the user and uploaded to the Onfido API. -- Removed `getCaptures` function that used to return the document and face files captured during the flow. -- Changed the behaviour of `onComplete` callback. It used to return an object that contained all captures, now it doesn't return any data. - -### Example of old behaviour - -```js -Onfido.init({ - token: 'YOUR_JWT_TOKEN', - containerId: 'onfido-mount', - onDocumentCapture: function (data) { - /*callback for when the*/ console.log( - 'document has been captured successfully', - data - ) - }, - onFaceCapture: function (data) { - /*callback for when the*/ console.log('face capture was successful', data) - }, - onComplete: function (capturesHash) { - console.log('everything is complete') - // data returned by the onComplete callback including the document and face files captured during the flow - console.log(capturesHash) - // function that used to return the document and face files captured during the flow. - console.log(Onfido.getCaptures()) - }, -}) -``` - -### Example of new behaviour - -```js -Onfido.init({ - // the JWT token that you generated earlier on - token: 'YOUR_JWT_TOKEN', - // id of the element you want to mount the component on - containerId: 'onfido-mount', - onComplete: function () { - console.log('everything is complete') - // You can now trigger your backend to start a new check - }, -}) -``` +- The "Capture Guide" screen has moved earlier in the document capture flow +- The "Completion" screens at the end of the cross-device flow have been streamlined and no longer show differences between the document and face capture steps +- Cross-device flow change: the user is now prevented from going cross-device after the first side (front) has already been captured. The full capture flow has to be either on the desktop or on the mobile device +- The `crossDeviceClientIntroProductName` subtitle customization option has been deprecated. Please use the standard language customization process to override the entire subtitle +- Merger of options `_crossDeviceLinkMethods: ['qr_code' | 'copy_link' | 'sms']` and `_initialCrossDeviceLinkView` into `_initialCrossDeviceLinkView: ['qr_code', 'copy_link', 'sms']` where the default cross-device option is the first element in the list. Note the change in separators from `|` to `,` + +## `Onfido.init()` parameters + +- `onUserExit` has been deprecated and the `user_consent_denied` type is now returned in the `onError` callback +- Ability for the Web SDK to self-load in a modal has been deprecated: + - `onModalRequestClose` + - `useModal` + - `isModalOpen` + - `shouldCloseOnOverlayClick` + - `autoFocusOnInitialScreenTitle` +- Removal of `uploadFallback` option for the `document` and `face` steps. This feature is now only configurable in the Onfido systems. +- `useMemoryHistory` has been deprecated +- `handle.setOptions()` has been deprecated, no longer allowing changing options after bootstrapping the SDK +- The fallback options under the `face` step now only occur on the mobile session of a user as all fallbacks due to device capabilities will always trigger a cross-device flow first. diff --git a/README.md b/README.md index d60710ce0..6f57e0165 100644 --- a/README.md +++ b/README.md @@ -1,425 +1,449 @@ -# Onfido SDK UI Layer +# Onfido Smart Capture Web SDK [![Build Status](https://travis-ci.org/onfido/onfido-sdk-ui.svg?branch=master)](https://travis-ci.org/onfido/onfido-sdk-ui) [![npm version](https://img.shields.io/npm/v/onfido-sdk-ui)](https://www.npmjs.com/package/onfido-sdk-ui) ## Table of contents -- [Overview](#overview) -- [General tips](#general-tips) -- [Getting started](#getting-started) -- [Handling callbacks](#handling-callbacks) -- [Removing the SDK](#removing-the-sdk) -- [Initialization options](#initialization-options) -- [Customizing the SDK](#customizing-the-sdk) -- [Creating checks](#creating-checks) -- [User Analytics](#user-analytics) -- [Premium Enterprise Features](#premium-enterprise-features) -- [Going live](#going-live) -- [Accessibility](#accessibility) -- [TypeScript](#typescript) +- [1. Overview](#overview) +- [2. Importing the library](#importing-the-library) +- [3. Initializing the SDK](#initializing-the-sdk) +- [4. Cross-device navigation](#cross-device-navigation) +- [5. Completing a session](#completing-a-session) +- [Advanced flow customization](#advanced-flow-customization) +- [Advanced callbacks](#advanced-callbacks) +- [Self-hosted cross-device URL](#self-hosted-cross-device-url) - [More information](#more-information) ## Overview -The Onfido Web SDK provides a set of components for JavaScript applications to capture identity documents and selfie photos, videos, and motion captures for the purpose of identity verification. +The Onfido Smart Capture SDKs provide a set of screens and functionality allowing applications to implement user identity verification flows. Each SDK contains: -The SDK offers a number of benefits to help you create the best identity verification experience for your customers: - -- Carefully designed UI to guide your customers through the entire capture process for photos, videos, or motion captures -- Modular design to help you seamlessly integrate the capture process for photos, videos, or motion captures into your application flow +- Carefully designed UX to guide your customers through the different photo or video capture processes +- Modular design to help you seamlessly integrate the different photo or video capture processes into your application's flow - Advanced image quality detection technology to ensure the quality of the captured images meets the requirement of the Onfido identity verification process, guaranteeing the best success rate - Direct image upload to the Onfido service, to simplify integration +- A suite of advanced fraud detection signals to protect against malicious users -⚠️ Note: the SDK is only responsible for capturing photos, videos, and motion captures. You still need to access the [Onfido API](https://documentation.onfido.com/) to manage applicants and perform checks. +All Onfido Smart Capture SDKs are orchestrated using [Onfido Studio](https://developers.onfido.com/guide/onfido-studio-product) workflows with only minor customization differences between the available platforms. -![Various views from the SDK](demo/screenshots.jpg) +The Onfido Web SDK is specifically designed for integrating web applications and easily managing cross-device experiences. -## General tips +![Various views from the SDK](../demo/screenshots.jpg) -For use in a mobile device, it is recommended to set up the SDK to use the full screen of the device. Otherwise, there may not be enough room to display all critical elements of the SDK. +### Environments and testing with the SDK -## Getting started +Two environments exist to support the Onfido SDK integrations: -The following content assumes you're using our API v3 versions for backend calls. If you are currently using API `v2` please refer to [this migration guide](https://developers.onfido.com/guide/api-v2-to-v3-migration-guide) for more information. +- 'sandbox' - to be used for testing with sample documents +- 'live' - to be used only with real documents and in production apps - +The environment being used is determined by the API token that is used to generate the necessary [SDK token](#sdk-authentication). -> ℹ️ If you are integrating using Onfido Studio please see out [Studio integration guide](ONFIDO_STUDIO.md). +### Going Live - +Once you are satisfied with your integration and are ready to go live, please contact [client-support@onfido.com](mailto:client-support@onfido.com) to obtain a live API token. You will have to replace the sandbox token in your code with the live token. -### 1. Obtain an API token +Check that you have entered correct billing details inside your [Onfido Dashboard](https://onfido.com/dashboard/), before going live. -In order to start integrating, you'll need an [API token](https://documentation.onfido.com/#api-tokens). +## Importing the library & staying up-to-date -You can use our [sandbox](https://documentation.onfido.com/#sandbox-testing) environment to test your integration. To use the sandbox, you'll need to generate a sandbox API token in your [Onfido Dashboard](https://onfido.com/dashboard/api/tokens). +The Onfido Web SDK can be added to your project in two ways: -⚠️ **Note: You must never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server.** +- Directly in the web application in a `script` tag or as an `import` +- As part of your project build as a library imported from [NPM](https://www.npmjs.com/package/onfido-sdk-ui) -#### 1.1 Regions +To benefit from the latest features and patches released by Onfido and minimize the size of the script used, it is highly recommended to use an integration method that leverages the Onfido CDN, as detailed in the following sections. -Onfido offers region-specific environments. Refer to the [Regions](https://documentation.onfido.com/#regions) section in the API documentation for token format and API base URL information. +**Note** that while Onfido hosts the CDN and ensures the script availability at runtime, any project using the SDK library from NPM would require its hosting. -### 2. Create an applicant +### Direct CDN integration -To create an applicant from your backend server, make request to the ['create applicant' endpoint](https://documentation.onfido.com/#create-applicant), using a valid API token. +The quickest and simplest way to integrate the Onfido Web SDK is to use the Onfido-hosted library. -⚠️ Note: Different report types have different minimum requirements for applicant data. For a Document or Facial Similarity report, the minimum applicant details required are `first_name` and `last_name`. +From SDK 12.3.1 onwards, the version number you subscribe to can vary, depending on your needs: -```shell -$ curl https://api.onfido.com/v3/applicants \ - -H 'Authorization: Token token=' \ - -d 'first_name=John' \ - -d 'last_name=Smith' +- subscribing to a major release (e.g. `v14`) means Onfido will update to the latest available patch and minor release +- subscribing to a minor level release (e.g. `v14.11`) means Onfido will update to the latest available patch release +- subscribing to a specific patch release (e.g. `v14.11.0`) will fix the library files to that SDK release + +### Importing the SDK in an html `script` tag + +```html + + ``` -The JSON response will contain an `id` field containing an UUID that identifies the applicant. Once you pass the applicant ID to the SDK, documents, photos, videos, and motion captures uploaded by that instance of the SDK will be associated with that applicant. +**Note** that prior to [version 12.3.1](https://github.com/onfido/onfido-sdk-ui/blob/12.3.0/README.md#43-cdn), the CDN path was `https://assets.onfido.com/web-sdk-releases//onfido.min.js`. -### 3. Generate an SDK token +Also note that from version 14 onwards, a separate stylesheet is no longer required as it will be included with the default library. -The SDK is authenticated using SDK tokens. Each authenticated instance of the SDK will correspond to a single Onfido applicant. You’ll need to generate and include a new token each time you initialize the Web SDK. +### Importing the SDK with a JavaScript `import` directive -⚠️ Note: You must never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server. +The library can also be invoked directly within an object or component: -To generate an SDK token, make a request to the ['generate SDK token' endpoint](https://documentation.onfido.com/#generate-web-sdk-token), including the applicant ID and a valid referrer. +```javascript +// ES6 module import +import { init } from 'onfido-sdk-ui' -```shell -$ curl https://api.onfido.com/v3/sdk_token \ - -H 'Authorization: Token token=' \ - -F 'applicant_id=' \ - -F 'referrer=' +// commonjs style require +var Onfido = require('onfido-sdk-ui') ``` -| Parameter | Notes | -| -------------- | ---------------------------------------------------------------- | -| `applicant_id` | **required**
Specifies the applicant for the SDK instance | -| `referrer` | **optional**
The referrer URL pattern | +The CSS style will be included inline with the JS code when the library is imported. -⚠️ Note: SDK tokens expire after 90 minutes. +**Note**: The library is Browser only, it does not support the Node Context. -#### 3.1 The referrer argument +### Integrating with an NPM package -The referrer argument specifies the URL of the web page where the Web SDK will be used. The referrer sent by the browser must match the referrer URL pattern in the SDK token for the SDK to successfully authenticate. +NPM is a public repository of libraries available for download and integration into web/native apps. Onfido has been publishing all its SDKs there for convenience to customers. -The referrer pattern guarantees that other malicious websites cannot reuse the SDK token in case it is lost. You can read more about referrer policy [in Mozilla's -documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy). +The Web SDK version 14 will continue with the existing [package name](https://www.npmjs.com/package/onfido-sdk-ui): -⚠️ Note: You must use a site referrer policy that lets the -`Referer` header be sent. If your policy does not allow this (e.g. -`Referrer-Policy: no-referrer`), then you'll receive a `401 bad_referrer` -error when trying to use the Web SDK. +```bash +npm install onfido-sdk-ui +``` -Permitted referrer patterns are as follows: +or -| Section | Format | Example | -| -------- | -------------------------------------------- | ----------------------------- | -| Referrer | `scheme://host/path` | `https://*.//*` | -| Scheme | `*` or `http` or `https` | `https` | -| Host | `*` or `*.` then any char except `/` and `*` | `*.` | -| Path | Any char or none | `/*` | +```bash +yarn add onfido-sdk-ui +``` -An example of a valid referrer is `https://*.example.com/example_page/*`. +From version 14 onwards, the `onfido-sdk-ui` package will, by default, be connected to the Onfido CDN. In addition to the benefits of using a CDN and the library being directly in your build process, core functions will also be typed when used with [Typesript](#typescript). -### 4. Import the library +Full bundles that consist of the full library will also be made available via NPM. -You can either: + -- use our CDN -- import directly into your HTML page -- use npm +> From version 14 onwards, "split bundles" are no longer supported. Onfido recommends the use of either the direct or NPM CDN integration. -#### 4.1 CDN + -You can use hosted versions of the library files from Onfido's CDN. +#### NPM package version pinning -From SDK 12.3.1 onwards, the version number you subscribe to can vary, depending on your needs: +In order to facilitate integration and A/B tests, the CDN-powered NPM package will also **optionally** support the ability to specify a version (major, minor or patch) of the Onfido Web SDK library. -- subscribing to a specific patch release (e.g. v12.3.1) will fix the library files to that SDK release -- subscribing to a minor level release (e.g. v12.3) means Onfido will update to the latest available patch release -- subscribing to a major release (e.g. v12) means Onfido will update to the latest available patch and minor release +More details are provided in the [SDK version pinning](#version-pinning) section below. -```html - - - -``` +#### TypeScript + +From version `6.5.0` onwards, TypeScript is officially supported, providing types for: -For versions prior to 12.3.1, specifying a precise release only, see our previous [documentation](https://github.com/onfido/onfido-sdk-ui/blob/12.3.0/README.md#43-cdn). +- `init()` method +- `options` argument (`SdkOptions`) and return object (`SdkHandle`) of `init()` method +- Arguments (`SdkResponse` and `SdkError`) for `onComplete()` and `onError()` callbacks +- `steps` option (`StepTypes` and `StepConfig`) +- `language` option (`SupportedLanguages` and `LocaleConfig`) +- `region` option (`ServerRegions`) -#### 4.2 HTML Script Tag Include +### Loading the Onfido flow -You can include the library as a regular script tag on your page: +To load the Onfido flow, add an empty HTML element for the modal interface to mount itself on: ```html - +
``` -And the CSS styles: +With the configuration in an accompanying script: -```html - +```javascript +Onfido.init({ + token: '', + containerId: 'onfido-mount', + //containerEl:
, an ALTERNATIVE to `containerId` + onComplete: function (data) { + console.log('everything is complete') + }, + workflowRunId: '', +}) ``` -You can see a [simple example using script tags](https://jsfiddle.net/gh/get/library/pure/onfido/onfido-sdk-ui/tree/master/demo/fiddle/). + -#### 4.3 NPM style import +> You can see an example integration of the Onfido Web SDK in our [sample app](https://github.com/onfido/onfido-sdk-web-sample-app/). -Alternatively, you can import the library as a module into your own JS build system (tested with Webpack): + -```shell -$ npm install --save onfido-sdk-ui -``` +You may also _optionally_ specify a different container or identifier to load the Onfido flow: -```javascript -// ES6 module import -import { init } from 'onfido-sdk-ui' +- **`containerId {String}` - optional** -// commonjs style require -var Onfido = require('onfido-sdk-ui') -``` + ID value of the container element that the UI will mount to. The element itself needs to be an empty element. The default ID is `onfido-mount`. If your integration needs to pass the container element itself, use `containerEl` as described next. -The CSS style will be included inline with the JS code when the library is imported. +- **`containerEl {Element}` - optional** -⚠️ Note: The library is **Browser only**, it does not support the **Node Context**. + Container element that the UI will mount to. This needs to be an empty element. This can be used as an alternative to passing in the container ID string previously described for `containerId`. Note that if `containerEl` is provided, then `containerId` will be ignored. -You can see an [example app using npm style import](https://github.com/onfido/onfido-sdk-web-sample-app/). +### Integrating in a webview -#### 4.4 Split bundle +While webviews provide a lightweight integration and simplify cross-platform development, they have limitations in terms of accessing device features such as the camera, microphone, and local files as they rely on the webview engines provided by the operating system. As such webviews don’t offer the same level of performance and user experience as the functionality of the Onfido mobile SDKs in native apps. -To decrease the size of your production bundle, you can use the split version of the library: +Where possible, Onfido recommends using its native mobile SDKs for optimal performance. -```javascript -import { init } from 'onfido-sdk-ui/split' -import 'onfido-sdk-ui/split/css' -``` +Please refer to this [guide](https://developers.onfido.com/guide/sdk-webview-guide) for more details about how to integrate the Onfido Web SDK in a webview. -If you are using TypeScript, you have to enable `moduleResolution` to `Node16 | NodeNext | Bundler`. If it is not possible in your case, you need to add a `@ts-ignore` comment above the import. +## Initializing the SDK -⚠️ Note: The main bundle will be in included in your build, but the other bundles will be loaded from Onfido's CDN. +The Web SDK has multiple initialization and customization options that provide flexibility to your integration, while remaining easy to integrate. -### 5. Add basic HTML markup +**Note** that from version 14, it will no longer be possible to change initialization options at runtime as was previously allowed with the `setOption()` function. -Add an empty HTML element at the bottom of your page for the modal interface to mount itself on. +### Defining a workflow -```html -
-``` +Onfido Studio is the platform used to create highly reusable identity verification workflows for use with the Onfido SDKs. For an introduction to working with workflows, please refer to our [Getting Started guide](https://developers.onfido.com/guide/general-introduction), or the Onfido Studio [product guide](https://developers.onfido.com/guide/onfido-studio-product). -### 6. Initialize the SDK +SDK sessions are orchestrated by a session-specific `workflow_run_id`, itself derived from a `workflow_id`, the unique identifier of a given workflow. -You can now initialize the SDK, using the SDK token. +For details on how to generate a `workflow_run_id`, please refer to the `POST /workflow_runs/` endpoint definition in the Onfido [API reference](https://documentation.onfido.com/#workflow-runs). -```javascript -Onfido.init({ - token: '', - containerId: 'onfido-mount', - containerEl:
, //ALTERNATIVE to `containerId` - onComplete: function (data) { - console.log('everything is complete') - }, - steps: ['welcome', 'poa', 'document', 'face', 'complete'], -}) -``` + -| Parameter | Format | Notes | -| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `token` | string | **required**
Your Web SDK token | -| `containerId` | string | **optional**
A string containing the ID of the container element that the UI will mount to. This must be an empty element. The default is `onfido-mount`.
Alternatively, if your integration requires it, you can pass in the container element instead. Note that if `containerEl` is provided, then `containerId` will be ignored | -| `onComplete` | function | **optional** A [callback function](#handling-callbacks) that executes after the applicant's document and face have both been captured and uploaded successfully | -| `steps` | string or object | List of different steps corresponding to parts of the process the user will be presented with | +> **Note** that in the context of the SDK the `workflow_run_id` property is referred to as `workflowRunId`. -## Handling callbacks + -### `onComplete {Function} optional` +### SDK authentication -Callback that fires when both the document and face have been successfully captured and uploaded. You can then trigger your backend to [create a check](https://documentation.onfido.com/#create-check), using the associated applicant ID. +The SDK is authenticated using SDK tokens. As each SDK token must be specific to a given applicant and session, a new token must be generated each time you initialize the Onfido Web SDK. -Example `onComplete` callback: +- **`token {String}` - required** -```javascript -Onfido.init({ - token: '', - containerId: 'onfido-mount', - onComplete: function (data) { - console.log('everything is complete') - }, -}) -``` + A JWT is required in order to authorize with the Onfido WebSocket endpoint. If the SDK token is missing, an exception will be thrown. -`data` is an object that contains properties of the document and face images captured during the SDK flow. +For details on how to generate SDK tokens, please refer to `POST /sdk_token/` definition in the Onfido [API reference](https://documentation.onfido.com/#generate-sdk-token). -For two-sided documents like `driving_licence` and `national_identity_card`, the object will also contain a `document_back` property representing the reverse side. + -For the face step an object is returned with the `variant` used for the face capture,`'standard' | 'video' | 'motion'`. This informs whether to specify a `facial_similarity_photo`, `facial_similarity_video`, or `facial_similarity_motion` report during check creation. +> SDK tokens have a fixed expiry of 90 minutes. -```javascript - { - "document_front": { - "id": "", - "type": "passport", - "side": "front" - }, - "face": { - "id": "", - "variant": "standard" - }, - "document_back": { - "id": "", - "type": "driving_licence", - "side": "back" - }, - "poa": { - "id": "" - "type": "utility_bill" - } - } -``` + -### `onError {Function} optional` +**Note**: You must never use API tokens in the frontend of your application as malicious users could discover them in your source code. You should only use them on your server. -Callback that fires when an error occurs. The callback returns the following error types: +### Version pinning -- `exception` - This will be returned for the following errors: +Based on the same major version, the minor and patch versions of the library can be specified in the `Onfido.init()` object. - - timeout and server errors - - authorization - - invalid token - - missing data in `onComplete` callback +- **`version {String}` - optional** - This data can be used for debugging purposes. + The specific version of the Onfido Web SDK that should be loaded as part of this initialization. A full version (e.g. `v14.12.1`) or just a minor version (e.g. `v14.13`) can be specified. When a minor version is specified, the latest patch version for that minor release will be loaded. + Example: `version: "14.12.1"` + +**Note**: This parameter is ineffective when the library is impoart as a full bundle from NPM (as opposed to the default CDN-powered NPM package). + +### Styling customization + +The Onfido Web SDK supports customization options to adjust the fonts, the SDK main container, buttons, links, icons, background color and popups. + +To customize the SDK, you can pass the required CSS values to the `customUI` object, in the root of the `Onfido.init()` object. + +- **`customUI {Object}` - optional** + + Object containing optional CSS values for the supported UI customization options. The sample below lists all possible options with some example values. ```javascript { - type: "exception", - message: "The request could not be understood by the server, please check your request is correctly formatted" + "customUI": { + "borderRadiusButton": "56px", + "borderStyleSurfaceModal": "0px", + "fontWeightBody": 400, + "fontSizeBody": "16px", + "fontSizeSubtitle": "16px", + "fontSizeTitle": "40px", + "colorBackgroundSurfaceModal": "transparent", + "colorBackgroundIcon": "transparent", + "colorBorderLinkUnderline": "transparent", + "colorBackgroundLinkActive": "transparent", + "colorBackgroundLinkHover": "transparent", + "colorBackgroundDocTypeButton": "transparent", + "colorContentBody": "rgb(255,255,255)", + "colorContentTitle": "rgb(255,255,255)", + "colorContentSubtitle": "rgb(255,255,255)", + + "colorContentButtonPrimaryText": "rgb(10,11,13)", + "colorBackgroundButtonPrimary": "rgb(55, 115, 245)", + "colorBackgroundButtonPrimaryHover": "rgb(55, 115, 245)", + "colorBackgroundButtonPrimaryActive": "rgb(55, 115, 245)", + + "colorContentButtonSecondaryText": "rgb(255,255,255)", + "colorBackgroundButtonSecondary": "rgb(50,53,61)", + "colorBackgroundButtonSecondaryHover": "rgb(30,32,37)", + "colorBackgroundButtonSecondaryActive": "rgb(30,32,37)", + "colorContentLinkTextHover": "rgb(55, 115, 245)", + "colorBorderDocTypeButton": "rgb(20, 21, 25)", + "colorBackgroundDocTypeButtonHover": "rgb(30,32,37)", + "colorBackgroundDocTypeButtonActive": "rgb(30,32,37)", + "colorContentDocTypeButton": "rgb(255,255,255)", + "colorIcon": "rgb(55, 115, 245)", + "colorContentInfoPill": "rgb(10,11,13)", + "colorBackgroundInfoPill": "rgb(55, 115, 245)", + "colorBackgroundSelector": "red", + "colorInputOutline": "rgb(87, 139, 250)", + "colorContentButtonTertiaryText": "rgb(255,255,255)", + "colorContentInput": "blue", + "colorBackgroundInput": "green", + "colorBorderInput": "yellow" + } } + ``` -- `expired_token` - This error will be returned when a token has expired. This error type can be used to provide a new token at runtime. + + +> For use in a webview on a mobile device, it is recommended to set up the SDK to use the full screen of the device. Otherwise, there may not be enough room to display all critical elements of the SDK. + + + +**Note** that from version 14, the Onfido SDK options to load the screens in a modal have been deprecated. If you wish to load the Onfido screens in a modal you will have to define it as part of your own integration. + +### Co-branding + +The Onfido SDK allows for two co-branding options that affect the display of the Onfido logo at the bottom of the Onfido screens. + +For further customization, please contact your Onfido Solution Engineer or Customer Success Manager. + +#### Text co-branding + +- **`cobrand {Object}` - optional** + + The most effective way to add your brand to the footer watermark, is by use of the `cobrand` property under `enterpriseFeatures`. This property takes a `text` parameter. + + ![Example of text cobranding](../demo/text_co_brand.png) ```javascript -{ - type: "expired_token", - message: "The token has expired, please request a new one" -} +Onfido.init({ + ... + enterpriseFeatures: { + cobrand: { + text: "Onboarding, Inc." + } + }, +}) ``` -### `onUserExit {Function} optional` +#### Logo co-branding -Callback that fires when the user abandons the flow without completing it. +- **`logoCobrand {Object}` - optional** -The callback returns a string with the reason for leaving. For example, `'USER_CONSENT_DENIED'` is returned when a user exits the flow because they declined the consent prompt. + As an alternative to `cobrand`, you may specify a set of images to be defined in the `logoCobrand` property under `enterpriseFeatures`. You must provide the path to an image for use in 'dark' mode and a separate image for 'light' mode. Both images must have a resolution of 144x32. ```javascript Onfido.init({ - token: '', - containerId: 'onfido-mount', - onUserExit: function (userExitCode) { - console.log(userExitCode) + ... + enterpriseFeatures: { + logoCobrand: { + darkLogoSrc: "https://YourLogoImageUrlOrFilePath", + lightLogoSrc: "https://YourLogoImageUrlOrFilePath", + } }, }) ``` -### `onModalRequestClose {Function} optional` - -Callback that fires when the user attempts to close the modal. +### Language selection -You can then decide to close the modal or keep it open by changing the property `isModalOpen`. +The Onfido SDK supports and maintains translations for over 40 languages in its SDKs. -## Removing the SDK +- **`language {String || Object}` - optional** -If you have embedded the SDK inside a single page app, you can call the `safeTearDown` function to remove the SDK completely from the current webpage. It will reset the state and you can safely re-initialize the SDK inside the same webpage later on. + You can customize the language displayed on the SDK by passing a string or object. + If `language` is not present at the root of the `Onfido.init()` call, the SDK will use the browser's language setting. If the browser's language is not supported by Onfido, the SDK will default to English (`en_US`). ```javascript -onfidoOut = Onfido.init({...}) -... -await onfidoOut.safeTearDown() +language: 'pt_BR' | 'es' ``` -⚠️ **Warning**: The `safeTearDown` method is a Promise. If you plan on mounting the SDK a second (or nth time), please await the promise first. +For the list of languages supported by Onfido, please refer to our [SDK customization guide](https://developers.onfido.com/guide/sdk-customization#language-customization). + +### Language customization + +In addition to selecting default languages for the SDK session, the SDK can also be displayed in a custom language for locales that Onfido does not currently support or for the addition of custom text, specific to your integration needs. This can be achieved by setting the following options in the `language` object: + +| Option | Description | Notes | +| --------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `locale` | **required**
A locale tag. | This is required when providing phrases for an unsupported language. You can also use this to partially customize the strings of a supported language (e.g. Spanish), by passing a supported language locale tag (e.g. `es_ES`). For missing keys, the values will be displayed in the language specified within the locale tag if supported, otherwise they will be displayed in English. The locale tag is also used to override the language of the SMS body for the cross-device feature. This feature is owned by Onfido and currently only supports English, Spanish, French and German. | +| `phrases` | **required**
An object containing the keys you want to override and the new values. | Keys can be passed as a nested object or as a string using the dot notation for nested values. Refer to the next section for instructions on how to find the right keys. | +| `mobilePhrases` | **optional**
An object containing the keys you want to override and the new values. | The values specified within this object are only visible on mobile devices. **Note**: support for standalone `mobilePhrases` key will be deprecated soon. Consider nesting it inside `phrases` if applicable. | ```javascript -onfidoOut = Onfido.init({...}) -await onfidoOut.safeTearDown() -onfidoOut2 = Onfido.init({...}) +language: { + locale: 'en_US', + phrases: { + 'capture.driving_licence.instructions': 'This custom string will appear by default' + }, + mobilePhrases: { + 'capture.driving_licence.instructions': 'This custom string will only appear on mobile' + } +} ``` -## Initialization options +#### Identifying text keys in the Onfido screens -- **`token {String} required`** +In order to identify text that can be overridden and locate their exact keys, you should use a browser inspector and indentify `div` blocks with the attribute name `data-i18n-token`. - A JWT is required in order to authorize with our WebSocket endpoint. If one isn’t present, an exception will be thrown. +![Example of how to use an html inspector to find a text key](../demo/inspector.png) -- **`useModal {Boolean} optional`** +### Cross-device navigation - Turns the SDK into a modal, which fades the background and puts the SDK into a contained box. The default value is `false`. +The Web SDK offers a cross-device flow where desktop users are directed to continue on their mobile device browser to complete the capture process. This provides a vastly improved image quality versus a typical desktop webcam and increases the likelihood of successful live capture. - ```javascript - +![Force cross-device flow](../demo/cross-device.png) - - - -
- - ``` +Three options are offered to the user to resume the flow on a mobile device browser: -- **`isModalOpen {Boolean} optional`** +- QR code that can be scanned with a camera app (default) +- 'Copy Link' feature that can be copy/pasted into a web browser +- One-time SMS link that can be sent diretly to the user's mobile phone - Defines whether the modal is open or closed, if `useModal` is set to `true`. The default value is `false`. +Regardless of the cross-device method, the secure URL is unique to this session. - To change the state of the modal after calling `init()` you need to use `setOptions()`. +At the end of the capture process, users will be instructed to revert back to their desktop to complete the SDK flow. -- **`shouldCloseOnOverlayClick {Boolean} optional`** +**Note** that during a capture sequence on a desktop device, if a camera cannot be detected, the user is forward by default to the cross-device flow in order to attempt the capture on another device. - If `useModal` is set to `true`, by default the user can close the SDK by clicking on the close button or on the background overlay. You can disable the user's ability to close the SDK by clicking the background overlay through setting `shouldCloseOnOverlayClick` to `false`. The default value is `true`. +#### Enforcing cross-device navigation -- **`autoFocusOnInitialScreenTitle {Boolean} optional`** +In order to optimize the capture quality, it is recommended to enforce the cross-device flow. The option is available in Onfido Studio, configurable in the [workflow builder](https://developers.onfido.com/guide/onfido-studio-product#document-capture-task). - Sets the SDK to auto focus on the initial screen's title. By default the SDK will auto focus on every screen's title. When disabled, auto focus will not be applied for the initial screen's title. The SDK will still auto focus to all subsequent screens' titles as the user goes through the steps. The default value is `true`. +Cross-device can also be enforced at run-time using the following initialization option: -- **`containerId {String} optional`** +- **`crossDevicePolicy {String}` - optional** - A string of the ID of the container element that the UI will mount to. This needs to be an empty element. The default ID is `onfido-mount`. If your integration needs to pass the container element itself, use `containerEl` as described next. + By default, the cross-device flow is not enforced but shown to the user alongside a button to upload a document instead. You can force the user to capture a document or face on a mobile device by either: -- **`containerEl {Element} optional`** +- setting the option globally (across all workflow runs) in the [workflow builder](https://developers.onfido.com/guide/onfido-studio-product#document-capture-task) - The container element that the UI will mount to. This needs to be an empty element. This can be used as an alternative to passing in the container ID string previously described for `containerId`. Note that if `containerEl` is provided, then `containerId` will be ignored. +- setting the `crossDevicePolicy` initialization option at runtime to either `force` or `disable` to completely remove the option -- **`smsNumberCountryCode {String} optional`** + ```javascript + crossDevicePolicy: 'force' + ``` + +#### Customizing the cross-device experience + +In addition to forcing the cross-device flow, the cross-device experience can be further customized during the SDK initialization with the following options: + +- **`_crossDeviceLinkMethods {List}` - optional** + + You can specify which of the three cross-device link options are presented to the user by adding any of `qr_code`, `copy_link` and/or `sms` to the `_crossDeviceLinkMethods` using a `,` as a separator. The first element of the list will be the **default** option shown to the user. Note the underscore at the start of the string. + + ```javascript + _crossDeviceLinkMethods: ['qr_code', 'copy_link', 'sms'] + ``` + +- **`smsNumberCountryCode {String}` - optional** - You can change the default country for the SMS number input by passing the `smsNumberCountryCode` option when the SDK is initialized. The value should be a string containing a 2-character ISO Country code. If empty, the SMS number country code will default to `GB`. + You can change the default country for the SMS number input by passing the `smsNumberCountryCode` option at the root of the `Onfido.init()` call when the SDK is initialized. The value should be a string containing a 2-character ISO country code. If empty, the SMS number country code will default to `GB`. ```javascript smsNumberCountryCode: 'US' ``` -- **`userDetails {Object} optional`** +- **`userDetails {Object}` - optional** The following user details can be specified ahead of time, so that the user doesn't need to provide the information themselves: - - `smsNumber` (optional) : The user's mobile number, which can be used for sending SMS messages to the user, for example, when a user requests to use their mobile devices to take photos. The value should be a string containing the mobile number with a country code. + - `smsNumber` (optional) : The user's mobile number can be added to the optional `userDetails` object at the root of the `Onfido.init()` call. The value should be a string containing the mobile number with a country code. ```javascript userDetails: { @@ -427,199 +451,252 @@ onfidoOut2 = Onfido.init({...}) } ``` -- **`steps {List} optional`** +- **`crossDeviceClientIntroProductLogoSrc {String}` - optional** - The list of different steps to be shown in the SDK flow and their custom options. Each step can either be specified as a string (when no customization is required) or an object (when customization is required). + You can customize the icon by adding your company or product logo to be displayed instead of the default SDK icon image with this option. The image referenced in the path should be no more than 144px in both height and width. ```javascript - steps: [ - { - type: 'welcome', - options: { - title: 'Open your new bank account', - }, - }, - 'document', - 'face', - ] + Onfido.init({ + ... + crossDeviceClientIntroProductLogoSrc: "path://to/logo/image/file", + }); ``` - See [flow customization](#flow-customization) for details of the custom options for each step. +**Note** that from version 14, the `crossDeviceClientIntroProductName` option used in previous versions to modify just the customer name in the cross-device intro screen has been deprecated. Instead, you should use the standard [language customization](#language-customization) process to override the subtitle of the screen. -## Customizing the SDK +## Completing a session -The Web SDK has multiple customizable features that provide flexibility, while also being easy to integrate. You can also read our [SDK customization guide](https://developers.onfido.com/guide/sdk-customization). +### Handling callbacks -### UI customization +When the Onfido SDK session will conclude, one of two callback functions may be triggered: -- **`customUI {Object} optional`** +- `onComplete`: the session was successful with at least 1 document captured +- `onError`: the session terminated unexpectedly - Please refer to the [SDK UI customization documentation](UI_CUSTOMIZATION.md) for details of the supported UI customization options that can be set in this property. +For advanced callbacks used for user analytics and returning submitted media, please refer to the [Advanced Callbacks ](#advanced-callbacks) section of this document. -### Language Localization +#### `onComplete {Function}` - optional -- **`language {String || Object} optional`** +Callback that fires when the flow has successfully been executed with at least 1 document capture. - You can customize the language displayed on the SDK by passing a string or object. - If `language` is not present we will use the browser's language setting. If the browser's language is not supported, we will default to English (`en_US`). - - #### Supported languages - - The SDK supports and maintains the following languages. These can be implemented directly inside the SDK by passing the `language` option as a string containing the supported language tag. - - | Language | Locale Tag | Direction | - | ------------------------ | ---------- | --------- | - | Arabic | "ar" | rtl | - | Armenian | "hy" | | - | Bulgarian | "bg" | | - | Chinese (Simplified) | "zh_CN" | | - | Chinese (Traditional) | "zh_TW" | | - | Croatian | "hr" | | - | Czech | "cs" | | - | Danish | "da" | | - | Dutch | "nl" | | - | English (United Kingdom) | "en_GB" | | - | English (United States) | "en_US" | | - | Estonian | "et" | | - | Finnish | "fi" | | - | French | "fr" | | - | French (Canadian) | "fr_CA" | | - | German | "de" | | - | Greek | "el" | | - | Hebrew | "he" | rtl | - | Hindi | "hi" | | - | Hungarian | "hu" | | - | Indonesian | "id" | | - | Italian | "it" | | - | Japanese | "ja" | | - | Korean | "ko" | | - | Latvian | "lv" | | - | Lithuanian | "lt" | | - | Malay | "ms" | | - | Norwegian | "no" | | - | Persian | "fa" | rtl | - | Polish | "pl" | | - | Portuguese | "pt" | | - | Portuguese (Brazil) | "pt_BR" | | - | Romanian | "ro" | | - | Russian | "ru" | | - | Serbian | "sr" | | - | Slovak | "sk" | | - | Slovenian | "sl" | | - | Spanish | "es" | | - | Spanish (Latin America) | "es_419" | | - | Swedish | "sv" | | - | Thai | "th" | | - | Turkish | "tr" | | - | Ukrainian | "uk" | | - | Vietnamese | "vi" | | - - Example: +```javascript +Onfido.init({ + token: "", + ... + onComplete: function (data) { + console.log("everything is complete"); + }, +}); +``` + +The `data` object contains properties of the documents and face images uploaded by the user during the SDK session. The properties contain a unique identifier that can be used to retrieve the full document or face capture using the corresponding `document`, `live_photos` (for 'standard' selfies) or `live_videos` (for 'video' or 'motion' captures) endpoints defined in the [API reference](https://documentation.onfido.com/#retrieve-document). + +```json +{ + "document_front": { + "id": "", + "type": "driving_licence", + "side": "front" + }, + "document_back": { + "id": "", + "type": "driving_licence", + "side": "back" + }, + "face": { + "id": "", + "variant": "standard" + }, + "poa": { + "id": "", + "type": "utility_bill" + } +} +``` + +For two-sided documents such as `driving_licence` and `national_identity_card`, the object will also contain a `document_back` property representing the reverse side. + +For the face step, an object is returned with the `variant` used for the face capture,`'standard' | 'video' | 'motion'`. + +### `onError {Function}` - optional + +Callback that fires when an error occurs. The callback returns the following error types: + +- `exception` + This will be returned for the following errors: + + - timeout and server errors + - authorization + - invalid token + - missing data in `onComplete` callback + + This data can be used for debugging purposes. ```javascript - language: 'pt_BR' | 'es' + { + type: "exception", + message: "The request could not be understood by the server, please check your request is correctly formatted" + } ``` - #### Custom languages +- `expired_token` + This error will be returned when a token has expired. This error type can be used to provide a new token at runtime. + + ```javascript + { + type: "expired_token", + message: "The token has expired, please request a new one" + } + ``` - The SDK can also be displayed in a custom language for locales that Onfido does not currently support. To implement this, pass an object containing the following keys: +- `permissions_unavailable` - | Key | Description | Notes | - | --------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `locale` | **required**
A locale tag. | This is required when providing phrases for an unsupported language. You can also use this to partially customize the strings of a supported language (e.g. Spanish), by passing a supported language locale tag (e.g. `es_ES`). For missing keys, the values will be displayed in the language specified within the locale tag if supported, otherwise they will be displayed in English. The locale tag is also used to override the language of the SMS body for the cross device feature. This feature is owned by Onfido and is currently only supports English, Spanish, French and German. | - | `direction` | **optional**
Direction of reading | Set the direction of reading, either left-to-right or right-to-left. Values: `ltr` or `rtl`. Default: `ltr` | - | `phrases` | **required**
An object containing the keys you want to override and the new values. | The keys can be found in [`src/locales/en_US/en_US.json`](src/locales/en_US/en_US.json). They can be passed as a nested object or as a string using the dot notation for nested values. See the examples below. | - | `mobilePhrases` | **optional**
An object containing the keys you want to override and the new values. | The values specified within this object are only visible on mobile devices. Please refer to the `mobilePhrases` property in [`src/locales/en_US/en_US.json`](src/locales/en_US/en_US.json). **Note**: support for standalone `mobilePhrases` key will be deprecated soon. Consider nesting it inside `phrases` if applicable. | + `permissions_unavailable` will be returned if the SDK was unable to access or request the necessary permissions. This may occur when the Web SDK is loaded within a webview or other custom browsers. ```javascript - language: { - locale: 'en_US', - direction: 'ltr', - phrases: { welcome: { title: 'My custom title' } }, - mobilePhrases: { - 'capture.driving_licence.instructions': 'This string will only appear on mobile' - } + { + type: "permissions_unavailable", + message: "Unable to retrieve or access required user permissions" } ``` -### Flow customization +- `user_consent_denied` -#### welcome + `user_consent_denied` will be returned if the user exits the flow because they declined the consent prompt. -This step is the introduction screen of the SDK. It displays a summary of the capture steps the user will pass through. These steps can be specified to match the flow required. This is an optional screen. + ```javascript + { + type: "user_consent_denied", + message: "Unable to proceed without user consent" + } + ``` -The custom options are: +**Note** that from version 14 onwards, the optional `onUserExit` callback, that was used to return the `USER_CONSENT_DENIED` message, has been deprecated and merged with the `onError` callback, as detailed above. -- `title` (string) -- `descriptions` ([string]) -- `nextButton` (string) +### SDK tear-down -#### document +If you have embedded the SDK inside a single page app, you can call the `safeTearDown` function to remove the SDK completely from the current webpage. It will reset the state and you can safely re-initialize the SDK inside the same webpage later on. -In the Document Capture step, an end user can select the issuing country and document type before capture. +```javascript +onfidoOut = Onfido.init({...}) +... +await onfidoOut.safeTearDown() +``` -This information is used to optimize the capture experience, as well as inform the end user about which documents they are allowed to use. +⚠️ **Warning**: The `safeTearDown` method is a Promise. If you plan on mounting the SDK a second (or nth) time, please await the promise first. -This selection screen is optional, and will be automatically hidden where the end user is not required to indicate which document will be captured. +```javascript +onfidoOut = Onfido.init({...}) +await onfidoOut.safeTearDown() +onfidoOut2 = Onfido.init({...}) +``` -By default, when the selection screen is shown, the country selection will be empty. +### Generating verification reports -![Choose documents type](demo/choose-document.png) +While the SDK is responsible for capturing and uploading the user's media and data, identity verification reports themselves are generated based on workflows created using [Onfido Studio](https://developers.onfido.com/guide/onfido-studio-product). -_The above images are for web SDK versions 8.3.0+. For previous designs, see previous SDK reference guides_ +For a step-by-step walkthrough of creating an identity verification using Onfido Studio and our SDKs, please refer to our [Quick Start Guide](https://developers.onfido.com/guide/quick-start-guide). -You can specify allowed issuing countries and document types for the document capture step in one of three ways: +If your application initializes the Onfido Web SDK using the options defined in the [Advanced customization](#advanced-flow-customization) section of this document, you may [create checks](https://documentation.onfido.com/#create-check) and [retrieve report results](https://documentation.onfido.com/#retrieve-report) manually using the Onfido API. +You may also configure [webhooks](https://documentation.onfido.com/#webhooks) to be notified asynchronously when the report results have been generated. -- If you are using Onfido Studio, this is configured within a Document Capture task, documented in the [Studio Product Guide](https://developers.onfido.com/guide/onfido-studio-product#document-capture-task) -- Otherwise, for Onfido Classic you can set this globally in your Dashboard (recommended), or hard code it into your SDK integration. Both of these options are documented below +## Advanced flow customization -##### Country and document type selection by Dashboard +This section on 'Advanced customization' refers to the process of initializing the Onfido Web SDK without the use of Onfido Studio. This process requires a manual definition of the verification steps and their configuration. +The `steps` parameter is mutually exclusive with `workflowRunId`. The other parameters under `Onfido.init()` remain the same. -Configuring the issuing country and document type selection step using your Dashboard is the recommended method of customization (available from [Web SDK](https://documentation.onfido.com/sdk/web/) version 10.0.0 onwards) as this configuration is also applied to your Document Reports. Any document that has been uploaded by an end user against your guidance will result in a Document Report sub-result of "rejected" and be flagged as `Image Integrity` > `Supported Document`. +**Note** that this initialization process is **not recommended** as the majority of new features are exclusively released for Studio workflows. -_We will be rolling out Dashboard-based configuration of allowed documents soon. In the meantime, contact [support@onfido.com](mailto:support@onfido.com) or your Customer Support Manager to request access to this feature_. +- **`steps {List}` - optional** -- Open the Accounts tab on your [Dashboard](https://dashboard.onfido.com/), then click Supported Documents -- You will be presented with a list of all available countries and their associated supported documents. Make your selection, then click Save Change + The list of user verification steps, in order of appearance. Each step can either be specified as a string (when no customization is required) or an object (when customization is required). Customization options are described in the following sections. -![The Supported Documents tab in the Dashboard](demo/supported_documents_dashboard.png) +From the possible steps listed below, only `document` is required: -**Please note:** +| Step | Description | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `welcome` | Welcome screen shown to the user with preliminary instructions. [Customization](#welcome-step) options include modification to the text elements and instructions shown to the user. | +| `document` | Set of screens that control the capture via photo or upload of the user's document. Numerous [customization](#document-step) options are available to define the document list presented to the user and the overall capture experience. | +| `face` | Set of screens that control the capture of a selfie, video or motion of the user. The [customization](#face-step) options allow the selection of the capture variant as well as fallback options. | +| `complete` | Screen shown to the user at the end of the flow. [Customization](#complete-step) options include modifications to the text elements shown to the user. | -- Hard coding any document type and issuing country configuration in your SDK integration will fully override the Dashboard-based settings -- Currently, only passport, national ID card, driving licence and residence permit are visible for document selection by the end user in the SDK. If you nominate other document types in your Dashboard (visa, for example), these will not be displayed in the user interface -- If you need to add other document types to the document selection screen, you can mitigate this limitation in the near-term, using the Custom Document feature -- If for any reason the configuration fails or is not enabled, the SDK will fallback to display the selection screen for the complete list of documents supported within the selection screens +```javascript +Onfido.init({ + token: "", + ... + steps: [ + { + type: "welcome", + options: { + title: "Open your new bank account", + }, + }, + "document", + "face", + ]; +}); +``` + +#### `welcome` step -##### Country and document type selection - SDK integration code +This step is the introduction screen of the SDK. It introduces the process and prepares the user for the steps they will need to complete. These steps can be specified to match the flow required. -If you want to use your own custom document selection UI instead of displaying the Onfido document selection screen, you will need to specify the document details during SDK initialization. +While this screen is **optional**, we only recommend its removal if you already have your own identity verification welcome screen in place. -The document selection screen will be skipped automatically when the single document type is specified. +The custom options are: -The SDK will accept the following: +- `title` (string) +- `descriptions` ([string]) +- `nextButton` (string) -- The **Document Type** is required. This controls fundamental SDK document capture behaviour -- The **Country** is optional, but recommended. This enables any optimizations the SDK may have for this specific document issued by this country -- The **Document Format** is optional, and only accepted for French driving licence, Italian national identity card and South African national identity card This defaults to Card, representing modern forms of these documents. If the end user indicates that they have an older, paper version of one of these documents, use Folded to ensure an optimized capture experience +#### `document` step -The custom options are: +The Document Capture step is typically organised in three parts: + +- The issuing country and document type selection +- The camera capture +- The document review and upload + +**Note** that the `document` step is mandatory. + +The customization options available all relate to the country and document type selection screen. +By default, the selection screen is shown with the country selection being empty. + +![Choose documents type](../demo/choose-document.png) +_The above images are for web SDK versions 8.3.0+_ + +Depending on the customization options defined in this step or the 'allowed countries' defined in your [Dashboard](https://dashboard.onfido.com/), either the country or document type selection screens might not be shown: + +- The country selection screen will not be shown if only 1 country is selected or if only passports are allowed +- The document selection screen will not be shown if only 1 document type is specified + +You can specify allowed issuing countries and document types for the document capture step in one of three ways: -- `documentTypes` (object) +- Onfido Studio: If you are using Onfido Studio, this is configured within the Document Capture task, as documented in the [Studio Product Guide](https://developers.onfido.com/guide/onfido-studio-product#document-capture-task) - The list of document types visible to the user can be filtered by using the `documentTypes` option. When `documentTypes` is not defined, the default value for each document type is `true`. When `documentTypes` is defined, it will override the default values. Absent types are considered `false`. +- Dashboard : Otherwise, the recommended approach is to apply this configuration globally in the [Dashboard](https://dashboard.onfido.com/) under Accounts \ Supported Documents. This option also ensures that the list is enforced as part of the Document Report validation. Any document that has been uploaded by an end user against your guidance will result in a Document Report sub-result of "rejected" and be flagged as `Image Integrity` > `Supported Document`. -- `country` (string) + ![The Supported Documents tab in Dashboard](../demo/supported_documents_dashboard.png) - Document country can be specified per document type. The `country` configuration for a document type allows you to specify the issuing country of the document as a string containing a 3-letter ISO 3166-1 alpha-3 country code. +- Run-time: For run-time configuration, the following `options` can be defined under the `document` step: - If `documentTypes` only includes one document type with a country value, users will not see the document selection screen and instead will be taken directly to the capture screen. + - **`documentTypes {Object}` - required** - ⚠️ **Note**: the `null` value is deprecated and has no effect. + The list of document types visible to the user can be filtered by using the `documentTypes` option. When `documentTypes` is not defined, the default value for each document type is `true`. When `documentTypes` is defined, it will override the default values. Absent types are considered `false`. - ⚠️ **Note**: Passports have the same format worldwide so the SDK will not show the country selection screen even if they are not restricted by country (e.g. passport: true). + - **`country {String}` - optional** -For example, if you want to allow only Spanish (ESP) driving licences, and national identity cards and residence permits for all countries: + Document country can be specified per document type. The `country` configuration for a document type allows you to specify the issuing country of the document as a string containing a 3-letter ISO 3166-1 alpha-3 country code. + + If `documentTypes` only includes one document type with a country value, users will not see the document selection screen and instead will be taken directly to the capture screen. + + ⚠️ **Note**: the `null` value is deprecated and has no effect. + + ⚠️ **Note**: Passports have the same format worldwide so the SDK will not show the country selection screen even if they are not restricted by country (e.g. passport: true). + + - **`hideCountrySelection {Boolean}` - optional** + + It is possible to completely remove the country selection screen, showing instead the list of all possible document types directly to the user by setting `hideCountrySelection` to `true`. This is **not recommended** as it will prevent document-specific optimization of the flow and detailed analytics. ```json { @@ -642,57 +719,24 @@ For example, if you want to allow only Spanish (ESP) driving licences, and natio } ``` -In the Web SDK, it is also possible to remove the country selection entirely from the document selection screen. Set the hideCountrySelection option to true to show all supported document types in a single list with no country selection. Note that, without capturing the country information, the SDK is unable to apply optimized capture experiences for specific documents, and we are not able to perform fine-grained analytics based on country selection. - -See more details in the Technical Reference [here](https://documentation.onfido.com/sdk/web/). - -**Note**: You may still wish to configure the Dashboard-based approach to ensure that the Document Report also rejects any document that has been uploaded by an end user against your guidance. - -##### Cross-device flow - -The Web SDK offers a cross-device flow where desktop users are directed to continue on their mobile device browser to complete the capture process, providing vastly improved image quality versus a typical desktop webcam and an increased likelihood of live capture. - -The user is offered a QR code to scan with their camera app, which then resumes the flow on their mobile device browser. For users that cannot scan a QR code, a Copy Link feature and Send Link with SMS feature are also available. Regardless of the cross-device method, the secure URL is unique to this session. - -When a user switches to the SDK's cross-device flow, they will see an [introductory screen](https://developers.onfido.com/guide/sdk-customization#cross-device---mobile-client-introductory-screen) when the SDK client loads on their mobile browser. At the end of the capture process, users will be redirected back to their desktop to complete the SDK flow. - -It is recommended to enforce the cross-device flow. The option is available in Onfido Studio, configurable in the [workflow builder](https://developers.onfido.com/guide/onfido-studio-product#document-capture-task). +_In the example above only Spanish (ESP) driving licences, and national identity cards and residence permits for all countries will be shown_ -In a Classic integration, the cross-device flow is configured by setting `forceCrossDevice` to true: - -```javascript -options: { - forceCrossDevice: true -} -``` - -- When configured, `forceCrossDevice` makes the cross-device flow mandatory for all users who will be required to complete the capture process on a mobile device browser -- The `forceCrossDevice` functionality can be configured for both the Document capture and Proof of Address verification steps -- `forceCrossDevice` cannot be configured for Face captures - -![Force cross-device flow](demo/cross-device.png) - -When a user switches to the SDK's cross-device flow, they will see an introductory screen when the SDK client loads on their mobile browser. This screen notifies the user that this is part of a flow initiated on a desktop browser when they open the cross-device link on their mobile browser. - -The following optional customizations are available for the introductory screen: +**Please note:** -- Specify company or product name +- Hard coding any document type and issuing country configuration in your SDK integration will fully override the Dashboard-based settings +- Currently, only passport, national ID card, driving licence and residence permit are visible for document selection by the end user in the SDK. If you nominate other document types in your Dashboard (visa, for example), these will not be displayed in the user interface +- If you need to add other document types to the document selection screen, you can mitigate this limitation in the near-term, using the [Custom Document](#custom-documents) feature +- If for any reason the configuration fails or is not enabled, the SDK will fallback to displaying the selection screen for the complete list of documents supported within the selection screens - - `crossDeviceClientIntroProductName` - - You can customize the text by adding your company or product name to the subtitle - - We recommend that you set this so that the user can identify the purpose of the flow when they open the cross-device link. This is also an opportunity to include your branding in the SDK flow +##### Custom Documents -- Display company or product logo - - `crossDeviceClientIntroProductLogoSrc` - - You can customize the icon by adding your company or product logo to be displayed instead of the default SDK icon image - - We recommend that you set this so that the user can identify the purpose of the flow when they open the cross-device link. This is also an opportunity to include your branding in the SDK flow - - The image used should be no more than 144px in both height and width +In case you require to capture a document that is not supported by Onfido or a supported document with a different name or scope (e.g. capturing the back of a two-sided document, even if it is not required for verification purposes), custom documents can be manually defined. -![Cross-device intro screen](demo/cross-device-logo.png) +**Note** that if recognized, Onfido will still attempt to process them based on their detected classification. -- `genericDocumentTypes` (object) +- **`genericDocumentTypes {Object}` - optional** - You can add generic documents that are not supported by Onfido. They will be displayed at the bottom of the built-in document types. + If defined under the `document` step `options`, the custom document will be displayed at the bottom of the standard document types list after any other document types applicable to the other optional country / document type selection options defined in the previous sections. ```javascript genericDocumentTypes: [ @@ -713,7 +757,7 @@ The following optional customizations are available for the introductory screen: ] ``` - In the same way to other document types, you can skip the document selection screen by adding a single `generic_document` object which references one of your generic documents declared in `genericDocumentTypes`. + In the same way to other document types, if you wish to skip the document selection screen, you can add a single `generic_document` object which references the custom document declared in `genericDocumentTypes`. ```javascript documentTypes: { @@ -723,54 +767,73 @@ The following optional customizations are available for the introductory screen: } ``` -#### poa +#### `face` step -This is the Proof of Address capture step. Users will be asked to select the issuing country of their document, the document type, and to provide images of their selected document. They will also have a chance to check the quality of the images before confirming. There are no custom options for this step. +This is the face capture step. Users will be asked to capture their face in the form of a photo, a video, or a motion capture. For photos and videos, they will also have a chance to check its quality before confirming. -#### face +**Note** that if a camera can’t be detected, the user will be forwarded to the cross-device flow in order to attempt to capture on another device. The cross-device flow will be presented to the user, **before** any optional fallback variants are assessed by the Web SDK. -This is the face capture step. Users will be asked to capture their face in the form of a photo, a video, or a motion capture. For photos and videos, they will also have a chance to check its quality before confirming. +##### `face` flow options -The custom options are: +- **`requestedVariant {String}` - optional** -- `requestedVariant` (string - default: `standard`) + A preferred variant can be requested for this step, by passing the option `requestedVariant: 'standard' | 'video' | 'motion'`, with the default version being `standard`. If `requestedVariant` is: - A preferred variant can be requested for this step, by passing the option `requestedVariant: 'standard' | 'video' | 'motion'`. If `requestedVariant` is: + - `standard`: a photo will be captured + - `video`: a video will be captured + - `motion`: a motion capture will be captured - - `standard`: a photo will be captured; - - `video`: a video will be captured; - - `motion`: a motion capture will be captured. + ```json + { + "steps": [ + "welcome", + "document", + { + "type": "face", + "options": { + "requestedVariant": "motion" + } + }, + "complete" + ] + } + ``` - The SDK will try to fulfil this request depending on camera availability, device capabilities, and browser support on the user's device: +- **`showIntro {Boolean}` - optional** - - if a video cannot be taken, the face step can be configured to fallback to the `standard` variant (see `photoCaptureFallback`); - - if Motion is not available, the face step can be configured to fallback to either `video` or `standard` variants (see `motionFallbackVariant`). + The instruction screen shown to the user at the beginning of the `face` capture step can be skipped for the [`video`](https://developers.onfido.com/guide/facial-similarity-reports#video) and [`standard`](https://developers.onfido.com/guide/facial-similarity-reports#standard) variants. By default, the screen is shown (default to `true`). + When disabled for the `standard` variant, the entire intro screen will be removed from the flow. + When disabled for the `video` variant, the example video will be hidden in the intro screen, only showing the text instructions. - If the SDK is initialized with the `requestedVariant` option for the face step, make sure you use the data returned in the [`onComplete` callback](#handling-callbacks) to request the correct report when creating a check. +- **`useMultipleSelfieCapture {Boolean}` - optional** -- `useMultipleSelfieCapture` (boolean - default: `true`) + This option only applies to the variant `standard`. By default the SDK will take additional selfie snapshots to help improve face similarity check accuracy. When disabled, only one selfie photo will be taken. - When enabled, this feature allows the SDK to take additional selfie snapshots to help improve face similarity check accuracy. When disabled, only one selfie photo will be taken. +- **`recordMotionAudio {Boolean}` - optional** -- `photoCaptureFallback` (boolean - default: `true`) + This option only applies to the variant `motion` and enables the recording of the user's background audio. By default this is option is set to `false`. - This feature only applies to the [Video](https://developers.onfido.com/guide/facial-similarity-reports#video) variant. +##### `face` fallback options - When enabled, it allows end-users to capture a selfie if their browser does not support MediaRecorder. - When disabled, we will return an unsupported browser error if the end-user browser doesn’t support MediaRecorder. +The SDK will try to fulfil the request depending on camera availability, device capabilities and browser support on the user's device: -- `showIntro` (boolean - default: `true`) +- if the selected variant cannot be fulfilled and the user is on a desktop, the user will first be forwarded to the cross-device screen. This default step is introduced with version 14 of the Web SDK. +- if a video cannot be taken on the mobile device, the face step can be configured to fallback to the `standard` variant (see `photoCaptureFallback`) +- if Motion cannot be captured on the mobile device, the face step can be configured to fallback to either `video` or `standard` variants (see `motionFallbackVariant`) - This feature applies to [Video](https://developers.onfido.com/guide/facial-similarity-reports#video) and [Standard](https://developers.onfido.com/guide/facial-similarity-reports#standard) variants. +If the SDK is initialized with the `requestedVariant` option for the face step, make sure you use the data returned in the [`onComplete` callback](#handling-callbacks) to request the correct report when creating a check. - When disabled for the Standard variant, it will remove the entire intro screen from the flow. - When disabled for the Video variant, it will hide the example video displayed in the intro screen, only showing the text instructions. +- **`photoCaptureFallback {Boolean}` - optional** -- `motionFallbackVariant` (string - default: `undefined`) + This feature only applies to the [video](https://developers.onfido.com/guide/facial-similarity-reports#video) variant. + By default, this option is `true` and allows end-users to capture a selfie if their mobile browser does not support MediaRecorder (which is required by the other variants). + When disabled, we will return an unsupported browser error if the end-user browser doesn’t support MediaRecorder. + +- **`motionFallbackVariant {String}` - optional** - This feature only applies to the [Motion](https://developers.onfido.com/guide/facial-similarity-reports#motion) variant and it allows to specify which face capture variant users will fallback to if Motion is not available on the end-user device due to MediaRecorder not being supported or to limited device capabilities. + This feature only applies to the [motion](https://developers.onfido.com/guide/facial-similarity-reports#motion) variant and allows to specify which face capture variant users will fallback to if Motion is not available on the end-user's mobile device due to MediaRecorder not being supported or to limited device capabilities. - If no variant is specified, then users on unsupported devices will receive an unsupported browser error instead. + By default, _no variant_ is specified which will result in users on unsupported devices receiving an unsupported browser error. The following example shows how to configure `motionFallbackVariant` to allow users on unsupported devices to fallback to Selfie: @@ -790,219 +853,603 @@ The custom options are: } ``` -- `recordMotionAudio` (boolean - default: `false`) - - When enabled, and the requested variant is `motion`, this feature allows Motion to record the user background audio. - -Please note that if a camera can’t be detected, we forward the user to the cross-device flow in order to attempt to capture in another device. - -#### complete +#### `complete` step This is the final completion step. The screen displays a completion message to signal the next steps to the user. This is an optional screen. The custom options are: - `message` (string) - `submessage` (string) -#### Cross device - mobile client introductory screen +## Advanced callbacks -When a user switches to the SDK's Cross Device flow, they will see an introductory screen when the SDK client loads on their mobile browser. -![Default Cross device mobile client introductory screen](demo/cross-device-client-intro.png) + -- **`crossDeviceClientIntroProductName {String} optional`** +> The following features must be enabled for your account before they can be used. For more information, please contact your Onfido Solution Engineer or Customer Success Manager. - You can customize the text by adding your company or product name to the subtitle with this option. We recommend that you set this, alongside the corresponding `crossDeviceClientIntroProductLogoSrc` below, to notify the user that this is part of a flow initiated on a desktop or laptop browser when they open the Cross Device link on their mobile browser. This is also an opportunity to include your branding in the SDK flow. + - ```javascript - Onfido.init({ - token: '', - crossDeviceClientIntroProductName: 'for a [COMPANY/PRODUCT NAME] loan', - }) - ``` +### Custom media callbacks - ![Cross Device Client Intro screen with client product name and copy](demo/cross-device-client-intro-example-1.png) +Custom media callbacks enable you to control the data collected by the Onfido SDK by using callbacks that are invoked when the end user submits their captured media. The callbacks provide all of the information that would normally be sent directly to the Onfido API and expect a promise in response, that controls what the SDK does next. -- **`crossDeviceClientIntroProductLogoSrc {String} optional`** +Once custom media callbacks are enabled for your account, you will need to add the optional `enterpriseFeatures` object at the root of `Onfido.init()`, set `useCustomizedApiRequests` to `true` and define the callbacks for `onSubmitDocument`, `onSubmitVideo`, `onSubmitSelfie`. - You can customize the icon by adding your company or product logo to be displayed instead of the default SDK icon image with this option. We recommend that you set this, alongside the corresponding `crossDeviceClientIntroProductName` above, to notify the user that this is part of a flow initiated on a desktop browser when they open the Cross Device link on their mobile browser. This is also an opportunity to include your branding in the SDK flow. - The image used should be no more than 144px in both height and width. +```javascript +Onfido.init({ + ... + enterpriseFeatures: { + useCustomizedApiRequests: true, + onSubmitDocument: (documentData) => { + // Your callback code here + }, + onSubmitSelfie: (selfieData) => { + // Your callback code here + }, + onSubmitVideo: (videoData) => { + // Your callback code here + }, + }, +}) +``` - ```javascript - Onfido.init({ - token: '', - crossDeviceClientIntroProductLogoSrc: 'path://to/logo/image/file', - }) - ``` +The callbacks return a `FormData` object, including the information that the SDK would send to Onfido. The callbacks are invoked when the end user confirms their image through the user interface. + +**Note** that the data can also be returned in `json` format by adding the property `formatter: 'raw'` under the `enterpriseFeatures` object. - ![Cross Device Client Intro screen with client product logo](demo/cross-device-client-intro-example-2.png) +##### `onSubmitDocument` data parameter -### Changing options in runtime +```javascript +{ + file: blob, + side: string, + type: string, + sdk_validations: object, + sdk_source: string, + sdk_version: string, + sdk_metadata: object, +} +``` -It's possible to change the options initialized at runtime: +##### `onSubmitSelfie` data parameter ```javascript -onfidoOut = Onfido.init({...}) -... -//Change the title of the welcome screen -onfidoOut.setOptions({ - steps: [ - { - type:'welcome', - options:{title:"New title!"} - }, - 'document', - 'face', - 'complete' - ] -}); -... -//replace the jwt token -onfidoOut.setOptions({ token: '' }); -... -//Open the modal -onfidoOut.setOptions({ isModalOpen:true }); +{ + file: blob, + snapshot: blob, + sdk_source: string, + sdk_version: string, + sdk_metadata: object, +} + +``` + +##### `onSubmitVideo` data parameter + +```javascript +{ + file: blob, + challenge: { type: 'recite' / 'movement', query: number[] / string } + challenge_id: string, + challenge_switch_at: number, // seconds + languages: { source: 'sdk', language_code: string } + sdk_source: string, + sdk_version: string, + sdk_metadata: object, +} ``` -The new options will be shallowly merged with the previous one, so you can only pass the differences to a get a new flow. +#### Uploading the media files to Onfido + +By default, this feature will prevent the request from being sent to Onfido, requiring you to [manually upload](https://documentation.onfido.com/#upload-document) the media files to Onfido from your backend for further processing. +We strongly recommend that you add all of the data provided to you through the callbacks in your request to the appropriate endpoint - `/documents` or `/live_photos`. Additionally, you should use the SDK token created for each applicant in the Authorization header of the request as shown below. + +**Note** that the SDK token is not included in the FormData provided by the callbacks. You may want to append this, or a different unique identifier that is mapped to the applicant's SDK token, on your backend before sending it off. + +``` +Authorization: Bearer +``` + +If you wish for the SDK to also upload the user-submitted data directly to Onfido you can resolve the promise with an object containing `continueWithOnfidoSubmission: true`. + +```javascript + onSubmitDocument: (data) => { + // Your callback code here + ... + // Once your code has executed, resolve the promise + return Promise.resolve({ continueWithOnfidoSubmission: true }) + } +``` + +#### Managing the Onfido response + +Once you have sent the request to Onfido yourself, you can supply the SDK with the response so it can determine what the end user should be presented with. +In the case where a success response is received, the promise should be resolved with `onfidoSuccessResponse: `. Otherwise reject the promise with the Onfido error response. +**Note**: An error response could be returned due to image quality issues. In this case, the SDK will present the end user with the appropriate error message. -## Creating checks +```javascript + onSubmitDocument: (data) => { + // Send request to Onfido API /documents via your backend proxy + .then(onfidoSuccessResponse => + Promise.resolve({ onfidoSuccessResponse: })) + .catch(onfidoError => Promise.reject(onfidoError)) + } +``` -The SDK is responsible for the capture of identity documents and selfie photos, videos, and motion captures. It doesn't perform any checks against the [Onfido API](https://documentation.onfido.com/). You need to access the Onfido API in order to manage applicants and perform checks. +This is a sample openAPI YAML file you could use as an example to start your own proxy. + +```yaml +openapi: 3.0.0 +info: + title: Network decouple back-end sample + description: Network decouple back-end setup skeleton + version: '1.0' + contact: {} +tags: [] +servers: [] +components: + schemas: + IDocumentsRequest: + type: object + properties: + file: + type: string + format: binary + description: Uploaded document. Passed in from the web SDK callback. + type: + type: string + default: passport + description: >- + The type of document that was submitted. Passed in from the web SDK + callback. + side: + type: string + default: front + description: >- + The type side of the document that was submitted. Passed in from the + web SDK callback. + sdk_metadata: + type: object + description: >- + The metadata that web SDK collects. Forward this to Onfido API + without modifications. Passed in from the web SDK callback. + sdk_validations: + type: object + description: >- + This is a an object used by web SDK to seek image quality feedback + from the API. Forward this object without modifications to Onfido + API. Passed in from the web SDK callback. + sdk_source: + type: string + default: onfido_web_sdk + description: >- + The source of origin of the requests. Forward this without + modifications to the Onfido API. Passed in from the web SDK callback. + sdk_version: + type: string + description: >- + The SDK version. Forward this without modifications to the Onfido + API. Passed in from the web SDK callback. + IMultiFrameSelfieRequest: + type: object + properties: + file: + type: string + format: binary + description: Uploaded photo + sdk_metadata: + type: object + description: >- + The metadata that web SDK collects. Forward this to Onfido API + without modifications. Passed in from the web SDK callback. + sdk_source: + type: string + default: onfido_web_sdk + description: >- + The source of origin of the requests. Forward this without + modifications to the Onfido API. Passed in from the web SDK callback. + sdk_version: + type: string + description: >- + The SDK version. Forward this without modifications to the Onfido + API. Passed in from the web SDK callback. + snapshot: + type: string + format: binary + description: Uploaded snapshot taken by the Web SDK to improve fraud analysis. +paths: + /onfido/v3.3/documents: + post: + operationId: OnfidoController documents + parameters: + - name: Authorization + in: header + description: Customer back-end Authentication token + schema: + type: string + requestBody: + required: true + description: The API endpoint to intercept the document upload from the Web SDK + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/IDocumentsRequest' + responses: + '200': + description: >- + The response received from Onfido v3.3/documents API call. The + response format might slightly vary with the use case. Forward it + without modifications as the callback response. + content: + application/json: + schema: + properties: + id: + type: string + format: uuid + created_at: + type: string + format: date-time + file_name: + type: string + file_size: + type: integer + file_type: + type: string + type: + type: string + side: + type: string + issuing_country: + type: string + applicant_id: + type: string + href: + type: string + download_href: + type: string + sdk_warnings: + type: object + '201': + description: '' + content: + application/json: + schema: + type: object + '422': + description: '' + content: + application/json: + schema: + properties: + error: + type: object + properties: + type: + type: string + message: + type: string + fields: + type: object + /onfido/v3/live_photos: + post: + operationId: OnfidoController + parameters: + - name: Authorization + in: header + description: Customer back-end Authentication token + schema: + type: string + requestBody: + required: true + description: The API endpoint to intercept the live photos upload from the Web SDK + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/IMultiFrameSelfieRequest' + responses: + '200': + description: >- + The response received from Onfido v3/live_photos API call. The + response format might slightly vary with the use case. Forward it + without modifications as the callback response. + content: + application/json: + schema: + properties: + id: + type: string + format: uuid + created_at: + type: string + format: date-time + file_name: + type: string + file_type: + type: string + file_size: + type: integer + href: + type: string + sdk_source: + type: string + sdk_version: + type: string + download_href: + type: string + '201': + description: '' + content: + application/json: + schema: + type: object +``` -### 1. Creating a check +#### Custom media callbacks in cross-device flows -For a walkthrough of how to create a document and facial similarity check using the Web SDK read our [Web SDK Quick Start guide](https://developers.onfido.com/guide/web-sdk-quick-start). +In the context of cross-device flows, you may choose to enable the media callbacks in either the desktop session or the mobile session. -For further details on how to [create a check](https://documentation.onfido.com/#create-check) with the Onfido API. +A prerequisite is that you host the cross-device experience of the Onfido SDK yourself, as described in the [self-hosted cross-device URL](#self-hosted-cross-device-url) section of this document. -Note: If you are testing with a sandbox token, please be aware that the results are pre-determined. You can learn more about [sandbox responses](https://documentation.onfido.com/#pre-determined-responses). +##### Enable custom media callbacks in mobile session -Note: If you are currently using API `v2` please refer to [this migration guide](https://developers.onfido.com/guide/api-v2-to-v3-migration-guide) for more information. +Once you have a server with the Onfido Web SDK installed and set up, you must initialize the mobile session with `mobileFlow: true` in addition to the callbacks and `useCustomizedApiRequests` options shown above. -### 2. Setting up webhooks +```javascript +Onfido.init({ + ... + enterpriseFeatures: { + useCustomizedApiRequests: true, + mobileFlow: true, + onSubmitDocument: (documentData) => { + // Your callback code here + }, + onSubmitSelfie: (selfieData) => { + // Your callback code here + }, + onSubmitVideo: (videoData) => { + // Your callback code here + }, + }, +}) +``` -Reports may not always return actual [results](https://documentation.onfido.com/#results) straightaway. +##### Enable custom media callbacks in desktop session -You can [set up webhooks](https://developers.onfido.com/guide/get-started-integrating#set-up-a-webhook) to be notified upon completion of a check or report, or both. +Media callbacks can also be triggered in the desktop session instead of the mobile session. +To do so, please contact your Onfido Solution Engineer or Customer Success Manager as additional configuration is required. -## User Analytics +### User analytics callbacks The SDK allows you to track a user's journey through the verification process via a dispatched event. This gives insight into how your users make use of the SDK screens. -### Overriding the hook +#### Overriding the hook In order to track a user's progress through the SDK an `EventListener` must be added that listens for `UserAnalyticsEvent` events. This can be done anywhere within your application. -For example: +The code inside of the `EventListener` callback will be invoked when an event is triggered. ```javascript addEventListener('userAnalyticsEvent', (event) => /*Your code here*/); ``` -The code inside of the `EventListener` will now be called when a particular event is triggered. For a full list of events see [tracked events](#tracked-events). +The `event` parameter being passed in the callback contains the following information: + +- `eventName {String}`: Name of the event triggered (full list below) +- `properties {Object}`: Event-specific properties +- `isCrossDevice {Boolean}`: Set to `true` when the event originates from a mobile session + +| eventName | +| ------------------------------------ | +| WELCOME | +| USER_CONSENT | +| DOCUMENT_TYPE_SELECT | +| ID_DOCUMENT_COUNTRY_SELECT | +| CROSS_DEVICE_INTRO | +| CROSS_DEVICE_GET_LINK | +| CROSS_DEVICE_START | +| DOCUMENT_CAPTURE_FRONT | +| DOCUMENT_CAPTURE_BACK | +| DOCUMENT_CAPTURE_CONFIRMATION_FRONT | +| DOCUMENT_CAPTURE_CONFIRMATION_BACK | +| FACIAL_INTRO | +| FACIAL_CAPTURE | +| FACIAL_CAPTURE_CONFIRMATION | +| VIDEO_FACIAL_INTRO | +| VIDEO_FACIAL_CAPTURE_STEP_1 | +| VIDEO_FACIAL_CAPTURE_STEP_2 | +| MOTION_FACIAL_INTRO | +| MOTION_FACIAL_ALIGNMENT | +| MOTION_FACIAL_CAPTURE | +| MOTION_FACIAL_NO_FACE_DETECTED | +| MOTION_FACIAL_CAPTURE_ERROR_TIMEOUT | +| MOTION_FACIAL_CAPTURE_ERROR_TOO_FAST | +| MOTION_FACIAL_UPLOAD | +| MOTION_FACIAL_UPLOAD_COMPLETED | +| MOTION_FACIAL_CONNECTION_ERROR | +| UPLOAD | + +## Self-hosted cross-device URL + + + +> The following feature must be enabled for your account before it can be used. For more information, please contact your Onfido Solution Engineer or Customer Success Manager. -The parameter being passed in is an `Event` object. The details related to the user analytics event can be found at the path `event.detail` and are as follows: + -| | | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `eventName` | **string**
Indicates the type of event. This will always be returned as `"Screen"` as each tracked event is a user visiting a screen. | -| `properties` | **map object**
Contains the specific details of an event. For example, the name of the screen visited. | +This feature allows you to specify your own custom or whitelabel url that the cross-device flow will redirect to instead of the Onfido default `id.onfido.com`. To use this feature, generate an SDK token as shown below and use it to start the SDK. -### Using the data +```bash + $ curl https://api.onfido.com/v3/sdk_token \ + -H 'Authorization: Token token=YOUR_API_TOKEN' \ + -F 'applicant_id=YOUR_APPLICANT_ID' \ + -F 'referrer=REFERRER_PATTERN' \ + -F 'cross_device_url=YOUR_CUSTOM_URL' +``` + +In addition to this, you must either: + +- Set up a server to forward the incoming HTTP request, including the path, to https://id.onfido.com -You can use the data to monitor how many users reach each screen in your flow. You can do this by storing the number of users that reach each screen and comparing that to the number of users who reached the `Welcome` screen. +- Set up a server to host the Onfido Web SDK yourself at the provided URL -### Tracked events +### Set up a server to forward the incoming HTTP request, including the path, to `https://id.onfido.com` -Below is the list of potential events currently being tracked by the hook: +You can do this by setting up a server as a reverse proxy so that the URL that the end-user sees is your selected URL but the content shown is the Onfido-hosted Web SDK. +An example set-up for a minimal nginx server using docker: +nginx.conf + +```nginx +server { + # Change the next 2 lines as needed + listen 80; + server_name localhost; + + location / { + # This forwards the path to Onfido and is the only change + # necessary when working with the default nginx configuration + proxy_pass https://id.onfido.com; + } +} ``` -WELCOME - User reached the "Welcome" screen -USER_CONSENT - User reached the "User Consent" screen -DOCUMENT_TYPE_SELECT - User reached the "Choose document" screen where the type of document to upload can be selected -ID_DOCUMENT_COUNTRY_SELECT - User reached the "Select issuing country" screen where the the appropriate issuing country can be searched for and selected if supported -CROSS_DEVICE_INTRO - User reached the cross device "Continue on your phone" intro screen -CROSS_DEVICE_GET_LINK - User reached the cross device "Get your secure link" screen -CROSS_DEVICE_START - User reached the "document capture" screen on mobile after visiting the cross device link -DOCUMENT_CAPTURE_FRONT - User reached the "document capture" screen for the front side (for one-sided or two-sided document) -DOCUMENT_CAPTURE_BACK - User reached the "document capture" screen for the back side (for two-sided document) -DOCUMENT_CAPTURE_CONFIRMATION_FRONT - User reached the "document confirmation" screen for the front side (for one-sided or two-sided document) -DOCUMENT_CAPTURE_CONFIRMATION_BACK - User reached the "document confirmation" screen for the back side (for two-sided document) -FACIAL_INTRO - User reached the "selfie intro" screen -FACIAL_CAPTURE - User reached the "selfie capture" screen -FACIAL_CAPTURE_CONFIRMATION - User reached the "selfie confirmation" screen -VIDEO_FACIAL_INTRO - User reached the "face video intro" screen -VIDEO_FACIAL_CAPTURE_STEP_1 - User reached the 1st challenge during "face video capture", challenge_type can be found in eventProperties -VIDEO_FACIAL_CAPTURE_STEP_2 - User reached the 2nd challenge during "face video capture", challenge_type can be found in eventProperties -MOTION_FACIAL_INTRO - User reached the "motion intro" screen -MOTION_FACIAL_ALIGNMENT - User reached the "motion alignment" screen -MOTION_FACIAL_CAPTURE - User reached the "motion capture" screen -MOTION_FACIAL_NO_FACE_DETECTED - User's face was not detected -MOTION_FACIAL_CAPTURE_ERROR_TIMEOUT - User's motion capture timed out -MOTION_FACIAL_CAPTURE_ERROR_TOO_FAST - User performed the motion headturn too fast -MOTION_FACIAL_UPLOAD - User's motion capture is uploading -MOTION_FACIAL_UPLOAD_COMPLETED - User's motion capture finished uploading -MOTION_FACIAL_CONNECTION_ERROR - User was presented the "motion connection error" screen during upload -UPLOAD - User's file is uploading + +dockerfile + +```docker +FROM nginx:1.15.8-alpine + +COPY ./nginx.conf /etc/nginx/conf.d/default.conf ``` -## Premium Enterprise Features +### Set up a server to host the Onfido Web SDK yourself at the provided URL -Please refer to the [Premium Enterprise Features documentation](ENTERPRISE_FEATURES.md) for details of the following features offered to our Enterprise customers: +This server must use the same version of the Onfido Web SDK and must initialize the SDK with `Onfido.init({ mobileFlow: true })`. All other configuration options, except for callbacks provided for the `useCustomizedApiRequests` feature, will be provided by your original instance of the Onfido Web SDK. -- Customized API Requests -- Callbacks Overview -- Cross device URL +This is an example of how you could host the Onfido Web SDK with minimal setup. This example involves using docker and an nginx image to serve an html file which starts the Onfido Web SDK using just the js and css files from the Onfido CDN (`https://sdk.onfido.com/`). -The above features must be enabled for your account before they can be used. For more information, please contact your Onfido Solution Engineer or Customer Success Manager. +File structure for this minimal example: -## Going live +```text +- dockerfile +- nginx.conf +- index.html +``` -Once you are happy with your integration and are ready to go live, please contact [client-support@onfido.com](mailto:client-support@onfido.com) to obtain a live API token. You will have to replace the sandbox token in your code with the live token. +dockerfile -Check the following before you go live: +```docker +FROM nginx:1.15.8-alpine -- you have set up [webhooks](https://documentation.onfido.com/#webhooks) to receive live events -- you have entered correct billing details inside your [Onfido Dashboard](https://onfido.com/dashboard/) +COPY ./nginx.conf /etc/nginx/conf.d/default.conf -## Accessibility +COPY ./index.html /usr/share/nginx/html/ -The Onfido SDK has been optimised to provide the following accessibility support by default: +COPY ./dist /usr/share/nginx/sdk/ -- Screen reader support: accessible labels for textual and non-textual elements available to aid screen reader navigation, including dynamic alerts -- Keyboard navigation: all interactive elements are reachable using a keyboard -- Sufficient color contrast: default colors have been tested to meet the recommended level of contrast -- Sufficient touch target size: all interactive elements have been designed to meet the recommended touch target size +``` -Refer to our [accessibility statement](https://developers.onfido.com/guide/sdk-accessibility-statement) for more details. +nginx.conf -⚠️ Note: If you make your own UI customizations, you are responsible for ensuring that the UI changes will still adhere to accessibility standards. For example, accessible color contrast ratios and dyslexic friendly fonts. +```nginx +server { + # Change the next 2 lines as needed + listen 80; + server_name localhost; -## TypeScript + location ~ ^/[0-9a-zA-Z]+$ { + root /usr/share/nginx/html; + try_files $uri /index.html =404; + } -From version `6.5.0`, TypeScript is officially supported, providing typings for: + location ~* \.(js|jpg|png|css)$ { + root /usr/share/nginx/sdk/; + } +} +``` -- `init()` method -- `options` argument (`SdkOptions`) and return object (`SdkHandle`) of `init()` method -- Arguments (`SdkResponse` and `SdkError`) for `onComplete()` and `onError()` callbacks -- `steps` option (`StepTypes` and `StepConfig`) -- `language` option (`SupportedLanguages` and `LocaleConfig`) -- `region` option (`ServerRegions`) +index.html + +```html + + + + + + + + Onfido Verification + + + + + +
+ + +``` ## More information -### Browser compatibility +### Supported browsers | ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png) | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png) | ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png) | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | -### Node.js compatibility +### Node.js supported versions The SDK is compatible with the all supported Node.js versions (currently starting with Node.js 16). +### Accessibility + +The Onfido SDK has been optimized to provide the following accessibility support by default: + +- Screen reader support: accessible labels for textual and non-textual elements available to aid screen reader navigation, including dynamic alerts +- Keyboard navigation: all interactive elements are reachable using a keyboard +- Sufficient color contrast: default colors have been tested to meet the recommended level of contrast +- Sufficient touch target size: all interactive elements have been designed to meet the recommended touch target size + +Refer to our [accessibility statement](https://developers.onfido.com/guide/sdk-accessibility-statement) for more details. + +⚠️ Note: If you make your own UI customizations, you are responsible for ensuring that the UI changes will still adhere to accessibility standards. For example, accessible color contrast ratios and dyslexic friendly fonts. + ### Troubleshooting -#### Content Security Policy issues +#### General Content Security Policy (CSP) issues In order to mitigate potential cross-site scripting issues, most modern browsers use a Content Security Policy (CSP). These policies might prevent the SDK from correctly displaying the images captured during the flow or correctly load styles. If CSP is blocking some of the SDK functionalities, make sure you add the following snippet inside the `` tag of your application. @@ -1010,13 +1457,13 @@ In order to mitigate potential cross-site scripting issues, most modern browsers