Gini Capture SDK помогает встроить в мобильное приложение понятный сценарий съёмки счетов и платёжных документов: пользователь наводит камеру, получает подсказки по качеству кадра, проверяет и поворачивает страницу, добавляет остальные листы, импортирует готовый PDF или изображение и передаёт подготовленный документ на анализ через Gini API. Разработчику доступны готовые экраны, отдельные компоненты камеры и проверки, настройка текстов и цветов, обработка разрешений, многостраничный режим, распознавание платёжных QR-кодов и обратные вызовы для загрузки и результата.

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

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

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

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

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

Готовая навигация и отдельные компоненты

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

Component API используется, когда навигация уже определена приложением. На Android в собственные Activity помещают фрагменты камеры, проверки и других этапов; на iOS отдельные контроллеры можно показать модально, встроить в контейнер или добавить в стек навигации. Команда сама рисует верхнюю панель, решает, где находится кнопка закрытия, и связывает переходы. Такой подход требует явного управления состоянием документа: нужно хранить порядок страниц, отличать отмену от ошибки, восстанавливать интерфейс после поворота или выгрузки процесса и не запускать две операции анализа одновременно.

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

Экран камеры и элементы управления

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

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

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

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

QR-коды в платёжном документе

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

В поддерживаемый набор входят европейские и национальные платёжные форматы, в том числе SPC, SPD, Pay by Square, UPNQR и HUB3. Наличие детектора не означает, что любой квадратный код является платёжным: рекламная ссылка, код отслеживания посылки или повреждённая строка должны приводить к понятному отказу, а не к заполнению случайных реквизитов. После чтения кода приложение обязано показать пользователю сумму, получателя и счёт до подтверждения платежа. Если в документе и QR расходятся данные, приоритет нельзя выбирать незаметно; конфликт следует вынести на экран проверки.

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

Разрешение на камеру и доступ к файлам

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

На Android разрешения и выбор документа — разные механизмы. Камера требует соответствующего разрешения, а импорт через системный выборщик обычно выдаёт приложению доступ к конкретному URI. Нельзя предполагать, что путь к выбранному файлу доступен как обычная строка файловой системы. Надёжная реализация читает поток через ContentResolver, учитывает временный характер разрешения и копирует данные в контролируемое хранилище только при необходимости. Если поставщик файлов возвращает облачный объект, чтение может занять время или завершиться сетевой ошибкой, даже когда сам SDK уже открыт.

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

Проверка качества после съёмки

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

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

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

Подсказки по фотографии

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

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

Многостраничный документ

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

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

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

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

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

Импорт изображений и PDF

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

Справка перечисляет поддерживаемые типы: изображения JPEG, PNG и GIF, а также PDF с ограничением по числу страниц в показанной конфигурации. Сгенерированные компьютером счета и платёжные документы предпочтительнее фотографий экрана. Рукописный текст и снимки монитора в справке отмечены как неподходящие для анализа. Эти ограничения следует показывать до открытия выборщика, иначе пользователь тратит время на поиск файла, который будет отвергнут после импорта. Серверные правила конкретного проекта могут быть строже, поэтому клиентская проверка должна повторять их.

Проверка расширения недостаточна. Файл с именем invoice.pdf может содержать другой формат, быть повреждённым или защищённым паролем. Надёжный поток определяет MIME-тип, пробует открыть структуру и проверяет размер до загрузки. Для изображения полезно прочитать размеры и ориентацию EXIF, а затем привести представление к ожидаемому направлению. Для PDF проверяют число страниц и возможность рендеринга первой страницы. Если документ зашифрован, приложение должно сообщить, что пароль необходимо снять в исходной программе; поле ввода пароля не относится к стандартному потоку Gini Capture SDK.

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

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

Экран анализа и связь с Gini API

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

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

На iOS готовый вариант с сетью принимает клиент и делегат результата, а вариант только UI возвращает приложение к собственной реализации анализа. В Component API экран анализа можно использовать отдельно. Он показывает советы при обработке изображения и сведения о документе при PDF. Независимо от варианта, извлечённые поля следует отображать на отдельном экране приложения, где пользователь сможет проверить сумму, получателя, IBAN, дату и назначение. SDK захвата готовит документ и сопровождает анализ, но бизнес-решение о подтверждении платежа остаётся за приложением.

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

Результат без извлечённых данных

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

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

Справка внутри потока

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

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

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

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

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

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

На iOS конфигурация применяется до создания контроллеров. При Component API её устанавливают централизованно, чтобы отдельные экраны использовали одинаковые ресурсы. Изменение конфигурации посреди активного потока может привести к разным цветам или текстам на соседних экранах, поэтому параметры фиксируют на время одного документа. Для A/B-теста выбирают вариант до открытия камеры и записывают его вместе с событиями, не меняя после первой страницы.

Доступность интерфейса

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

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

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

Android-библиотека распространяется как AAR через Maven Central и подключается зависимостью Gradle. Основной артефакт содержит экраны и компоненты захвата, а сетевую реализацию можно добавить отдельно. После синхронизации проверяют конфликты AndroidX, Material Components, CameraX, Kotlin и других транзитивных зависимостей. Принудительное понижение одной из них ради старого модуля приложения может привести к ошибке во время запуска, хотя сборка завершилась. Надёжнее выровнять зависимости на совместимые выпуски и прогнать полный поток на минимально поддерживаемом устройстве.

Приложению требуется увеличить доступную heap-память, поскольку изображения обрабатываются в памяти. Это не разрешение хранить неограниченное число полноразмерных кадров. Многостраничный сценарий должен освобождать временные битмапы, использовать уменьшенные миниатюры для ленты и не держать одновременно исходник, повёрнутую копию и превью для каждого листа. При `OutOfMemoryError` сначала изучают размеры изображений и жизненный цикл экранов, а не только увеличивают лимит памяти. Утечка Activity через обратный вызов способна удерживать весь набор страниц после закрытия потока.

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

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

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

Проверка требований устройства

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

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

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

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

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

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

Открытие документа из другого приложения требует обработки входного URL и безопасного копирования файла. Нельзя читать большой PDF синхронно на главном потоке: почтовый клиент может передать облачный объект, а система даст приложению ограниченное время. Сначала проверяют доступ, затем копируют во временный каталог, показывают индикатор и только после успешного завершения создают объект документа для SDK. Если пользователь открыл второй файл, пока первый анализируется, приложение должно выбрать — поставить задачу в очередь или отклонить новый вход, но не смешивать страницы.

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

Форматы документов и подготовка данных

Основные входы — фотография, существующее изображение и PDF. Для фотографии важны разрешение, ориентация и отсутствие сильного сжатия. Для импортированного изображения приложение получает уже готовые пиксели и не может попросить пользователя изменить освещение, поэтому экран проверки особенно важен. Для PDF не требуется превращать каждую страницу в JPEG перед передачей, если выбранный API принимает PDF напрямую. Лишняя растеризация увеличивает размер, ухудшает мелкий текст и удаляет текстовый слой.

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

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

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

Сетевой поток, повторы и отмена

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

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

Тайм-ауты разделяют на соединение, отправку и ожидание анализа. Большой PDF по медленной сети требует больше времени на передачу, чем небольшая фотография. Единый короткий тайм-аут создаёт ложные ошибки; бесконечный — оставляет пользователя без решения. Экран может показывать прогресс загрузки, затем отдельное состояние анализа. Если серверный анализ продолжается дольше обычного, приложение сохраняет идентификатор документа и может опросить результат после восстановления, не загружая файл заново.

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

Конфиденциальность и безопасное хранение

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

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

Аналитика и отчёты об ошибках должны исключать содержимое. Нельзя прикреплять снимок к автоматическому crash-отчёту или включать распознанные поля в breadcrumb. Для обращения в поддержку пользователь может отдельно согласиться отправить диагностический пакет; в нём перечисляют технические параметры и, только при необходимости, документ по защищённому каналу. Такое согласие не следует объединять с основным разрешением камеры.

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

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

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

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

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

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

Типовые рабочие процессы

Оплата счёта в банковском приложении

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

Для такого процесса особенно важна граница ответственности. Gini Capture SDK организует захват и подготовку документа, API возвращает извлечения, а банковское приложение применяет правила платежа, проверяет лимиты, санкционные списки и подтверждение. Нельзя считать успешный анализ разрешением на перевод. Если QR и печатный текст расходятся, приложение должно показать конфликт. Если сумма отсутствует, поле остаётся пустым; автоматическая подстановка последней суммы опасна.

Передача счёта в страховой или бухгалтерский сервис

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

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

Съёмка документа в службе поддержки

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

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

Устранение ошибок Gini Capture SDK

Камера открылась, но предпросмотр чёрный

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

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

Изучают размеры исходных кадров и число одновременно живых Bitmap. Лента должна хранить миниатюры, а не полноразмерные копии. После поворота страницы старый буфер освобождают. Закрытый экран не должен оставаться в обратном вызове сети. На Android включают требуемый large heap, но не используют его как замену управлению памятью. Пиковый тест выполняют с максимальным числом страниц, импортом крупного PDF и несколькими повторными съёмками.

Файл виден в выборе, но не импортируется

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

Анализ не завершается

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

QR-код определяется как недействительный

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

Страницы отправляются в неверном порядке

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

После отказа разрешение больше не запрашивается

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

Сравнение Gini Capture SDK с аналогами

Программа	Лучше подходит для	Главное ограничение
Gini Capture SDK	Съёмки счетов и платёжных документов с подготовкой к Gini API	Извлечение реквизитов связано с инфраструктурой Gini
Scanbot Document Scanner SDK	Универсального офлайн-сканирования, автозахвата, фильтров и экспорта JPG, PDF или TIFF	Платёжная семантика и серверный процесс настраиваются отдельно
Google ML Kit Document Scanner	Быстрого добавления готового сканера PDF и JPEG в Android-приложение	Только Android и зависимость от Google Play services
Dynamsoft Document Normalizer	Точного поиска границ, выравнивания перспективы и настройки обработки изображений	Готовый процесс счетов и извлечение реквизитов нужно строить отдельно
Microblink Capture SDK	Автоматического получения выровненных изображений удостоверяющих документов	Ориентирован прежде всего на документы личности
PDF Commander	Ручного редактирования, сборки и проверки уже полученных PDF на компьютере	Не встраивается в мобильное приложение как камера

Gini Capture SDK логичнее выбирать, когда центральная задача — провести пользователя от камеры или импортированного счёта к анализу и проверке платёжных реквизитов. Scanbot лучше подходит для универсального офлайн-сканера с автоматическим захватом, фильтрами и несколькими форматами экспорта. ML Kit удобен для Android-проекта, которому нужен компактный готовый поток без собственной камеры, но он загружает модели и интерфейс через Google Play services. Dynamsoft полезен, когда команда строит собственный UX и особенно важны геометрическая нормализация и параметры изображения. Microblink Capture SDK уместнее для удостоверений личности. PDF Commander дополняет мобильный процесс на этапе ручной обработки готового PDF, но не заменяет библиотеку захвата.

Практические ограничения

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

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

Анализ требует сети и доступа к выбранному Gini API, если приложение хочет получить извлечённые поля. Сам UI захвата можно связать с собственной загрузкой, однако готовые платёжные результаты не появляются без серверной обработки. Это влияет на офлайн-сценарий: пользователь может подготовить кадр, но приложение должно явно сообщить, будет ли документ поставлен в очередь или требуется подключение сейчас. Скрытая очередь без статуса создаёт риск повторной отправки.

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

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

Регрессионная проверка после изменения зависимостей

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

На Android отдельно контролируют дерево зависимостей, потому что приложение и SDK могут требовать разные выпуски CameraX, Kotlin, AndroidX или сетевого клиента. Принудительное выравнивание номеров без проверки способно устранить ошибку сборки и одновременно изменить поведение камеры. Надёжный процесс фиксирует разрешённые зависимости, запускает сборку с отчётом о конфликтах и затем проверяет предпросмотр на нескольких моделях устройств. При включённом уменьшении кода сохраняют классы, которые создаются через отражение или объявлены в манифесте, а релизную сборку тестируют отдельно от отладочной.

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

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

Рекомендации по внедрению

1. Сначала зафиксировать один основной сценарий: одиночный счёт, многостраничный документ или импорт PDF.
2. Собрать поток на Screen API и подключить тестовую загрузку, чтобы проверить полный жизненный цикл.
3. Настроить разрешения, тексты и аппаратную проверку до глубокой визуальной кастомизации.
4. Разделить события камеры, загрузки и анализа в журнале и аналитике без содержимого документа.
5. Проверить максимальное число страниц, крупные изображения и повторы на устройствах с небольшим объёмом памяти.
6. Добавить экран проверки извлечённых реквизитов и отправлять обратную связь только после решения пользователя.
7. Перейти на Component API только для тех экранов, где действительно требуется собственная навигация или UX.
8. Перед выпуском провести тесты разрешений, импорта из нескольких поставщиков, QR-кодов и нестабильной сети.

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

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

Ответы на практические вопросы

Можно ли использовать только камеру без Gini API?

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

Можно ли импортировать PDF вместо фотографии?

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

Как обрабатывать несколько страниц?

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

Что делать с низкой резкостью?

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

Почему после анализа нужно ещё проверять поля?

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

Как не потерять документ при повороте экрана или уходе в фон?

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

Итоговый рабочий подход

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

Разработчику важно удерживать границы между слоями. Компоненты камеры отвечают за получение документа, сетевой слой — за безопасную передачу, Gini API — за извлечение, а бизнес-экран — за проверку и подтверждение реквизитов. Когда эти этапы разделены в коде, журнале и интерфейсе, сбой можно локализовать, повтор выполняется без дубликатов, а отмена не оставляет скрытых операций. Такой поток подходит для банковских, страховых и бухгалтерских приложений, где качество изображения и понятное подтверждение важнее максимальной скорости первого нажатия.

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