На чем написано приложение сбербанка

Java SDK

Java-библиотека для серверных приложений на Java, упрощающая получение Access Token и UserInfo.

Подключение 

Установить в локальный maven-репозиторий артефакты:

Добавить в зависимости проекта SDK, прописав в pom.xml:

Использование 

Создать объект SberApiClient, указав свои значения client_id, client_secret (подробнее), шлюзы вызова API. Адреса для запроса access token перечислены здесь(), для получения пользовательских данных — здесь().

Если используется 2-х сторонний TLS, необходимо установить SSL-контекст, указав путь к выпущенному p12-сертификату:

Выполнить запрос на получение Access Token, Id Token, указав значения:

1. Адреса для возврата Auth Code;
2. Auth Code, полученного через фронтенд;
3. Nonce (который использовался при получении Auth Code);
4. Code Verifier (обязателен, если используется PKCE).

Пример

Объект AuthData содержит поля (в соответствии с параметрами ответа):

• accessToken — Сгенерированный Access token;
• tokenType — Тип запрашиваемого токена. Всегда передается значение «Bearer»;
• expiresIn — Время в секундах, в течение которого действует Access Token;
• scope — Список групп персональных данных, на получение которых выдан данный токен. В список так же по умолчанию включается название сервиса API;
• idToken — Набор атрибутов, необходимый для идентификации пользователя.

Используя полученный Access Token, выполнить запрос на получение пользовательских данных:

В классе UserInfoData описаны обязательные поля. При необходимости (для получения дополнительных полей) класс нужно расширить, например:

В этом случае необходимо передать класс при формировании запроса:

Для генерации nonce при запросе Auth Code можно использовать метод формирования 32-байтной случайной строки:

• ApiResponseException, ApiException — в случае получения ошибки от API (с детализацией ошибки см. здесь() и здесь();
• IncorrectNonceException — в случае несовпадения Nonce с тем, который использовался для получение Auth Code;
• SberApiClientException — в случае ошибок чтения сертификата;
• IncorrectAudException — в случае несовпадения полученного aud и client_id.

Логирование 

Если требуется вывести в лог детальные http-запросы/ответы к Sberbank ID, то указать в VM параметрах:

Платформа сервисов: как и зачем Сбер использует API

SberBusinessAPI — это технология прямой интеграции с банком, которая позволяет мгновенно обмениваться платёжными данными с интернет-банком, автоматически авторизовываться в сервисах экосистемы СберБизнес, а также предоставляет широкий спектр возможностей партнёрского взаимодействия с банком.

Как в банке изменили свой подход к API и к чему это привело?

Как всё начиналось?

SberBusinessAPI (application programming interface, интерфейс программирования приложений) известен большинству наших действующих клиентов как Fintech API. Это уникальное решение Сбера, которое было разработано и внедрено в банке и по-прежнему не имеет аналогов на отечественном рынке с точки зрения масштабов и количества методов.

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

Мы изучили подход и практики крупнейших финтех-компаний: Amazon, Google, Microsoft, Apple и др. — и пришли к выводу, что наше решение должно быть создано с нуля, без оглядки на предыдущие банковские решения. Начали с фокус-групп — провели серию интервью с разработчиками компаний – потенциальных клиентов нашего API. Вывод оказался очевиден: если разработчик видит знакомый ему подход, интеграция пройдёт быстрее и проще.

Поэтому для разработки API мы сформировали перечень принципов, на которых сегодня основывается SberBusinessAPI:

Никаких универсальных и тяжёлых форматов, которые учитывают малейшие нюансы.

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

Никаких проприетарных решений (от англ. proprietary, частное, патентованное), привязанных к определённой платформе. Все должно быть кроссплатформенным и не ограничивать партнёра в используемой инфраструктуре и среде разработки.

Никаких лишних деталей. Партнёрам не должно мешать то, что им не нужно: сложные структуры данных, механизмы компонентов банковской платформы, особенности работы наших legacy-систем. Всё это может благополучно укрыться «под капотом».

API должен подходить максимально широкому кругу потенциальных партнеров, вплоть до внедрения в умные холодильники (интернет вещей стремительно набирает обороты).

API нужно проектировать с помощью практик и способов, которые используются при создании визуальных интерфейсов. Для этого нужно выявить и проанализировать UX-схемы использования API.

Зачем нужен SberBusinessAPI?

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

Именно благодаря SberBusinessAPI пользователи нашего корпоративного интернет-банка СберБизнес имеют доступ не только к традиционным банковским продуктам, но и более чем к 40 нефинансовым сервисам для развития и ведения бизнеса.

В их числе — бухгалтерские сервисы, финансовая аналитика, CRM, сервисы для торговли и многие другие. Провайдерами этих услуг выступают партнёры и дочерние компании Сбера, сервисы которых полностью интегрированы в интернет-банк.

Сейчас SberBusinessAPI насчитывает 36 групп методов, которые закрывают ключевые потребности B2B-провайдеров, представителей сегментов крупного и среднего бизнеса. Благодаря этому решению нам удалось выстроить цифровую инфраструктуру, которая превратила наш корпоративный интернет-банкинг СберБизнес в настоящую платформу сервисов и услуг для бизнеса на любом этапе его развития.

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

Что внутри?

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

Внутри SberBusinessAPI мы используем такие проверенные решения, как Sbergile-методологию разработки, подход Easy Steps при документировании, аутентификацию на базе протокола OAUTH 2.0, REST-архитектуру поверх HTTP, формат JSON, платформу для тестирования с развёрнутым Swagger. Всё это лучшие практики для отдельно взятых ИТ-отраслей, например, на платформе для тестирования разработчик партнёра может смоделировать бизнес-процесс работы и получить результат без написания кода.

запросов в сутки обрабатывает

Что в итоге?

За два с половиной года SberBusinessAPI удалось стать хедлайнером на рынке отечественных банковских API. Сегодня наше решение обеспечивает основные сценарии взаимодействия юридических лиц и финтех-компаний с банком и обрабатывает свыше 5 млн запросов в сутки, каждый в среднем не более чем за 0,2 секунды.

Благодаря SberBusinessAPI банковские и небанковские продукты и услуги в СберБизнес объединены на одной платформе. Наши клиенты пользуются бесшовной авторизацией в партнёрских сервисах, мгновенно обмениваются платёжными данными, интегрируют учётные системы бизнеса с интернет-банком. К настоящему времени решение используют более 60 тысяч российских компаний, 65 из них — крупнейшие в своих отраслях. Это, например, СберРешения, ГК «Абсолют», ЮMoney, «Эвотор» и другие. Недавно команда разработки ГК СНС провела работы по интеграции своей ERP-системы со SberBusinessAPI всего за 12 дней. Выручка этого дистрибутора исчисляется сотнями миллиардов рублей.

Под эгидой SberBusinessAPI налажены подписание согласия клиента на передачу данных, методы выставления и оплаты счетов, блокировок денежных средств, работы с безакцептными списаниями (корпоративные подписки), получения информации по счетам и операциям, работы с зарплатным проектом, реестры задолженностей и платежей, работы с международными платежами, методы, позволяющие интернет-магазинам увеличивать продажи за счёт кредитных средств, предоставляемых клиентам Сбера. И, конечно, механизм бесшовной авторизации СберБизнесID. Им уже пользуются 360 тысяч организаций в месяц. Благодаря СберБизнесID нам удалось увеличить конверсию регистрации в постоянных пользователей с 30 до 75%.

Как работают приложения Сбербанк Онлайн: Workflow API и фрэймворки

Много кто пользуется приложением Сбербанк Онлайн, но немногие знают, как оно работает. Настало время приоткрыть завесу тайны – в этой статье мы расскажем о некоторых подходах, которые используем в разработке.

Здесь не будет биг даты, блокчейна, аджайла и другого рокет-сайенса. Зато будет описано API, на котором работают наши самые популярные приложения. Ценность этой статьи не в прорывных идеях, а в подходах и практиках, которые работают в большом приложении с одной из самых требовательных аудиторий.

Надеемся, что наш опыт поможет читателям сделать свой продукт лучше, а главное масштабируемым, потому что большинство шишек при разработке API мы уже поймали и исправили.

О чем пойдет речь

Мы расскажем, как в мобильном и веб приложениях Сбербанк Онлайн работают платежные сценарии, а именно про API между приложениями и сервер-сайдом.

Почему фокус на API? Все просто – это фактически единственный мостик, который соединяет клиентские приложения и бэкенд. Если проект небольшой, то мы можем легко менять API и переписывать под него приложения. Но если проект масштабный (такой, как у нас), то даже небольшие изменения API требуют вовлечения большого количества ресурсов как на фронте, так и на бэкенде, и становятся очень дорогими. И второй момент – чем раньше мы зафиксировали API, тем раньше фронтальные и бэковые команды могут начинать разработку. Им просто надо будет сойтись в одну точку.

Сначала мы немного расскажем о наших возможностях и ограничениях, чтобы было понятно, почему мы выбирали то, а не иное решение, а потом представим сам протокол API на верхнем уровне.

Специфика и мотивация

Приложения большие. Когда мы писали эту статью, приложение Сбербанк Онлайн на Android занимало около 800 000 строк кода, на iOS – 500 000 строк кода. И это только наш код, без подключаемых библиотек.

Обратная совместимость и много пользователей. MAU – 32 млн активных пользователей мобильного приложения. И если мы не сделаем обратную совместимость на уровне API, очень многим пользователям по всей стране придется качать приложения заново. Это очень нехорошо. Кстати, это одна из причин, почему у нас так много кода.

Сбербанк Онлайн разрабатывает много небольших команд. Вы, наверное, слышали про Agile в Сбербанке. Это правда, мы работаем по Agile в командах по 9 человек.

Приложение банковское: несмотря на то, что функциональность банковских приложений растет очень быстро, основное, что происходит в дистанционном банкинге – это последовательный процесс (обработка клиентских заявок). Такие процессы мы называем workflow. Заявки эти могут быть разного рода и обрабатываются они огромным количеством взаимосвязанных сервисов в периметре банка.

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

Омниканальность. Крайне важная история. Чтобы не разрабатывать бэк несколько раз – отдельно для мобильных приложений и отдельно, например, для веб-версии и банкоматов, нужно сделать так, чтобы API был максимально схожим для всех каналов (как минимум должна быть одинаковой структура ответа).

Мобильное приложение

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

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

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

Лучший клиентский опыт: мы выбрали для себя основную технологию разработки мобильных приложений – разработка на нативных языках. Только так можно получить лучший клиентский опыт.

Если обобщить все эти требования – приложения должны разрабатываться на нативных языках, иметь повторно используемые компоненты внутри себя, но при этом вся бизнес-логика должна управляться со стороны сервера.

Как делать не стали

После того как мы обозначили граничные условия, расскажем, какие существующие решения мы анализировали.

Программирование на JSON

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

Не используем описание стилей компонентов, поскольку они могут разниться от форм-фактора, платформы и даже режима работы (портретная/ландшафтная ориентация, responsive в web). Декларации стилей в конечной реализации всегда будут качественнее, ближе к реальности и корректнее работать с краевыми случаями. Кроме этого, бывает, что компоненты со схожей логикой принципиально по-разному работают на разных устройствах: например, ввод номера телефона – с телефонной книгой на мобильном устройстве и без неё в вебе.

Фиксация модели данных в интерфейсе приложения

Этот способ еще называется «прибить гвоздями». Смысл в том, что интерфейс приложения строится на уникальных идентификаторах объектов, которые передаются с сервера. В такой схеме любые изменения на стороне сервера приводят к переработкам клиентской части. Невозможно повторно использовать код. Сложно поддерживать.
Единственное, почему стоит выбирать такой способ на своем проекте, – уверенность на 99%, что API не будет меняться. Ну или если проект совсем небольшой и проектировать API дороже, чем быстро переделать пользовательский интерфейс под изменения в API.

Добавляем к каждому объекту признак стиля. UI приложений строим на основании этого признака. Стилей ограниченное число, поэтому появляется возможность строить интерфейс динамически. Но с увеличением функциональности UI приходится увеличивать количество стилей.
В этом варианте становится возможно управлять отображением отдельных элементов, но повышается сложность реализации связанности между разными полями. И главное – с ростом вариативности UI у вас будет постоянная необходимость расширять протокол API.

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

Web Components / React Components API

Концепция веб-компонентов, которая в том числе значительно повлияла на API компонентов React, нам подходит уже намного лучше: с одной стороны, у нас есть контроль за отображением, с другой стороны – есть возможность привязывать данные к элементам UI.
К сожалению, всё слишком сильно завязано на HTML + CSS + JS. Напрямую не используешь, но запомним – потом пригодится.

Как решили делать

UI-контейнеры

Объекты упаковываются в контейнеры, презентационную логику приложения строим на этих контейнерах. Основное преимущество – можем группировать несколько простых объектов в один контейнер. Это дает свободу в программировании UX/UI на клиенте, например, можем управлять скрытием/отображением одного поля при заполнении данных в другом. При этом базовых типов объектов – ограниченное число, и весь бизнес-транспорт реализуется на них.

Мы выбрали именно этот подход. Сначала мы опишем протокол API, а потом – как устроены фрэймворки внутри мобильных и веб-приложений.

Чтобы было понятнее, рассмотрим API на примере простого процесса, например, перевод между своими счетами. Как добираемся до точки входа, не рассматриваем – это не процесс и для этого есть свой API (о нем мы тоже как-нибудь расскажем). Итого, процесс у нас начинается с точки входа:
/>

Транспорт данных

Для начала договоримся об основных принципах – как передаём данные. За основу возьмём самый простой подход – пары «ключ-значение». Ключом пусть будет строка из букв латинского алфавита, значение – тоже строки, но уже произвольные.

Формы для заполнения бывают сложные, с вложенными элементами и подразделами, значит, надо допускать вложенность. Можно именовать ключи в формате camelCase, но они могут быть плохо читаемым (например, в логах) или даже «портиться» в системах, нечувствительных к регистру. Нужно ввести разделитель.

Самый очевидный разделитель – точка – во многих языках используется для доступа к свойствам объекта. При неаккуратном использовании ключи с таким разделителем будут создавать словари (или объекты), в которых возможны коллизии. Например, “foo.bar” = “foobar” и “foo.bar.baz” = “foobarbaz” в javascript может повлечь перезапись свойства “bar” объекта “foo” со строки на объект. В конце концов, договорились на двоеточии: с одной стороны, явное визуальное разделение и семантическое отражение вложенности, с другой стороны, достаточно безопасно для всех используемых языков.

Что делать с повторяемыми полями? Вводим дополнительное правило: между парой разделителей могут быть либо латинские буквы, либо цифры. Получаются конструкции вида: children:5:name:first.

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

Решение: значение – либо строка, либо список строк. Так решение выглядит типовым, но в то же время накладные расходы оказываются незначительными.

Шаг – это состояние процесса. Первый шаг у нас – выбор счета списания и счета зачисления и ввод суммы.

UI на этой картинке не видно, потому что шаг – это про серверную логику, а не про презентационную. Есть два подхода к работе с шагами: можно передавать с сервера только разницу (нарастающий итог в клиентском приложении) или каждый шаг целиком (нарастающий итог на сервере).

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

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

Экраны

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

Для экранов мы ввели два правила:

1. переход между экранами может быть только линейным, без ветвлений;
2. переход между экранами не требует взаимодействий с бэкэндом.

UI компоненты (блоки)

UI компонент – независимый компонент, который реализует клиентскую логику и наполняет документ данными. По сути, это ассоциация между управляющей командой в протоколе и куском кода и разметки в приложении. На первом экране три компонента:

1. Счет списания
2. Тот же компонент для счета зачисления
3. Сумма перевода

Поля – это атомарные компоненты, которые выступают транспортом для отдельных элементов данных и обрабатывают пользовательский ввод в случае деградации блока. Типов полей ограниченное число и все они поддерживаются на уровне фрэймворка: text, checkbox, select, multiselect.

Это значит, что любая версия приложения может отрисовать интерфейс, опираясь только на типы полей.

Поля в UI-компонентах из нашего примера:

1. Поле со ссылкой на справочник в счете списания и счете зачисления. Почему ссылка на статический справочник? Потому что счет мы выбираем из списка карт (счетов), без лишнего обращения к серверу.

2. Два отдельных поля для суммы и валюты в компоненте ввода суммы

Таким образом, формат для полей имеет такую структуру:

События

Так как приложения ничего не знают о процессе, логично, чтобы события (кнопки, которые видит пользователь) тоже были частью ответа от сервера.

События мы разделили на два типа.

1) Основные – они есть почти на каждом экране в привычных местах для пользователя. Как пример, это события «назад» и «продолжить». Первое осуществляет переход на шаг назад, а второе собирает заполненные данные с клиентской формы и отправляет их на сервер вместе с командой «Перейти на следующий шаг».

2) И специальные – для нестандартных действий, которые мы заранее спрогнозировать не можем, да и смысла закладывать их в часть движка нет, так как они редко используются.
В нашем случае на экране только основные события – «продолжить» и «назад». Они реализованы на уровне платформы.

У всех событий есть ряд атрибутов, такие как сам тип события, title и признак видимости. И никакого UI на сервер-сайде вроде размера кнопки, положения и цвета. Эта логика реализуется на фронте.

Справочники

Со справочниками все стандартно. Если он небольшой, то мы его присылаем полностью в ответе от сервера и называем статическим. Сделано это для того, чтобы минимизировать количество запросов к сервер-сайду и время отклика на действие пользователя в интерфейсе. Чтобы его отобразить в форме на экране, добавляем поле с типом – selectList, одно из свойств которого – ссылка на статический справочник.

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

Ошибки валидации на клиенте и сервере

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

Примерно так выглядит структура ответа:

Фрэймворки

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

Workflow engine

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

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

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

Как работают UI-контейнеры?

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

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

Два режима работы фрэймворка

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

Слева – как может отображаться контейнер для ввода суммы на списке из простых типов полей. Справа – если в сборке приложения есть UI-контейнер. Несмотря на то, что в режиме списка простых полей нет слайдера и есть отдельное поле вместо иконки с выбором валюты, – мы можем передать все данные с PL и процесс будет рабочим.

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

Каких правил мы стараемся придерживаться при работе с UI-компонентами:

• Поддерживать работу функционала в режиме списка простых типов полей. У любого прикладного проекта есть соблазн превратить динамический протокол в статический. Поэтому мы всех просим сначала разработать функционал на типовом UI-контейнере, а потом обогащать UX/UI добавлением кастомных контейнеров на этой модели данных. Это не только позволит в будущем обновлять процессы на старых сборках, но и автоматически поддерживает логическую целостность API.
• Не менять модель данных (JSON) для UI-контейнера, если он уже готов (проходит финальное тестирование или уже в продакшене). Так как логика на PL жестко связана с моделью данных, её изменение сломает функционал на версиях мобильного приложения, которые не обновляются. Тем не менее, модель можно расширять при условии сохранения обратной совместимости.
• Называть свой UI-компонент системным именем. Так как имя UI-компонента – обязательный атрибут протокола и должен быть минимум один на каждом экране, мы ввели специальное системное имя, которые реализует простой список полей.
• Не реализовывать бизнес-логику на UI-компонентах. Логику необходимо реализовывать на сервере, почему – писали выше.

Coming soon…

Мы очень старались писать лаконично, но это первая техническая статья про платформу Сбербанк Онлайн и она должна была многое охватить.

Пишите в комментариях, что непонятно, что интересно – постараемся писать меньше, но чаще и в цель. У нас много интересных вызовов, и поэтому много материала.

Saved searches

Use saved searches to filter your results more quickly

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.

SberID / android-sdk Public archive

Android SDK помогает реализовать получение кода авторизации (Auth Code) Сбер ID минимальными усилиями со стороны разработчика и в соответствии с утвержденными гайдами по отображению кнопки.

License

Unknown, Unknown licenses found

Licenses found

SberID/android-sdk

Name already in use

• Local
• Codespaces

Use Git or checkout with SVN using the web URL.

Work fast with our official CLI. Learn more about the CLI.

Sign In Required

Please sign in to use Codespaces.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio Code

Your codespace will open once ready.

There was a problem preparing your codespace, please try again.

Latest commit

Git stats

Files

Failed to load latest commit information.

README.md

Android SDK

Общие сведения

Android SDK помогает реализовать получение кода авторизации (Auth Code) Сбер ID минимальными усилиями со стороны разработчика и в соответствии с утвержденными гайдами по отображению кнопки. Чтобы добавить поддержку Сбер ID в свое приложение, следуйте инструкциям ниже. Для выполнения успешных запросов Вам необходимо зарегистрировать Ваше приложение в банке и подписать договор. Заявку можно оставить по ссылке

Подключение

Используя maven:

Подключая aar файлом:

Добавьте файл .aar в папку libs вашего проекта:

Перейдите в build.gradle вашего модуля:

И добавьте зависимость в раздел dependencies:

ВАЖНО! SDK реализована на языке Kotlin (версия 1.4.0), поэтому если в вашем проекте используется только Java и никакие дополнительные зависимости на Kotlin ранее не подключались, нужно добавить поддержку Kotlin (версия указана для примера, актуальна на момент написания документации):

ВАЖНО! Android Studio покажет предупреждение о том, что версия Kotlin Plugin (null) не соответствует версии подключенной библиотеки, но в данном случае подключение к проекту Kotlin Plugin не является обязательным. Все вызовы статических методов SDK в вашем Java-коде по примерам ниже необходимо выполнять через стандартный вспомогательный объект Companion, например:

Перейдите в settings.gradle вашего проекта:

И подключите библиотеку к вашему проекту:

Поддержка Android 11+

ВАЖНО! Начиная с версии 1.3.1 SDK поддерживает определение видимости МП СБОЛ по требованиям, введенным в Андроид 11. Для возможности корректной сборки проекта необходимо, чтобы версия Android Gradle Plugin в вашем приложении была соответствующей. Подробнее про функционал видимости внешних пакетов можно ознакомиться в документации Google:

Если версия Android Gradle Plugin будет ниже требуемой, при сборке проекте будет возникать ошибка Android resource linking failed. Для поддержки работоспособности достаточно минорного обновления версии Android Gradle Plugin в зависимости от той, которая у вас используется сейчас, подробнее про версии плагина можно прочитать здесь:

Минимально допустимая версия Android Gradle Plugin, поддерживающая требования в Андроид 11 — 3.3.3. Минимально допустимая версия Gradle, поддерживающая эту версию плагина — 4.10.1.

Отправка аналитических событий

Начиная с версии 1.3.0 SDK автоматически формирует и отправляет на сервер Сбербанка события, связанные с авторизацией по Сбер ID (показ и клик по кнопке, результат авторизации).

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

Отправка аналитических событий

Начиная с версии 1.3.0 SDK автоматически формирует и отправляет на сервер Сбербанка события, связанные с авторизацией по Сбер ID (показ и клик по кнопке, результат авторизации).

Для корректной работы функционала отправки событий необходимо выполнить следующие действия:

• если ваше приложение использует только Kotlin, то добавьте в файл build.graddle вашего приложения в раздел android блок кода для совместимости с Java (если уже используете Java, это делать не нужно):

• добавьте зависимости в раздел dependencies (если вы подключаете aar файлом):

• если вы уже используете в своем приложении какие-то из указанных выше зависимостей, указывать их заново не нужно
• версии добавляемых библиотек рекомендуется использовать не ниже тех, которые указаны в примере выше в явном виде или комментарии //min

Синхронизируйте ваш проект – библиотека подключена!

Добавление кнопки

Для добавления кнопки используйте в своей разметке вью sberid.sdk.auth.view.SberIDButton

Кнопка автоматически устанавливает иконку Сбербанка, текст, шрифт, цвет по указанным в атрибутах значениям либо значениями по умолчанию. Высота кнопки органичена интервалом 28dp-64dp, при установке высоты, выходящей за пределы интервала, высота будет автоматически приведена в соответствующей границе. Ширина кнопки имеет минимальное значение, исходя из размеров выбранного текста, логотипа и отступов. Максимальная ширина кнопки не ограничена.

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

Вам остается только добавить:

• параметры для положения кнопки
• отступы

Для большей информации о стиле кнопок, смотрите гайд по дизайну Сбер ID.

Пример (значение и способ размещения кнопки может отличаться, зависит от вашей реализации)

Кастомизация кнопки

Тип

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

Для изменения стиля кнопки, укажите параметр в xml кнопки app:buttonType=»значение из списка».

Значение ‘white_type соответствует белой кнопке с серой обводкой:

Обводка

В случае установки типа кнопки «white_type» есть возможность переопределить значение цвета обводки для соответствия вашему дизайну, если на экране присутствует несколько однотипных кнопок.

Для этого установите конкретный цвет через атрибут кнопки app:buttonStrokeColor=»@color/. «

При установке цвета обводки для стандартной зеленой кнопки значение будет проигнорировано.

Скругление

Для изменения скругления кнопки, укажите параметр в xml кнопки app:buttonCornerRadius=»значение_dp». Предопределённые значения «corner_small» и «corner_large» соответствуют 4 и 32 dp соответственно. Есть возможность указать здесь собственное значение радиуса скругления в dp.

Текст

Для изменения текста кнопки, укажите параметр в xml кнопки app:buttonText=»значение из списка».

Значение по умолчанию — Войти по Сбер ID. Установка собственного текста, шрифта, цвета текста не поддерживается.

• allCaps всегда выключен (т.е. текст не будет заглавными буквами) ;
• тексты поддерживают английскую локализацию на устройстве. При выборе локализации, отличной от русской и английской, тексты будут на русском.

• В примере кнопка с текстом «Сбер ID» отрисована с минимально допустимой шириной

Персонализация кнопки

Начиная с версии SDK 1.2.0 кнопка входа по Сбер ID автоматически поддерживает персонализацию при выполнении следующих условий:

• на устройстве установлено МП СБОЛ версии от 11.8 и выше
• в МП СБОЛ пользователем включен функционал персонализации входа в приложениях партнера (МП СБОЛ — Профиль пользователя — Сбер ID — Настройки входа)

Дополнительных действий от разработчиков при интеграции этой версии SDK не требуется.

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

Если персонализация на стороне МП СБОЛ отключена либо на устройстве не установлено МП СБОЛ либо процедура персонализации завершилась неуспешно, текст на кнопке будет отображаться тот, который вы указали в разметке при ее добавлении.

• Если кнопка была добавлена с коротким текстом «Сбер ID», персонализация кнопки не будет запущена в любом случае. Если дизайн экрана предполагает наличие широкой кнопки входа по Сбер ID, рекомендуется использовать один из длинных вариантов текста

При запуске процедуры персонализации на кнопке отображается индикатор загрузки:

После завершения персонализации кнопка выглядит следующим образом:

Если имя пользователя слишком длинное, чтобы уместиться в отведенное размерами кнопки место, итоговый текст будет автоматически обрезан с правой стороны:

Управление статусом загрузки

Начиная с версии SDK 1.3.5 появилась возможность вручную программно управлять статусом загрузки в кнопке (анимированное лого СберБанка, как в разделе Персонализация кнопки).

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

Установка/снятие статуса загрузки вручную не мешает работе процедуры персонализации кнопки, эти процессы не связаны друг с другом. Если на момент снятия вами статуса загрузки процедура персонализации еще не будет завершена, то анимация лого продолжится до ее завершения.

Предусмотрено два варианта управления статусом:

• атрибут в xml разметке кнопки app:buttonLoader=»значение_true_false». Если ваш экран подразумевает ожидание каких-либо данных при первоначальной отрисовке UI, рекомендуем пользоваться именно этим способом, выставляя в разметке значение true. Если атрибут в разметке не указан, по умолчанию значение принимается за false.

• публичный метод в классе кнопки SberIDButton для управления статусом загрузки по мере необходимости из программного кода

Запуск авторизации по Сбер ID

Класс SberIDLoginManager содержит все методы для работы с авторизацией по Сбер ID.

• для корректной работы необходимо обеспечить, чтобы экземпляр созданного класса **SberIDLoginManager** создавался и переживал весь цикл авторизации по Сбер ID (запрос на авторизацию и проверка результата). Будьте внимательны при работе с вашим DI, в противном случае при проверке результате вы будете получать ошибку «invalid_state»

Для запуска аутентификации используйте метод loginWithSberbankID.

Класс SberIDLoginManager содержит статический билдер для удобного создания uri для авторизации по Сбер ID, он позволяет минимизировать ошибки ввода значения в неверный параметр. Класс PkceUtils содержит утилиты для создания значений параметров протокола PKCE (необязательные параметры, если вы не используете PKCE).

Необходимо направить запрос на support@ecom.sberbank.ru на добавление deeplink в список доверенных. В запросе указывается client_id и список deeplink, по которым будет производиться возврат в мобильное приложение партнера. Сотрудник банка добавит домен в список разрешенных.

После выполнения авторизации по Сбер ID в обратном интенте придет deeplink, содержащий результаты авторизации.

В манифесте вашего приложения для активити, которая будет обрабатывать результат авторизации по Сбер ID, необходимо указать схему и хост обратного deeplink (они должны совпадать с redirectURI, который вы присылаете к нам). Если хотите обрабатывать обратный deeplink в той же активити, в которой и стартовали аутентификацию, необходимо указать в атрибуте launchMode для вашей активити значение «singleTop» и получать интент с результатом в методе onNewIntent(intent: Intent).

Примеры обработки deeplink:

Для проверки результата передать полученный intent в метод SberIDLoginManager#getSberIDAuthResult(intent), который его обработает ответ и вернет сущность SberIDResultModel.

В большинстве случаев вам будет нужен nonce и authCode, они приходят в при успешной авторизации и вы их должны передать в свой бэк для дальнейшей аутентификации вместе с codeVerifier (если используете), созданным ранее.

Также будет передан параметр state, который был получен от сервера авторизации. Проверка на соответствие изначально переданному в запросе от партнера параметру state выполняется на стороне SDK, см. раздел Описание ошибок.

Пример обработки в том же окне:

При обработки в отдельном окне можно перехватить в методе onCreate(savedInstanceState: Bundle?)

Поддержка бесшовной авторизации

Начиная с версии SDK 1.3.5 реализована поддержка бесшовной авторизации по Сбер ID, когда после перехода из приложений СберБанка в ваше приложение необходимо автоматически запустить авторизацию без показа кнопки и необходимости пользователю выполнять лишнее действие по нажатию на нее.

В диплинке, который придет в ваше приложение, помимо параметров, которые вы заложите в него самостоятельно по вашим требованиям, будет приходить дополнительный параметр, содержащий строку со схемой и хостом, которую нужно будет передать в билдер диплинка авторизации по Сбер ID (см. раздел Запуск авторизации по Сбер ID).

Для стандартной (не бесшовной) авторизации по Сбер ID по кнопке выполнять указанные в этом пункте действия не требуется.

Чтобы получить значение этого параметра, необходимо воспользоваться следующим методом в классе SberIDLoginManager, передав в него исходный uri, полученный при перехода в ваше приложение в сценарии бесшовной авторизации (uri находится в getIntent().getData()).

Полученное значение необходимо передать в следующий метод билдера SberIDLoginBuilder при построении диплинка авторизации.

Все дальнейшие действия по подготовке диплинка и старте авторизации аналогичны описанным в разделе Запуск авторизации по Сбер ID.

Запуск авторизации Сбер ID в CustomTabs

Начиная с версии SDK 1.4.0, была добавлена поддержка запуска авторизации по Сбер ID через веб-страницу oidc, которая открывается в CustomTabs. Теперь, если приложение СберБанк Онлайн не установлено на устройстве, веб-страница авторизации откроется в CustomTabs, а не во внешнем браузере, как это было раньше. Это позволяет реализовать еще более бесшовный сценарий для клиента без редиректов в отдельное приложение.

Для этого в вашем проекте должна быть добавлена зависимость на библиотеку браузера AndroidX (если вы подключаете aar файлом).

Для этого в вашем build.gradle пропишите ее в разделе зависимости, если ее еще нет (версия указана на момент публикации, можно использовать более актуальные):

Сбер ID через единое веб окно авторизации

В версии SDK 1.4.0 была добавлен новый метод для авторизации пользователя по Сбер ID, используя единое веб окно авторизации. Данный метод предназначен для партнеров, которым необходимо по той или иной причине производить авторизацию только через веб.

Для этого нужно чтобы была подключена зависимость на библиотеку androidx.browser и версия sdk от 1.4.0. **Не используйте** этот способ, если вам нужен обычный вход через Сбер ID.

Как это работает:

Создайте Uri, как при обычном входе с дополнительным параметром customTabRedirectUri. Для этого в SberIDLoginManager.sberIDBuilder() появился новый метод customTabRedirectUri(customTabRedirectUri: String, context: Context): SberIDBuilder:

Запустите авторизацию, используя функцию loginWithSberIDToCustomTabs(context: Context, uri: Uri): Boolean, класса SberIDLoginManager. Если запуск сценария невозможен, вернется false, данное поведение возможно, если не были подключены все необходимые зависимости, нет подходящих браузеров на устройстве или ссылка была собрана некорректно.

Если все сделано верно, вы увидите окно с различными способами идентификации входа по Сбер ID:

Новый параметр СustomTabRedirectUri используется для возврата в ваше приложение в сценариях: «Вход по номеру телефона», «Войти через Сбербанк Онлайн» и других. Она запускает заглушечную activity, которая открывается поверх окна с CustomTabs и сразу закрывается. Тем самым происходит возврат на то самое веб окно с CustomTabs, с которого начиналась авторизация в вебе. В SDK идет готовая заглушечная activity ReturnToCustomTabsSberIDActivity, чтобы использовать ее добавьте activity в вашем AndroidManifest.xml:

ВАЖНО! android:host и android:scheme соответсвуют customTabRedirectUri из предыдущих шагов. Регистрация на стороне банка customTabRedirectUri аналогичная той, что используется для redirectUri. android:launchMode=»singleTask» позволяет вернуться в ваше приложение вне задачи мобильного приложения СберБанк Онлайн.

Окно с CustomTabs после восстановления продолжит свою работу и в результате, как и раньше, после авторизации пользователя, по диплинку из переданного изначально redirectUri, произойдет редирект на нужный экран вашего приложения.

Смотрите пункт Запуск авторизации по Сбер ID.«

Описание ошибок

Если state сгенерированный вами и state возвращенный при авторизации по Сбер ID не совпадет, результат будет ошибочным, в SberIDResultModel.errorDescription вернется фраза «invalid_state». При других ошибках, так как падение приложения Сбербанк Онлайн, прерывание сценария и др. будет ошибка «internal_error»

Пример ответа с ошибкой

типы возвращаемых ошибок	описание ошибок
invalid_request	В запросе отсутствуют обязательные атрибуты.
unauthorized_client	АС-источник запроса не зарегистрирована в банке.
unauthorized_client	АС-источник запроса заблокирована в банке.
unauthorized_client	Значение атрибута client_id не соответствует формату.
unsupported_response_type	Значение атрибута response_type не равно «code».
invalid_scope	Запрошенный scope содержит значения, недоступные для АС-источника запроса.
invalid_request	Значение code_challenge_method не соответствуют допустимым значениям.

• Для любого из перечисленных типов ошибок МП СБОЛ на платформе Android возвращает в приложение партнера код 5 в параметре error_code без указания типа ошибки.
• В случае отсутствия в запросе атрибута redirect_uri или в случае если значение redirect_uri не зарегистрировано для данного партнера, банк перенаправляет клиента на экран, информирующий клиента о недоступности сервиса.

About

Android SDK помогает реализовать получение кода авторизации (Auth Code) Сбер ID минимальными усилиями со стороны разработчика и в соответствии с утвержденными гайдами по отображению кнопки.