Перейти к содержимому
Справочник API Получить API-ключи

SDK и плагины · Глава 11

Flutter SDK

Запускайте проверку внутри своего приложения для Android или iOS с пакетом kyc_flutter. Он открывает проверку с доступом к камере и поддерживает электронную проверку паспортов и ID-карт.

4 мин чтения

Установка

Требования: Dart 3.5+, Flutter 3.24+, Android minSdk 24, iOS 13.

  1. Скачайте kyc_flutter.zip и распакуйте в свой проект, например в packages/kyc_flutter.
  2. Добавьте зависимость по пути в pubspec.yaml:
dependencies:
  kyc_flutter:
    path: packages/kyc_flutter
  1. Выполните 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