Microblink Document Capture помогает встроить в приложение автоматическую съёмку удостоверений: камера сама находит документ, подсказывает, как убрать блики, размытие и сильный наклон, последовательно принимает лицевую и оборотную стороны, а затем возвращает выровненное изображение вместе с исходным кадром. Разработчик может использовать готовый экран захвата или построить собственный сценарий на Direct API, настроить требования к DPI, проверки качества, подсказки, локализацию и повторную съёмку неудачной стороны.

Рабочий процесс начинается с полноэкранного видоискателя. В центре находится прицел, под ним появляется короткая команда: показать лицевую сторону, приблизить или отдалить карту, выровнять её, улучшить освещение, устранить размытие либо блик. Когда геометрия и качество кадра удовлетворяют анализатор, прицел переходит в состояние успеха; для двухстороннего документа интерфейс показывает анимацию переворота и продолжает ту же сессию, не заставляя пользователя возвращаться к исходному экрану.

На выходе приложение получает не только перспективно исправленную область документа, но и исходный кадр камеры. Это позволяет отправить аккуратно обрезанную копию в распознавание или проверку, а оригинал сохранить для аудита качества, повторной обработки либо собственного алгоритма. Сам компонент не собирает многостраничный PDF и не редактирует его содержимое: его задача — получить пригодное изображение удостоверения до того, как начнутся OCR, извлечение полей, проверка подлинности или формирование файла.

Как проходит автоматический захват документа

Главное отличие этого сценария от обычной кнопки камеры состоит в непрерывном анализе видеопотока. Пользователю не нужно угадывать, когда нажать спуск: анализатор рассматривает последовательность кадров, ищет границы удостоверения, оценивает положение относительно камеры и ждёт сочетания условий, при котором изображение можно считать пригодным. Если карта слишком далеко, занимает лишь малую часть кадра или выходит за пределы видимой области, подсказка меняется до фактической съёмки. Поэтому значительная часть брака отсеивается ещё до создания итогового изображения, а не после отправки на сервер.

Во встроенном экране одновременно работают несколько уровней обратной связи. Текст сообщает конкретное действие, прицел показывает текущее состояние, а включение фонаря доступно непосредственно в видоискателе. Для бликующих пластиковых карт предусмотрено отдельное предупреждение: яркое освещение может сделать фотографию формально резкой, но закрыть голограммой или белым пятном имя, номер и портрет. Интерфейс предлагает слегка изменить угол карты, а не просто повысить яркость. Это важнее общего сообщения плохое качество, потому что пользователь понимает, какое движение исправит ситуацию.

После принятия первой стороны анализатор определяет, завершён ли документ. Паспортная страница обычно рассматривается как односторонний объект, поэтому результат можно вернуть сразу. Для водительского удостоверения или идентификационной карты, где значимые данные находятся с двух сторон, появляется понятная команда перевернуть документ. Следующая сторона снимается в той же камере и связывается с первой в одном результате. Приложению не требуется самостоятельно строить два независимых запуска и затем угадывать, к какой заявке относится второй кадр.

Автоматическая перспектива исправляет трапециевидное искажение, возникающее, когда телефон находится не строго параллельно карте. Готовая область становится прямоугольной и удобной для последующего распознавания. При этом коррекция не заменяет требования к исходному кадру: если документ снят под чрезмерным углом, часть деталей растянута, а блик закрывает строки, анализатор должен попросить изменить положение, а не искусственно дорисовывать недостающие сведения. Сочетание предварительных проверок и геометрического выравнивания даёт более предсказуемый вход для OCR и проверки документа.

Элементы видоискателя и их назначение

В левом верхнем углу встроенного экрана находится выход из сессии. Его следует воспринимать как полноценное пользовательское действие и обрабатывать отдельно от успешного результата. Человек может закрыть камеру из-за отсутствия документа, отказа продолжать или случайного запуска; бизнес-логика не должна показывать такое завершение как техническую ошибку. На противоположной стороне размещается управление фонарём. Иконка меняется для включённого и выключенного состояния, поэтому её можно стилизовать, сохранив различимость двух режимов.

Центральный прицел работает как индикатор этапа, а не как декоративная рамка. В нейтральном состоянии система ещё собирает подходящие кадры. Анимация прогресса показывает, что положение близко к правильному и анализ продолжается. Ошибка сопровождается цветом и инструкцией, например приблизьте документ. Успех обозначает принятие стороны; после него не нужно повторно нажимать кнопку. Если собственная тема меняет графику, эти состояния должны оставаться визуально различимыми даже при слабом экране, высокой яркости улицы и включённом системном увеличении.

Нижнее предупреждение о вспышке не следует закрывать собственной панелью навигации. Оно появляется в ситуации, когда фонарь помогает освещению, но одновременно создаёт отражение. Центральная инструкция и предупреждение решают разные задачи: первая сообщает, как расположить карту, второе объясняет оптическую проблему. При проектировании фирменной темы полезно проверить одновременное отображение обоих текстов на небольшом экране, иначе важное сообщение может выйти за безопасную область или наложиться на системную жестовую панель.

Иконка карты и анимация переворота особенно важны там, где пользователи путают оборотную сторону с повторной съёмкой лицевой. Их можно заменить фирменными drawable или изображениями, но смысл должен сохраняться: первая картинка представляет уже принятую сторону, вторая — сторону, которую требуется показать. Нежелательно подменять этот элемент абстрактной стрелкой без изображения карты, поскольку при работе с паспортом, пластиковой картой и бумажным удостоверением одна и та же стрелка может трактоваться неоднозначно.

Введение, обучение и помощь во время съёмки

Перед камерой можно показать короткое вводное окно. Оно подходит для единственной критической инструкции, которую пользователь должен увидеть перед первой попыткой: держать все поля открытыми, не закрывать нижнюю строку пальцем и обеспечить равномерное освещение. Вводное окно закрывается одной кнопкой и не требует проходить несколько страниц. Такой вариант уместен в короткой форме идентификации, когда лишний шаг снижает завершение, но без предупреждения люди часто держат карту за область с текстом.

Многостраничное обучение раскрывает правила по одному. На страницах можно показать правильное и неправильное положение документа, предупредить о пальцах и голографических отражениях, объяснить расстояние до камеры. Индикатор страниц сообщает объём обучения, а кнопки пропустить, назад, далее и завершить дают управляемый выход. В Android видимость вводного окна и обучения задаётся раздельно через параметры UX, поэтому их не обязательно показывать вместе. Для повторных клиентов обычно оставляют только контекстную помощь, а подробное обучение включают при первом запуске или после нескольких неудачных попыток.

Кнопка помощи остаётся доступной в видоискателе и позволяет снова открыть рекомендации, не отменяя операцию. Рядом с ней может появляться подсказка Нужна помощь?. Стандартная задержка такой подсказки составляет двенадцать секунд; интервал задаётся в миллисекундах. Это значение стоит сопоставить с реальным временем успешной съёмки: если большинство пользователей заканчивает за пять секунд, ранняя подсказка будет мешать; если сложные глянцевые документы занимают двадцать секунд, предложение помощи после затянувшейся попытки уместно.

Отключать обучение следует после проверки аналитики, а не только ради сокращения пути. Если после удаления инструкций растёт доля отклонённых кадров, время экономится лишь на клиенте, но теряется на повторной проверке. Практичная схема состоит в том, чтобы показывать вводное окно в первом сеансе, сохранять факт ознакомления в настройках приложения и повторно предлагать помощь при серии ошибок качества. Сам SDK отображает интерфейс; решение о том, когда считать пользователя обученным, остаётся за приложением.

Подсказки качества: что именно исправляет пользователь

Набор команд охватывает геометрию, резкость и освещение. Приблизьте появляется, когда документ занимает слишком мало пикселей и итоговая область не достигнет требуемой детализации. Отдалите нужна, если края выходят из кадра или камера находится слишком близко для устойчивой фокусировки. Держите документ видимым сообщает о частичном перекрытии границ. Выровняйте относится к положению внутри видоискателя, а команды поворота помогают привести ориентацию к ожидаемой.

Освещение оценивается не одной общей величиной. Слишком тёмная сцена скрывает мелкий шрифт и защитные элементы, однако чрезмерный свет может выбить светлые участки. Поэтому предусмотрены раздельные сообщения об увеличении и уменьшении интенсивности. Пользователю полезнее предложить перейти к рассеянному освещению, чем безусловно включить фонарь: на матовой бумаге фонарь помогает, на ламинированной карте создаёт локальный пересвет. В собственном тексте локализации команды должны оставаться короткими, поскольку они обновляются в реальном времени.

Команда устранить размытие означает, что текущий кадр недостаточно резок. Причиной может быть движение руки, дрожание карты, медленный автофокус или слишком малая дистанция. Сценарий должен дать человеку время стабилизировать телефон, а не мгновенно сменять несколько сообщений. Для киоска с фиксированной камерой полезно дополнительно проверить выдержку и постоянное освещение, поскольку пользователь не сможет компенсировать аппаратную конфигурацию движением телефона.

Команда устранить блик относится к области документа, а не к общей яркости кадра. На удостоверениях с голограммой отражение может перемещаться при минимальном наклоне, поэтому наиболее эффективная инструкция — слегка повернуть карту или телефон, сохраняя все края в кадре. Если приложение добавляет собственную рамку, она не должна принуждать держать карту строго в одном угле, когда анализатор просит изменить отражение. Небольшая свобода внутри видоискателя помогает найти положение без бликов.

Настройки DPI и пригодность результата

Минимальный DPI задаёт ожидаемую детализацию исправленного изображения документа. Значение связывает физический размер удостоверения с количеством пикселей в итоговом кадре и помогает не принимать слишком далёкую съёмку. Стандартная настройка ориентирована примерно на 230 DPI. Повышение порога может улучшить мелкие символы для последующего OCR, но одновременно потребует приблизить карту, повысит чувствительность к фокусу и может увеличить число неудачных попыток на недорогих камерах.

Параметр автоматической корректировки минимального DPI позволяет анализатору адаптироваться, когда входное разрешение не позволяет строго выполнить исходное требование. В результате можно проверить признак того, что DPI был скорректирован, и решить, допустим ли такой кадр для конкретной операции. Например, просмотр человеком может терпеть меньшую детализацию, а автоматическое чтение мелкой зоны или проверка защитного рисунка — нет. Не стоит молча принимать скорректированный результат во всех процессах одинаково.

Сохранение DPI в преобразованном изображении важно для систем, которые читают метаданные разрешения, а не только размеры в пикселях. Если последующий конвейер рассчитывает масштаб документа или печатает копию, нужно проверить, сохраняется ли ожидаемое значение после перспективного преобразования. Одновременно следует помнить, что запись DPI сама по себе не создаёт деталей: маленький исходный объект, увеличенный интерполяцией, не станет эквивалентом хорошо снятой крупной карты.

Ошибка неподходящих настроек анализатора возникает, когда разрешение входа слишком мало, чтобы выполнить заданные требования. Это отличается от обычного неудачного кадра: пользователь не исправит проблему, если камера или переданный файл в принципе не содержит нужного числа пикселей. В интерфейсе следует предложить выбрать оригинал большего размера, переключить камеру или изменить обоснованный порог, а в журнале разработки сохранить разрешение входа и активные настройки. Простая повторная попытка с тем же уменьшенным изображением результата не даст.

Политики размытия, бликов и наклона

Проверки качества можно настроить по строгости. Для размытия, блика и наклона доступны уровни, которые условно соответствуют строгому, обычному, ослабленному и отключённому контролю. Выбор политики должен исходить из назначения изображения. При регистрации банковского клиента строгая проверка оправдана, поскольку ошибка чтения приводит к ручной обработке. При внутреннем хранении уже известных карт иногда достаточно обычного уровня, чтобы не блокировать работу из-за незначительного отражения вне текстовых зон.

Строгая политика не гарантирует идеальность каждого пикселя и не заменяет проверку результата. Она лишь повышает требования к кадрам, которые анализатор готов принять. Чем жёстче критерий, тем дольше пользователь ищет подходящее положение. Поэтому измерять нужно не только процент успешного OCR, но и медианное время, число подсказок, долю отмен и повторных обращений. Оптимальная настройка — та, которая даёт достаточную пригодность при приемлемом усилии, а не максимальное число активных проверок.

Отключение конкретной политики допустимо, когда мешающий фактор контролируется другим способом. Например, в киоске с фиксированным держателем наклон может быть физически ограничен, но проверка бликов остаётся необходимой. В мобильной съёмке отключать наклон опаснее: сильная перспектива растягивает край документа и ухудшает мелкий текст, даже если прямоугольник удаётся восстановить. Для каждого отключения следует записать причину и тестировать минимум на нескольких типах удостоверений.

Применять одинаковые значения ко всем этапам необязательно. Сначала можно использовать обычные критерии, затем пропускать принятую сторону через дополнительный фильтр, который решает, достаточно ли изображения для последующего извлечения. Такой подход предотвращает бесконечный поиск идеального кадра и одновременно не выпускает данные, которые конкретный распознаватель не способен обработать. Важно, что при отклонении фильтром та же сторона переснимается в текущей камере, а вся сессия не начинается заново.

Готовый экран или Direct API

Готовый UX разумно выбирать, когда нужен проверенный путь от открытия камеры до получения двух сторон. Он уже содержит видоискатель, управление фонарём, инструкции, вводное окно, обучение, помощь, анимацию переворота и завершение. Интегратору остаётся задать лицензию, запустить экран с настройками, разобрать статус и забрать результат. Это сокращает объём кода вокруг камеры и уменьшает риск пропустить состояние, при котором пользователь должен приблизить документ или убрать блик.

Direct API выбирают, когда камера уже реализована в приложении, нужен нестандартный горизонтальный макет, захват идёт из видеопотока устройства, либо дизайн не допускает встроенного контроллера. В этом режиме разработчик передаёт кадры анализатору и получает обратную связь по каждому изображению. На основе состояния приходится самостоятельно отрисовать рамку, сообщения, прогресс, ошибки, кнопку фонаря и переход между сторонами. Свобода выше, но ответственность включает жизненный цикл камеры, ориентацию буфера, частоту кадров, преобразование координат и доступность интерфейса.

Для потока используется анализ последовательных кадров. Каждый новый кадр уточняет состояние, а итог формируется на основании накопленной информации. Когда состояние сообщает, что документ принят, результат можно отделить от анализатора, чтобы последующие кадры не изменили его. Для заранее имеющихся фотографий применяется анализ отдельных изображений; при одном кадре на сторону включается стратегия SingleFrame. Эти режимы нельзя механически смешивать: метод, оптимизированный для одного файла, не должен получать бесконечный поток без управления нагрузкой.

Анализатор допускает захват одного документа за раз. Если приложение открывает две параллельные формы или запускает обработку из нескольких экранов, нужен собственный диспетчер сессии. Перед следующим документом состояние сбрасывают, после завершения работы освобождают выделенную память. Несоблюдение этой последовательности проявляется как смешение сторон, старый результат в новой заявке или накопление памяти после многократных открытий камеры.

Интеграция в Android-проект

Библиотеки Android публикуются через Maven Central. Для предоставленного интерфейса подключают зависимость capture-ux; Direct API требует только capture-core. Репозиторий mavenCentral должен быть доступен в конфигурации сборки. Номер зависимости фиксируют в централизованном каталоге версий проекта, чтобы UX и Core не разошлись. После обновления полезно очистить кеш сборки только при фактическом конфликте: безусловное удаление кешей затрудняет диагностику, поскольку скрывает причину несовместимости транзитивных зависимостей.

Лицензионный файл помещают в assets приложения и задают до обращения к другим классам SDK. Практичное место — onCreate собственного класса Application. Лицензия привязана к application ID, поэтому debug, staging и production с разными идентификаторами должны получать подходящие ключи. Ошибка часто возникает, когда файл присутствует, но Gradle добавляет суффикс к debug-идентификатору; путь к assets выглядит правильным, однако ключ выпущен для другой строки пакета.

Запуск встроенного экрана строится на контракте MbCapture и Activity Result API. Колбэк проверяет статус CaptureResult до чтения analyzerResult. При DOCUMENT_CAPTURED результат доступен; CANCELLED означает выход пользователя или незавершённое завершение; ERROR_LICENCE_CHECK относится к проверке лицензии; ERROR_ANALYZER_SETTINGS_UNSUITABLE сообщает о несовместимости разрешения входа с настройками. Логика не должна обращаться к analyzerResult во всех ветках, иначе отмена превратится в исключение из-за отсутствующего объекта.

Минимальная поддерживаемая версия системы соответствует API level 21. Для камеры важна именно резолюция preview не ниже 1080p, а не заявленное разрешение видеозаписи или фотографии в рекламных характеристиках телефона. Некоторые устройства умеют писать видео высокого разрешения, но отдают стороннему приложению меньший поток при выбранном размере Surface. Во время теста следует записывать фактический размер кадров, передаваемых анализатору, особенно на моделях с несколькими задними камерами.

Архитектуры и нативные библиотеки Android

Нативные бинарные файлы рассчитаны на armeabi-v7a и arm64-v8a. В defaultConfig рекомендуется ограничить abiFilters этими архитектурами. Это не только уменьшает вероятность установки на неподдерживаемое устройство, но и предотвращает конфликт с другой C++-библиотекой, которая собрана для непересекающегося ABI. Если виртуальная машина выбирает архитектуру, для которой одна из зависимостей отсутствует, приложение может завершиться с UnsatisfiedLinkError уже при инициализации.

Эмулятор x86 не подходит для полноценной проверки такого набора ABI. Основные сценарии следует запускать на реальных ARM-устройствах. Для публикации через Android App Bundle магазин сформирует пакет с нужной архитектурой и не будет раздавать обе нативные копии каждому телефону. По официальному расчёту добавка для одной ABI составляет примерно 2,6 МБ в APK и около 2,4–2,5 МБ в загрузке; реальный итог зависит от сжатия, ресурсов приложения и других библиотек.

Если в проекте есть собственный загрузчик нативных библиотек, порядок и обработку ошибок необходимо согласовать до первого вызова SDK. Симптомы проблемы — корректная работа на arm64, но падение на старом ARMv7, либо обратная ситуация после добавления стороннего компонента. Диагностика начинается с APK Analyzer: проверяют содержимое каталогов lib, затем сопоставляют его с abiFilters и supportedAbis устройства. Подмена причины сообщением камера недоступна затруднит поддержку, потому что сбой происходит до открытия камеры.

Интеграция в iOS-проект

На iOS используются CaptureUX.xcframework и CaptureCore.xcframework. При ручном добавлении оба фреймворка переносят в проект как группы, включают в цель и для динамических компонентов выбирают Embed & Sign. В Linked Frameworks and Libraries добавляют libc++.tbd и libz.tbd. Если фреймворк только связан, но не встроен, сборка может пройти, а приложение завершится при запуске из-за отсутствующего динамического образа. Если файл добавлен как folder reference, Xcode может сформировать неожиданную структуру ресурсов.

Доступны также Swift Package Manager и CocoaPods. При SPM UX и Core представлены отдельными публичными пакетами, поэтому нужно убедиться, что целевой модуль приложения получает оба продукта, когда используется готовый экран. При CocoaPods после установки открывают workspace, а не исходный xcodeproj; иначе зависимости будут видны в файловой системе, но не в активной схеме. В больших проектах способ поставки выбирают один и не смешивают ручной XCFramework с тем же компонентом из менеджера пакетов.

Минимальная система — iOS 13.0. Фреймворки подходят для Swift и Objective-C и не содержат bitcode. В современном проекте это обычно не требует действий, но старый конвейер, который всё ещё ожидает bitcode для каждого зависимого фреймворка, нужно перенастроить. Перед сборкой для публикации проверяют, что Embed & Sign применён к основной цели, расширения не встраивают дубликаты без необходимости, а архитектуры XCFramework соответствуют устройству и симулятору.

Лицензию задают до создания контроллера захвата, предпочтительно при запуске приложения. Ключ можно передать строкой либо ресурсом из bundle. Для файла нужно проверить членство в target и фазу Copy Bundle Resources. Недействительный или истёкший ключ приводит к исключению или ошибке в callback, поэтому обработчик лицензирования должен завершить инициализацию до того, как пользователь нажмёт кнопку камеры. Нельзя маскировать сбой общим пустым экраном: показывайте понятное внутреннее сообщение и сохраняйте техническую причину в защищённом журнале.

Контроллер, делегат и завершение на iOS

Готовый сценарий создаётся через MBICCaptureSettings и MBICCaptureViewController. Контроллеру назначают делегат и показывают его полноэкранно. Итог возвращается методом MBICCaptureViewControllerDelegate, который получает MBICAnalyserResult. Сильную ссылку на контроллер и настройки хранят столько, сколько длится сессия, а после завершения освобождают. Если объект исчезнет раньше, делегат может не получить событие; если держать его после закрытия вместе с тяжёлыми изображениями, память не вернётся.

Закрытие камеры следует выполнять в согласованной точке: сначала зафиксировать результат или отмену, затем убрать контроллер и обновить форму. Двойное закрытие из делегата и внешней кнопки создаёт гонку переходов. Для защиты вводят состояние сессии — launching, capturing, finishing, finished — и допускают завершение только один раз. Этот же механизм предотвращает повторную отправку одной заявки, если callback приходит в момент, когда пользователь нажал системный жест назад.

Настройка внешнего вида на Android

Тема встроенного экрана передаётся через свойство style в CaptureSettings. Для кнопки выхода задаётся drawable, для фонаря — отдельные изображения включённого и выключенного состояния. Текст инструкции имеет TextAppearance и фоновый drawable; предупреждение о блике настраивается независимо. Такой раздельный подход позволяет сделать обычную команду компактной, а предупреждение — более заметным, не меняя внутреннюю логику появления.

Для анимации переворота доступны изображения лицевой и оборотной сторон карты. Прицел имеет отдельные drawable для нейтрального, успешного и ошибочного состояний, а цвет внутренних фигур задаётся отдельно. Проверяйте контраст каждого состояния на светлом и тёмном участке видеопотока: камера не имеет постоянного фона, поэтому цвет, хорошо видимый в макете, может пропасть на белом столе или чёрной обложке паспорта. Полупрозрачная подложка должна помогать, но не закрывать края документа.

Вводное окно настраивает внешний вид заголовка, сообщения, фона и иллюстрации. У обучения есть цвета изображений, текста, кнопок, фона и индикатора страницы. Кнопка помощи получает собственный drawable, всплывающая подсказка — цвет фона и TextAppearance. Диалоги ошибок также допускают отдельные стили заголовка, сообщения, кнопки и фона. При глубокой фирменной настройке важно не потерять системный размер касания и поддержку крупного шрифта.

Строки переопределяются через CaptureOverlayStrings. Отдельно задаются helpTooltip, flashlightWarning, набор OnboardingStrings, InstructionsStrings и AlertStrings. Среди инструкций есть съёмка лицевой и оборотной сторон, переворот, поворот, приближение, удаление, удержание документа в кадре, выравнивание, изменение освещения, устранение размытия и блика. Это позволяет сделать перевод терминологически согласованным с остальной формой, но массивы заголовков и сообщений обучения должны содержать соответствующее число элементов.

Темы и локализация на iOS

На iOS внешний вид задаётся объектом MBICCaptureViewControllerTheme в настройках контроллера. Для вводного alert можно менять цвет и шрифт заголовка, цвет и шрифт сообщения, оформление кнопки Done. У учебных страниц настраиваются кнопки закрытия и перехода, заголовок, сообщение и Page Control. Статусная плашка поддерживает шрифт и радиус углов, а изображение успешного сканирования можно заменить фирменным.

Отдельные параметры предусмотрены для подсказки, кнопки помощи, ошибочного цвета прицела, изображений фонаря, картинок первой и второй сторон, предупреждений о вспышке. Поддерживается тёмный режим, но камера остаётся динамическим фоном. Поэтому тёмная тема не означает, что все элементы следует делать светлыми без подложки: белая иконка исчезает на светлой карте. Проверять нужно реальные сцены и оба системных оформления, включая увеличение контраста.

В поставке iOS заявлена локализация на 23 языка. Используются каталоги строк xcstrings, которые при сборке формируют Localizable.strings в папках lproj. Строки можно изменить для нужного языка внутри фреймворка, но такой способ требует дисциплины при обновлении: ручные правки легко перезаписать. Надёжнее хранить список изменённых ресурсов и автоматическую проверку, которая сравнивает их после замены XCFramework. Перевод должен оставаться кратким, чтобы статус не занимал область документа.

Особое внимание требуется языкам с длинными словами и направлением справа налево. Даже если базовая локализация присутствует, фирменные тексты могут не помещаться в одну строку. Проверьте кнопки обучения, сообщения о сети и лицевой/оборотной стороне при максимальном системном размере шрифта. Значок переворота и логика сторон не должны полагаться только на направление стрелки; текст и изображение карты вместе снижают риск неправильной интерпретации.

Результаты захвата и дальнейшая обработка

После успешной сессии основным объектом становится результат анализатора. Для каждой принятой стороны доступны выровненное изображение документа и исходный кадр. Выровненная копия удобна для OCR, классификации, проверки читаемости и отображения в компактном подтверждении. Исходный кадр сохраняет окружающую сцену и геометрию до коррекции; он полезен для диагностики, но может содержать лишние персональные или бытовые детали, поэтому хранить его без цели не следует.

Приложение должно явно решить, какие изображения передавать дальше. Если сервер ожидает только прямоугольную карту, отправка полного кадра расходует трафик и расширяет объём персональных данных. Если служба контроля качества должна понимать причину брака, оригинал может быть нужен на ограниченный срок. Политика хранения, шифрование, права доступа и удаление относятся к приложению и серверу: компонент возвращает данные, но не определяет вашу модель жизненного цикла.

Для двухстороннего документа сохраняют порядок сторон и идентификатор одной сессии. Не следует складывать два изображения в общий каталог без метаданных: при параллельных заявках легко перепутать оборотные стороны. Практичная модель содержит sessionId, side, transformedImage, originalFrame, факт корректировки DPI, время захвата и итог дополнительного фильтра. После подтверждённой загрузки временные файлы удаляют, если они не нужны для повторной отправки.

Формат итогового изображения и способ сериализации проверяют по API конкретной платформы. Не стоит предполагать, что объект можно безопасно удерживать в памяти до конца длинной анкеты. Фотография 1080p и оригинальный кадр занимают заметно больше места после декодирования, чем сжатый файл. Для многошаговой формы результат лучше записать в защищённый временный файл, освободить bitmap или UIImage и загружать потоково, контролируя поворот и цветовой профиль.

Дополнительный CaptureFilter и проверка извлекаемости

CaptureFilter вызывается после успешного захвата каждой стороны и принимает либо отклоняет её. При отклонении камера остаётся открытой, состояние возвращается к текущей стороне, пользователь повторяет попытку без повторного прохождения введения и без потери уже принятой стороны. Это место подходит для бизнес-специфической проверки: наличие ожидаемой зоны, достаточная читаемость внешним алгоритмом, допустимый тип документа или серверный сигнал, если задержка и политика конфиденциальности это позволяют.

Готовый BlinkIdCaptureFilter запускает извлечение BlinkID на принятом изображении и оставляет сторону только тогда, когда она пригодна для извлечения. На Android для него подключается дополнительная зависимость и задаётся отдельная лицензия BlinkID; на iOS добавляется соответствующий XCFramework и также настраивается лицензия распознавания. Это принципиально: лицензия на захват не превращает Capture в OCR, а фильтр добавляет ещё один продукт и вычислительный этап.

Фильтр не должен выполнять долгую операцию без обратной связи. Пока он решает судьбу кадра, пользователь ожидает в камере; если проверка занимает секунды, нужен индикатор и защита от повторного действия. При сетевой валидации следует определить тайм-аут и поведение без связи: разрешить кадр, попросить повторить, сохранить для отложенной проверки или остановить процесс. Нельзя бесконечно переснимать документ, когда причина находится на сервере, а не в изображении.

Собственный фильтр обязан возвращать одинаковый результат для одинакового входа, насколько это возможно. Если порог плавает из-за нагрузки или случайной выборки, пользователь получает противоречивые команды. Для отладки сохраняют не персональные изображения в открытом виде, а код причины, измеренные показатели и версию конфигурации проверки. Тестовый набор с разрешёнными образцами помогает оценить ложные отклонения до выпуска.

Работа Direct API с видеопотоком

AnalyzerRunner получает кадры через analyzeStreamImage, когда кадры поступают с камеры или заранее записанный видеопоток. Необязательно отправлять каждый кадр с максимальной частотой. Если анализ одного изображения занимает дольше интервала камеры, очередь начнёт расти и обратная связь устареет: пользователь уже изменил положение, а на экране отображается оценка старого кадра. Обычно оставляют один кадр в обработке и заменяют ожидающий наиболее свежим.

FrameAnalysisResult сообщает состояние текущего кадра и позволяет построить собственные подсказки. Координаты и ориентацию необходимо согласовать с предпросмотром: буфер камеры может быть повёрнут, зеркален или обрезан иначе, чем видимая поверхность. Ошибка преобразования приводит к тому, что рамка рисуется не вокруг документа, хотя анализ корректен. Тестируйте портрет, альбомную ориентацию, поворот устройства во время сессии и разные соотношения сторон экрана.

При CaptureState.DocumentCaptured итог доступен через AnalyzerRunner.result. Вызов detachResult фиксирует результат и сразу возвращает анализатор к исходному состоянию, исключая изменение объекта последующими кадрами. Это удобно, если камера продолжает отдавать изображения ещё несколько миллисекунд после решения закрыть экран. Без отделения гонка может заменить принятый кадр или начать следующую сторону до того, как интерфейс завершил анимацию.

После окончания работы вызывают terminate для освобождения памяти обработки. Перед новым документом выполняют reset, если анализатор не был автоматически возвращён в исходное состояние. Владелец сессии должен гарантировать, что кадры не приходят после terminate. Для этого сначала останавливают подписку камеры или помечают поток закрытым, затем ждут завершения активного анализа и освобождают анализатор. Простой вызов terminate из произвольного потока при продолжающейся подаче кадров создаёт трудно воспроизводимые ошибки.

Анализ одной или нескольких готовых фотографий

Для фиксированного набора изображений используется analyzeImage. Этот путь полезен, когда фотография уже получена собственной камерой, импортирована из защищённого хранилища или пришла от другого устройства. Если на каждую сторону имеется один кадр, включают CaptureStrategy.SingleFrame, иначе анализатор будет ожидать последовательность, предназначенную для потокового режима. Изображение должно сохранять достаточное разрешение; миниатюра из галереи вместо оригинала часто приводит к неподходящим настройкам.

Перед передачей файла проверяют ориентацию EXIF. Некоторые загрузчики декодируют пиксели без применения поворота, и документ поступает боком, хотя системная галерея показывает его правильно. Также следует избегать повторного JPEG-сжатия с низким качеством: мелкий текст и гильошные линии разрушаются блочными артефактами, которые нельзя восстановить перспективной коррекцией. Надёжный путь — декодировать оригинал с учётом ориентации и только затем масштабировать, если это действительно требуется по памяти.

Для двух сторон сохраняют явный порядок. Если пользователь выбирает файлы из галереи, подписи лицевая и оборотная должны быть видимы до запуска анализа, иначе поменянные местами изображения могут пройти геометрическую проверку, но нарушить последующий конвейер. При известном классе документа настройка enforcedDocumentGroup может ограничить ожидаемую группу и уменьшить неоднозначность; использовать её следует только тогда, когда тип действительно выбран ранее.

Пакетная обработка множества заявок требует последовательного доступа к singleton-анализатору. Создайте очередь документов, а не очередь отдельных сторон: обе стороны одной заявки должны пройти подряд в одном состоянии. Ошибка одной фотографии не должна блокировать остальные элементы навсегда; сохраняйте код отказа, очищайте состояние и переходите к следующему заданию. Одновременно ограничьте число декодированных изображений в памяти, особенно на старых устройствах.

Поддерживаемые документы и границы задачи

Сценарий ориентирован на удостоверения личности и умеет различать одностороннюю и двухстороннюю структуру. Примеры из документации — паспорт и водительское удостоверение. Это не означает универсальную классификацию любых бумажных листов. Квитанция, договор A4, книга или пачка страниц имеют другую геометрию, правила многостраничности и обработку теней; для них нужен документ-сканер общего назначения.

Capture возвращает изображения, но не извлекает имя, дату рождения, номер, MRZ или штрихкод как часть базового результата. Для полей нужен BlinkID либо другой OCR/парсер. Аналогично компонент не проверяет подлинность, лицо владельца и совпадение селфи сам по себе. Выровненный кадр повышает шанс работы последующего инструмента, но бизнес-решение нельзя строить только на факте успешной съёмки.

Нет встроенного редактора PDF, объединения страниц, аннотаций, подписи, перестановки листов и печати. Когда задача пользователя — открыть существующий PDF, исправить текст или собрать сканы в документ, нужен редактор или общий сканер. Capture полезен раньше: он формирует качественный вход удостоверения для приложения. После получения сторон разработчик может самостоятельно создать PDF, но это будет функция его кода или другой библиотеки, а не готовая команда интерфейса.

Не следует применять автоматически исправленную карту как юридически эквивалентный оригинал без требований конкретного процесса. Перспективная коррекция меняет геометрию изображения, а дополнительное сжатие может затронуть детали. Если аудит требует необработанный кадр, сохраняйте original frame вместе с преобразованной копией и фиксируйте, какой файл использовался на каждом этапе. Если хранение оригинала запрещено политикой минимизации данных, это решение также должно быть явным.

Типовые сценарии внедрения

Регистрация клиента в финансовом приложении

В анкете камера открывается после выбора типа удостоверения и объяснения цели обработки. Capture помогает получить стороны без бликов и сильного наклона, затем выровненные изображения передаются распознавателю. Поля показываются человеку для подтверждения, а не заполняются на основании самого факта захвата. Если фильтр BlinkID отклоняет сторону, пользователь остаётся в камере и повторяет только её. Отмена возвращает к анкете с сохранёнными неперсональными полями, но без ложного сообщения о системной ошибке.

Заселение в гостиницу или выдача автомобиля

Сотрудник или клиент снимает удостоверение в условиях стойки, где потолочные лампы часто отражаются в пластике. Предупреждение о блике и фонарь помогают быстрее найти угол. Для общего устройства следует очищать изображения и состояние между посетителями, блокировать доступ к галерее результатов и не оставлять original frame в кеше. Если камера закреплена, заранее тестируют дистанцию, фокус и минимальный DPI на наиболее маленьком документе.

Предварительная проверка загрузки

Приложение может использовать Capture как барьер качества перед отправкой в удалённый KYC-процесс. Это снижает число файлов, которые сервер отклонит из-за размытия или обрезанных краёв. Однако сообщение клиенту должно различать локальную проблему кадра и серверный отказ по данным. Хорошее изображение не гарантирует, что документ поддерживается, действителен или принадлежит человеку. Логику повторной съёмки ограничивают, чтобы не заставлять пользователя бесконечно исправлять кадр при другой причине.

Оцифровка документов внутри защищённого процесса

Внутреннее приложение может сохранить исправленную сторону в карточке клиента и оригинальный кадр в закрытом аудите. Перед этим определяют сроки хранения, шифрование, доступ и способ удаления. Если конечной системой является PDF-хранилище, изображения передают генератору PDF после захвата, задавая размер страницы и сжатие там. Не нужно ожидать от Capture многостраничного контейнера: разделение обязанностей упрощает контроль качества и позволяет независимо менять формат хранилища.

Ошибки лицензии и сетевой активации

Первое, что проверяют при ошибке лицензии на Android, — фактический application ID установленной сборки. Он может отличаться от namespace и от значения, которое разработчик видит в основном build.gradle, из-за productFlavor или applicationIdSuffix. Затем проверяют имя и путь файла в assets, регистр символов и вызов CaptureSDK.setLicenseFile до инициализации. На iOS сопоставляют Bundle ID, членство файла в target, Copy Bundle Resources и момент вызова setLicenseKey или setLicenseResource.

Некоторые ключи требуют онлайн-активации. Если она не состоялась, Android возвращает ERROR_LICENCE_CHECK, а интерфейс локализации предусматривает сообщения о проверке интернета и сетевой коммуникации. Не следует показывать пользователю секретные сведения ключа или полный ответ сервера. Достаточно предложить проверить связь и повторить; служебный журнал содержит код, среду, время и идентификатор сборки. При постоянной ошибке команда проверяет разрешение сети, прокси, TLS-инспекцию и срок ключа.

Ключ нельзя хранить в открытом репозитории, печатать в аналитике или вкладывать в публичный пример. Файл внутри приложения всё равно является распространяемым ресурсом, поэтому его защищённость определяется лицензионной моделью и привязкой к идентификатору, а не секретностью как пароля. Для CI используют защищённые переменные или закрытое хранилище артефактов, а сборка проверяет наличие нужного ключа для выбранной среды.

Обработка ошибки должна завершать сессию чисто. Камеру закрывают, временные кадры освобождают, кнопка запуска снова становится доступной. Автоматический бесконечный перезапуск создаёт цикл, особенно при отсутствии сети. Для тестов предусмотрите недействительный, истёкший и выпущенный для другой идентичности ключ, а также первый запуск без подключения. Эти случаи должны приводить к контролируемому состоянию формы, а не к падению.

Проблемы камеры и низкого разрешения

Если документ не принимается ни при каком положении, сначала выводят фактическое разрешение preview. Требование 1080p относится к потоку анализа; выбор маленького ImageAnalysis в CameraX или низкого preset на iOS нельзя компенсировать высокой фотографией, которая снимается другой веткой камеры. Затем проверяют, не уменьшается ли буфер при преобразовании в bitmap и не передаётся ли в Direct API миниатюра. Только после этого меняют пороги DPI.

Автофокус должен работать на дистанции, где карта почти заполняет кадр. На телефонах с несколькими объективами система может переключиться на широкоугольный модуль с иной минимальной дистанцией. Если собственная камера выбирает объектив вручную, тестируйте читаемость текста, а не только отсутствие размытия на предпросмотре. Фиксация экспозиции слишком рано также мешает: белая карта на тёмном столе меняет среднюю яркость и требует повторного измерения.

Чёрный экран обычно связан с разрешением камеры, жизненным циклом поверхности или конкурирующей сессией, а не с анализом документа. Готовый UX берёт управление камерой на себя, поэтому перед запуском нужно закрыть собственный preview. В Direct API, наоборот, приложение полностью отвечает за разрешение и подачу кадров. На Android проверьте runtime permission и состояние Activity; на iOS — статус AVAuthorizationStatus и обработку возвращения из системных настроек.

При нестабильном поведении на конкретной модели полезный отчёт включает точное название устройства, версию системы, архитектуру, разрешение входа, активные политики и образец проблемы высокого разрешения, переданный по безопасному каналу. Скриншот видоискателя без исходного кадра часто недостаточен: он уже масштабирован экраном и не показывает реальные пиксели анализатора. Персональные сведения на диагностическом документе должны быть тестовыми или надёжно обезличенными.

Сбой нативной загрузки и конфликты сборки

UnsatisfiedLinkError на Android указывает, что загрузчик не нашёл подходящую нативную библиотеку или не смог разрешить её зависимость. Сравните ABI устройства с папками внутри APK/AAB, проверьте abiFilters и исключения packagingOptions. Если другая библиотека поставляет только одну архитектуру, Gradle может собрать пакет, который частично выглядит корректным, но падает при выборе несовместимого набора. Исправление состоит в пересечении поддерживаемых ABI, а не в копировании случайного .so из другого выпуска.

Дубликаты классов или ресурсов возникают при одновременном подключении capture-ux и другой транзитивной копии core несовместимого номера. Просмотрите dependencyInsight, выровняйте версии и удалите ручные AAR, если библиотека уже приходит из Maven. Принудительное исключение core без понимания зависимости может перенести ошибку из сборки в рантайм. После изменения зависимостей воспроизведите чистую сборку в CI, а не только на машине с наполненным кешем.

На iOS типичная ошибка dyld означает, что XCFramework не встроен или не подписан. В General цель должна содержать нужные фреймворки с Embed & Sign, а собранный пакет — соответствующие slices. Дублирование через SPM и ручное добавление создаёт конфликт символов. Если приложение и расширение используют общий код, не встраивайте динамический фреймворк в оба места без корректной схемы; проверьте итоговый bundle командой анализа зависимостей и запуск на физическом устройстве.

libc++.tbd и libz.tbd должны присутствовать среди связанных библиотек при ручной iOS-интеграции. Ошибка линковщика с C++ или zlib-символами не исправляется изменением Swift-кода. Сначала сопоставляют инструкцию интеграции, затем очищают DerivedData только для исключения старого артефакта. В отчёте сохраняют полную строку undefined symbol и архитектуру, потому что одинаковое пользовательское сообщение может скрывать разные проблемы.

Производительность, память и размер приложения

Анализ видеопотока сочетает декодирование кадров, нативную обработку и отрисовку интерфейса. Самая частая ошибка Direct API — очередь всех кадров. Камера выдаёт новый буфер быстрее, чем старый анализируется, память растёт, а подсказки запаздывают. Используйте backpressure: обрабатывается один кадр, а из накопившихся остаётся самый свежий. Профилируйте не средний FPS камеры, а задержку от физического движения документа до смены инструкции.

Изображения результата нужно освобождать после записи или передачи. Декодированная RGBA-картинка 1920×1080 занимает около восьми мегабайт без учёта копий; две стороны, оригиналы и преобразованные версии быстро увеличивают пик памяти. На Android следите за Bitmap и ByteBuffer, на iOS — за UIImage/CGImage и autoreleasepool в цикле. Не помещайте полноразмерные кадры в объект состояния интерфейса, который переживает весь процесс регистрации.

Для Android официальная оценка добавки с зависимостями составляет примерно 2,6 МБ APK на поддерживаемую ABI, а размер загрузки — около 2,4–2,5 МБ. App Bundle помогает доставлять только нужную архитектуру. На iOS приводится ориентир около 2,1 МБ в сжатой загрузке и 3,1 МБ после установки. Эти числа не включают ваш OCR, фильтр BlinkID, аналитику и изображения интерфейса, поэтому измеряйте итоговый пакет приложения после включения всех компонентов.

Холодный запуск камеры отделяйте от времени автоматического захвата. Инициализация лицензии, загрузка нативных библиотек и создание сессии могут занимать заметную долю первой попытки. Предварительная инициализация допустима после получения согласия и без открытия камеры, но не должна удерживать тяжёлые ресурсы весь сеанс приложения. Метрики полезно разделить на launch-to-preview, preview-to-first-guidance, guidance-to-capture и filter-duration.

Безопасность и работа с персональными изображениями

Удостоверение содержит персональные данные, поэтому отладочные удобства должны быть ограничены с первого прототипа. Не записывайте кадры в общую галерею, не выводите байты в консоль и не прикладывайте реальные документы к публичным баг-трекерам. Временные файлы размещают в каталоге приложения, шифруют по требованиям проекта и удаляют после подтверждённой обработки. Экран результата защищают от случайного повторного открытия другим пользователем общего устройства.

Original frame может содержать лицо человека рядом с картой, стол, экран или документы на фоне. Если дальнейшему процессу нужна только выровненная область, оригинал следует удалить как можно раньше. Если он нужен для аудита, срок и доступ задают отдельно от основной копии. Принцип минимизации важен и для аналитики: вместо изображения сохраняют причину отклонения, модель устройства, разрешение и длительность, когда этого достаточно для улучшения UX.

Лицензионная сеть и передача документов — разные потоки. Наличие сетевой проверки ключа не означает, что приложение автоматически загружает захваченные изображения; способ отправки результата определяет интеграция. И наоборот, даже при успешной локальной съёмке ваш код может передать данные на сервер. Пользовательское уведомление о конфиденциальности должно описывать фактическую архитектуру приложения, а не общие свойства библиотеки.

Скриншоты в системном переключателе задач могут показать документ после захвата. На чувствительных экранах применяют средства платформы для скрытия содержимого в фоне или защищённого окна, учитывая влияние на доступность и поддержку. Также обрабатывают прерывания звонком и блокировку: камера останавливается, временный кадр не остаётся на экране, а возвращение либо продолжает безопасно, либо начинает сторону заново.

Тестирование перед выпуском

Матрица устройств должна включать как минимум старую ARMv7-модель, современный ARM64-телефон, устройство с несколькими камерами и экран с небольшим разрешением. На iOS проверяют минимально поддерживаемую систему и несколько размеров дисплея. Эмулятор подходит для сборки и части навигации, но не оценивает реальный автофокус, экспозицию и блики. Основные критерии качества измеряют на физической камере.

• Матовые и глянцевые карты при дневном, тёплом и слабом освещении.
• Паспортная страница, односторонний документ и карта с обязательным оборотом.
• Пальцы на краях, частично закрытые поля, обрезанный угол и фон похожего цвета.
• Сильный наклон, поворот на 90 градусов, дрожание и быстрое движение.
• Отмена на каждом этапе, сворачивание приложения и отзыв разрешения камеры.
• Недействительная лицензия, отсутствие сети при активации и неподходящий application ID.
• Низкое разрешение входа, импорт миниатюры и одиночный кадр в потоковой стратегии.

Для каждого случая фиксируют ожидаемую подсказку и допустимый выход. Тест не удалось недостаточен: важно, объяснил ли интерфейс причину и сохранил ли уже принятую сторону. При регрессии темы сравнивают видимость элементов на светлом и тёмном фоне, крупный шрифт, локализации с длинными строками и VoiceOver или TalkBack. Кнопка выхода и помощь должны иметь достаточную область касания независимо от рисунка.

Автоматизированные тесты покрывают маршрутизацию статусов, модель сессии и очистку файлов. Камерную часть проверяют инструментальными сценариями и разрешённым набором тестовых документов. Не используйте реальные удостоверения сотрудников как постоянные fixture. Для Direct API можно хранить обезличенные синтетические изображения, но они должны оставаться фотографиями с реальными оптическими дефектами; идеально отрисованный прямоугольник не воспроизводит блики и автофокус.

Наблюдаемость и метрики качества

Полезные метрики не содержат изображений и текста документа. Сохраняют время открытия камеры, время до принятия каждой стороны, число смен подсказок, наиболее частую причину задержки, количество отклонений фильтром, отмену, код технической ошибки и модель устройства. Эти данные показывают, мешает ли строгая политика конкретной аудитории. Например, рост команды приблизьте на одной модели может указывать на неверно выбранное разрешение preview, а не на поведение людей.

События строят вокруг одной сессии с уникальным неперсональным идентификатором. Запуск, показ первого кадра, принятие лицевой стороны, запрос переворота, принятие оборотной, фильтрация и завершение должны связываться, но не содержать номер документа. Для повторной попытки сохраняют номер попытки и причину. Аналитика, которая считает только успешный финал, не объяснит, почему пользователи уходят.

Порог тревоги задают отдельно для функционального сбоя и ухудшения качества. Массовый ERROR_LICENCE_CHECK требует оперативной реакции, а плавный рост времени из-за сезонного освещения — продуктового анализа. После изменения политики DPI или темы сравнивают контрольную и новую группу на реальных показателях OCR либо ручной приемки. Снижение времени захвата не считается улучшением, если сервер чаще просит повторную загрузку.

При обращении в поддержку можно сформировать диагностический пакет без персональных кадров: версия приложения, платформа, модель, ABI, размер preview, активные параметры, последовательность статусов и обезличенный лог. Если нужен пример изображения, используют тестовый документ высокого разрешения и передают его по согласованному защищённому каналу. Такая дисциплина ускоряет поиск ошибки и не превращает диагностику в утечку.

Сравнение Microblink Document Capture с аналогами

Программа	Лучше подходит для	Главное ограничение
Microblink Document Capture	Автоматического захвата лицевой и оборотной сторон удостоверений с подсказками по бликам, резкости, освещению и наклону	Не формирует PDF и не извлекает поля без дополнительного распознавателя
Scanbot Document Scanner SDK	Сканирования обычных документов, многостраничных потоков, фильтров и экспорта в JPG, PDF или TIFF	Общий документный сценарий не так специализирован на структуре удостоверений
Genius Scan SDK	Встраивания общего сканера бумаги с обнаружением границ, обработкой изображения и OCR в разных оболочках	Для проверки извлекаемости удостоверения потребуется отдельная логика
Docutain SDK	Полного конвейера документ-сканирования с OCR, извлечением данных и PDF-функциями	Более широкий набор функций избыточен для одной задачи захвата ID
Dynamsoft Document Normalizer	Программного поиска четырёхугольников, обрезки, выравнивания перспективы и настройки улучшения изображения	Пользовательский поток сторон и подсказки приходится проектировать отдельно

Выбор определяется не общей мощностью, а местом в процессе. Для мобильной формы, где важно провести человека через лицевую и оборотную стороны удостоверения и не принять блик, Microblink даёт наиболее прямой сценарий. Scanbot удобнее, когда результатом должны стать многостраничный PDF или TIFF и нужны фильтры бумаги. Genius Scan SDK и Docutain подходят для широкого документооборота с OCR, а Dynamsoft — для команды, которой нужен низкоуровневый контроль нормализации и собственный интерфейс. PDF Commander решает последующее редактирование готовых PDF на компьютере, поэтому не является прямой заменой камере захвата.

Практический план внедрения

1. Определите, какие удостоверения и стороны принимает бизнес-процесс, и нужен ли исходный кадр.
2. Выберите готовый UX либо Direct API; не начинайте с собственной камеры без необходимости.
3. Получите ключи для точных идентификаторов debug, staging и production.
4. Подключите зависимости одним способом и проверьте ABI, iOS embedding и связанные библиотеки.
5. Настройте минимальный DPI и политики на тестовом наборе, а не по максимальной строгости.
6. Согласуйте тексты подсказок, вводное обучение, тему и доступность с дизайном приложения.
7. Реализуйте обработку всех статусов, однократное завершение сессии и очистку памяти.
8. При необходимости добавьте CaptureFilter и отдельно измерьте его задержку и причины отказа.
9. Определите хранение, загрузку, шифрование и удаление обеих разновидностей изображения.
10. Проведите матрицу реальных устройств, плохого света, бликов, отмен и лицензионных ошибок.
11. Добавьте обезличенные метрики времени и качества, затем откорректируйте пороги по результатам.

На первом прототипе полезно оставить стандартный внешний вид и добиться стабильного результата. Одновременная замена темы, локализации, камеры и политик делает причину ошибки неясной. После успешной съёмки тестового паспорта и двухсторонней карты меняют один слой за раз: сначала тексты и цвета, затем дополнительные проверки, затем оптимизацию производительности. Для Direct API сначала воспроизводят sample-последовательность, и только потом подключают сложную архитектуру камеры проекта.

Критерий готовности включает больше, чем один удачный кадр разработчика. Пользователь без инструкции должен понять, какой стороной повернуть карту, исправить блик, выйти без потери анкеты и получить объяснимое сообщение при отсутствии сети. Приложение обязано освобождать камеру и память, не смешивать результаты параллельных заявок и не хранить лишний фон. Только после этих проверок автоматический захват действительно сокращает ручную обработку.

Частые вопросы по рабочему процессу

Можно ли получить PDF сразу после съёмки?

Нет, базовый результат — изображения сторон. Для PDF требуется генератор документа в приложении или отдельный редактор. Такой конвейер должен сам выбрать размер страниц, порядок сторон, сжатие и метаданные. Если PDF нужен лишь для хранения, обычно используют выровненные изображения; если аудит требует исходную сцену, original frame сохраняют отдельно, а не подменяют им аккуратную страницу.

Почему карта выглядит ровно, но анализатор просит приблизить её?

Геометрическая правильность не означает достаточную детализацию. Документ может быть полностью виден и параллелен камере, но занимать слишком мало пикселей для минимального DPI. Проверьте размер preview и фактическую область карты. Не повышайте цифровой масштаб после съёмки: он увеличит пиксели без новых деталей. Лучше физически приблизить камеру в пределах фокусировки или выбрать поток большего разрешения.

Нужно ли добавлять BlinkID?

Для получения выровненных изображений — нет. BlinkID нужен, когда требуется извлечение полей или готовый фильтр, который принимает только изображения, пригодные для такого извлечения. В этом случае подключается дополнительная зависимость и лицензия. Решение следует принимать по бизнес-задаче: бессмысленно увеличивать сборку и время обработки, если изображения проверяет другой сервис.

Почему после первой стороны снова открывается камера?

Для двухсторонней карты это ожидаемый переход к обороту. Интерфейс должен показать анимацию и явную команду перевернуть документ. Если тот же этап повторяется после принятия оборота, проверьте порядок сторон, результат фильтра и сброс анализатора. CaptureFilter может отклонить кадр и попросить переснять текущую сторону, не закрывая камеру; приложение должно отличать это от начала нового документа.

Можно ли обрабатывать два документа одновременно?

Direct API использует singleton AnalyzerRunner и рассчитан на один документ за раз. Параллельные заявки ставят в очередь на уровне приложения. Готовый экран также лучше защищать от повторного запуска кнопкой, пока активна текущая сессия. После завершения фиксируют результат, сбрасывают или завершают анализатор и только затем открывают следующий документ.

Что делать, если подсказки меняются слишком быстро?

В собственном UX введите сглаживание состояния: показывайте новую команду после нескольких согласованных кадров или минимального времени, не задерживая критический успех. Во встроенном UX управляйте условиями через корректные политики и камеру, а не поверхностно скрывайте сообщения. Частая смена ближе—дальше также указывает на нестабильный масштаб preview или границу порога DPI.

Итоговая схема надёжной сессии

Надёжная сессия начинается с проверенной лицензии и разрешения камеры, затем создаёт ровно один владелец состояния. Пользователь видит краткую подготовку, открывает видоискатель и получает одну конкретную команду за раз. Анализатор принимает сторону только при достаточном качестве, дополнительный фильтр при необходимости подтверждает пригодность, а двухсторонний документ продолжает ту же сессию после понятного переворота. Успех, отмена, лицензионная ошибка и неподходящие настройки проходят разными ветками.

После успеха приложение отделяет итог от анализатора, сопоставляет стороны, записывает только нужные изображения и освобождает память камеры. Выровненная копия идёт в OCR, проверку или PDF-конвейер, исходный кадр хранится лишь при обоснованной цели. Метрики фиксируют длительность и причины трудностей без текста документа. Такой порядок превращает автоматическую камеру из визуального эффекта в управляемый канал качественных данных.

Главная практическая ценность Microblink Document Capture проявляется до распознавания: пользователь получает понятную коррекцию положения в момент съёмки, а следующая система — прямоугольное, достаточно детальное изображение вместо случайной фотографии. Результат зависит от честной настройки DPI и политик, реального разрешения preview, корректного жизненного цикла и ясного разделения между захватом, извлечением данных и формированием PDF. При таком разделении ошибки легче диагностировать, персональные данные проще контролировать, а повторная съёмка касается только действительно неудачной стороны.