Установка
Требования: Dart 3.5+, Flutter 3.24+, Android minSdk 24, iOS 13.
- Скачайте kyc_flutter.zip и распакуйте в свой проект, например в
packages/kyc_flutter. - Добавьте зависимость по пути в
pubspec.yaml:
dependencies:
kyc_flutter:
path: packages/kyc_flutter
- Выполните
flutter pub get.
Пакета пока нет на pub.dev. В архиве есть приложение example/ со всеми настройками ниже.
Разрешения
SDK запрашивает камеру нативно, а затем передаёт её проверке. Если пользователь откажет, проверка покажет своё сообщение.
Android — android/app/src/main/AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
iOS — ios/Runner/Info.plist:
<key>NSCameraUsageDescription</key>
<string>The camera is used to photograph your document and take a selfie for identity verification.</string>
и включите разрешение камеры в ios/Podfile (внутри post_install):
target.build_configurations.each do |config|
config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)', 'PERMISSION_CAMERA=1']
end
а в начале Podfile укажите platform :ios, '13.0'.
Запуск проверки
Ваш бэкенд создаёт сессию (POST /applicants/{id}/sessions) и отправляет в приложение только её token. Передавайте token, а не url.
Никогда не кладите секретный API-ключ в приложение. Любой может извлечь его из пакета приложения.
import 'package:kyc_flutter/kyc_flutter.dart';
Future<void> verify(BuildContext context) async {
final token = await myBackend.createKycSession(); // session token
final result = await KycFlow.start(
context,
token: token,
locale: 'uz', // uz | ru | en, optional
);
if (result.isCancelled) {
// Closed before a decision. result.errorCode: link_invalid, session_expired, network, …
return;
}
switch (result.decision!) {
case KycDecision.green:
showMessage('Thank you! We are confirming your verification.');
case KycDecision.onHold:
showMessage('Your documents are under review.');
case KycDecision.red:
// decisionType: 'retry' — can try again with a new session; 'final' — cannot
showMessage('Verification failed: ${result.rejectLabels.join(', ')}');
}
// Unlock features only after your backend confirms the decision.
await myBackend.refreshKycStatus();
}
KycFlow.start открывает полноэкранный маршрут и возвращает Future<KycResult>. Результат никогда не бывает null: если пользователь закроет экран, вы получите отменённый результат. Маршрут закрывается сам через 3 секунды после экрана результата.
| Параметр | По умолчанию | Описание |
|---|---|---|
token |
обязательно | token сессии |
baseUrl |
https://kyc.goxost.net |
Только HTTPS |
locale |
locale заявителя |
uz, ru или en |
title |
«Проверка личности» на языке locale (на английском, если не задан) |
Заголовок панели приложения |
closeDelay |
3 секунды | Сколько экран результата остаётся открытым перед закрытием |
onEvent |
— | Вызывается для каждого события (см. ниже) |
readChip |
true |
Выполнять электронную проверку документа, когда этого требует сценарий |
KycResult:
| Поле | Тип | Описание |
|---|---|---|
decision |
KycDecision? |
green, red, onHold; null при отмене. .code даёт GREEN, RED, ON_HOLD |
decisionType |
String? |
final или retry для RED, иначе обычно null |
rejectLabels |
List<String> |
Коды причин, см. Ошибки и коды |
errorCode |
String? |
Последняя ошибка, если проверку закрыли без решения |
isCancelled |
bool |
true, если решения нет |
Результат в приложении нужен только для интерфейса. Итоговое решение берите на бэкенде — из вебхука или GET /verifications/{id}.
Встраивание в свой экран
Чтобы разместить проверку внутри своей вёрстки, используйте KycView:
SizedBox(
height: 640,
child: KycView(
key: ValueKey(token), // a new key restarts the flow with a new token
token: token,
locale: 'ru',
onStep: (step) {}, // KycStep.consent, document, liveness, processing, handoff
onComplete: (result) {}, // KycResult
onError: (code) {}, // link_invalid, session_expired, network, http_<status>, …
onCancel: () {}, // system back before a result
onEvent: (event) {}, // every event, including ready and resize
),
)
KycView нужен ограниченный размер — например, внутри Expanded, SizedBox или тела Scaffold. Электронную проверку документа он не выполняет; для неё используйте KycFlow.start.
События (onEvent): KycReadyEvent, KycStepEvent, KycCompleteEvent, KycErrorEvent, KycResizeEvent — те же события, что и в kyc.js.
Электронная проверка документа
Если в сценарии электронная проверка документа задана как optional или required (панель → Настройки), KycFlow.start выполняет её после снимков: экран с инструкцией, прогресс, повтор и кнопка пропуска, если сценарий это разрешает. Телефоны, которые её не поддерживают, пропускают этот шаг автоматически. Чтобы отключить её, передайте readChip: false. Полученные данные не записываются на устройство.
Android — добавьте в манифест. required="false" сохраняет возможность установки на телефоны без этой функции:
<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />
iOS (iPhone 7 или новее) — добавьте в ios/Runner/Info.plist:
<key>NFCReaderUsageDescription</key>
<string>Used to check your identity document electronically.</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
</array>
Затем в Xcode → Signing & Capabilities добавьте Near Field Communication Tag Reading. Это создаст ios/Runner/Runner.entitlements:
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
<string>TAG</string>
</array>
Для App ID должна быть включена та же capability. Электронная проверка работает только на реальном устройстве, не в симуляторе.
Веб-проверка и kyc.js не выполняют электронную проверку документа. Если в сценарии она required и запасной вариант не разрешён, отправка из веба завершится ошибкой 409 nfc_required — для веб-пользователей используйте отдельный сценарий.
Решение проблем
| Проблема | Решение |
|---|---|
ArgumentError при запуске |
Передайте token сессии (начинается с eyJ), а не url; baseUrl должен быть HTTPS |
| Чёрный экран камеры на iOS | Проверьте NSCameraUsageDescription и PERMISSION_CAMERA=1 в Podfile, затем выполните pod install |
| Камера не открывается на Android | Проверьте разрешение CAMERA в манифесте и что пользователь разрешил его в системных настройках |
errorCode: link_invalid или session_expired |
Сессия использована, заменена или истекла — создавайте новую сессию для каждой попытки |
KycView пустой или выдаёт ошибку вёрстки |
Задайте ему ограниченную высоту |
| Нет шага электронной проверки | В сценарии она off, телефон её не поддерживает, readChip равен false или вы используете KycView |
| Электронная проверка не работает на iOS | Проверьте запись select-identifiers, capability и настройки App ID |