Руководитель отдела: “Привет, там пришел новый проект с интересной интеграцией. Пойдёшь?”
Аналитик: *был(а) в сети 5 минут назад*
Всем привет! Меня зовут Алина, и я — бизнес и системный аналитик команды Surf.
Я работаю с мобильными приложениями, у меня за спиной 5 интеграций с небольшими внешними сервисами и одна с большой гибкой системой. И да, новости о предстоящих «интересных интеграциях» до сих пор иногда вызывают реакцию, как в переписке выше.
Почему?
Любая интеграция с незнакомой системой — это почти 100% неопределённости.
В проектах с интеграциями встречаются сложности с оценкой работ, прогнозированием сроков поставки ТЗ, технические ограничения и другие «радости».
Хорошая новость — можно найти подход, который позволит снизить этот уровень неопределённости и структурировать план действий. И сейчас мы о нём поговорим.
Ремарки:
Мы расскажем про кейсы, с которыми сталкивались в проектах с интеграцией.
Мы опишем подход преимущественно для роли BA/SA. Если вы занимаете иную должность, статья может быть полезной для понимания зоны ответственности BA на этапе проектирования интеграции и пополнения базы знаний.
Предлагаемый подход — это последовательность действий, собранная опытным путем. Конечно, это он не единственно верный. И его можно (и нужно) корректировать с опорой на систему, с которой вы будете интегрироваться, и процессы компании.
Мы рассмотрим API-интеграции.
Итак, представим: вы подключились к проекту. Перед вами стоит задача – спроектировать интеграцию с системой Х.
Этап 1. Ресерч
Спойлер: самый важный этап!
Часто ресерч не выделяется отдельным этапом, а входит в состав проектирования.
Тем не менее, если заранее выполнить пункты 1.1-1.5, дальнейшие работы, с большей вероятностью, пройдут более ровно.
1.1. Определить, с чем нужно работать
К моменту проектирования мы, скорее всего, уже понимаем, какие составные части должен включать в себя продукт.
А в случае с интеграцией необходимо определить, какие продукты системы Х понадобятся и зачем.
Пример
Мобильное приложение для заказа еды из ресторана.
Необходимые требования
Заказ должен создаваться по API системы на конкретной точке сети ресторанов и отображаться у работника на кассе.
Вопрос, который можно задать
Как происходит взаимодействие с заказом после его получения на кассе?
Ответ
Принять заказ и перевести его в другой статус может только кассир с доступом к продукту системы Х — кассовой станции.
Система в этом случае будет отправлять Webhook с новым статусом заказа. Это программный код, с помощью которого отслеживают изменения на одном ресурсе и передают данные на другой.
А актуальный статус заказа будет отображаться пользователю в интерфейсе.
Итог
Нам нужен доступ к кассовой станции — одному из продуктов системы Х — для проектирования и тестирования полноценного флоу заказа: от создания до готовности.
1.2. Разобраться в ограничениях продуктов системы Х
Если система предлагает гибкую настройку в административной панели и в веб-офисе, полезно знать базовые принципы управления настройками.
С их помощью можно самостоятельно управлять данными и не отвлекать клиента просьбами с изменением сущности. А ещё — быстро локализовать ошибки и предусматривать часть технических ограничений системы.
Пример
Мобильное приложение для продажи рецептов и продуктов для приготовления блюда по этим рецептам.
Требования
Пользователь должен иметь возможность убрать из заказа часть опциональных продуктов. Например, из-за аллергии.
Действия
Заходим в административную панель системы и понимаем, что возможности регулировать опциональность продуктов в рамках рецепта нет. Все продукты считаются обязательными — система не пропускает продажу рецепта без этого продукта.
Итог
Вот мы и столкнулись с техническим ограничением. Теперь подсвечиваем его клиенту, совместно оцениваем риски и принимаем решение. Собственно, на этом этапе можно рассмотреть альтернативные системы для интеграции.
1.3. Договориться об ограничениях тестирования
Стоит заранее поговорить с клиентом о возможностях и ограничениях тестирования.
Если клиент уже работает с системой, с которой мы интегрируем мобильное приложение, не исключено, что какие-то настройки регулировать нельзя.
Пример
Интеграция умного поиска в мобильное приложение. На сайте заказчика она уже настроена.
Требования
У пользователя должна быть возможность перейти к Каталогу по тапу на подсказку в выпадающем из поля поиска списке.
В Каталоге должен отображаться список фильтров с разными типами: слайдер, свитчер и множественный выбор.
Типы и значения фильтров регулируются в административной панели интегрируемого сервиса.
Действия
Заходим в административную панель системы и видим, что у всех фильтров, настроенных для сайта, одинаковый тип: множественный выбор.
Приходим к клиенту с запросом на настройку дополнительных фильтров разных типов для дальнейшего тестирования. И тут выясняется, что делать это категорически нельзя, поскольку сайт в текущей реализации поддерживает только один тип.
Итог
Чтобы избежать нестабильной работы сайта и спроектировать интеграцию по требованиям клиента, мы синхронизируем работы с разработчиками сайта.
1.4. Определить источники информации, к которым можно обращаться в процессе проектирования
Что может помочь:
-
Официальная документация для разработчиков.
Здесь всё просто: официальная документация есть у большинства сервисов, и она значительно упрощает проектирование. Но полностью полагаться на документацию не стоит, об этом ниже;
Бесплатная или платная техническая поддержка со стороны разработчиков системы.
Некоторые системы предлагают прямую услугу технической поддержки. Формат поддержки зависит от конкретной компании и предложения, обычно это текстовая коммуникация в чате или голосовые консультации. Но помним, техническая поддержка встречается не всегда и может зависеть от тарифа;
-
Опыт коллег и внутренняя документация компании.
Тут помогут ключевые слова для поиска информации во внутренних ресурсах. Можно поболтать с коллегами — вполне возможно, что у них уже был опыт интеграции с системой или её аналогом на предыдущем месте работы;
-
Документация и API сервисов-конкурентов.
Если мы знаем аналоги интегрируемой системы или у нас был опыт интеграции с сервисом-конкурентом, можно собрать папку «шпаргалок», они могут быть хорошим ориентиром в момент принятия решений;
-
Поисковики и ИИ.
Мы обычно используем ChatGPT для изучения возможностей настроек продуктов системы.
Пример запроса:
В каком продукте системы A настраивается номенклатурное меню по сети ресторанов: в X или Y?Ответ ChatGPT:
Настройка номенклатурного меню в сети ресторанов обычно производится в Y. Y предоставляет централизованные инструменты для управления различными аспектами бизнеса в сети, включая меню, цены и акции.
1.5. Оценить необходимость реализации прослойки
Система Х может иметь особенности, которые при прямом общении Mobile <-> Система X, будут негативно влиять на скорость работы приложения, пользовательский опыт и другие параметры.
Обойти такие проблемы можно реализацией Middleware (прослойки).
Пример
Мобильное приложение для заказа продуктов курьером на дом. Все бизнес-процессы — бухгалтерия, продукты, стоп-листы — у заказчика настроены в системе Х. Нужна интеграция мобильного приложения с системой.
Необходимые требования
Каталог продуктов должен быть расположен на Главном экране, чтобы пользователь видел его сразу при открытии приложения.
У Каталога может быть два уровня вложенных категорий и переход на листинг со списком продуктов по тапу на категорию или подкатегорию.
Действия
Изучаем API системы и понимаем, что из-за особенности загрузки товаров в систему и их правильного учета, получать товары мобильное приложение может только общим списком. Получается, запрос вернет сразу все товары всех категорий. Ожидание ответа запроса занимает от 6 до 15 сек.
Итог
6 секунд ожидания на Главной странице мобильного приложения — ну очень много. Нам понадобится Middleware, который будет хранить и обновлять в базе категории и продукты и отдавать мобильному фронту запрашиваемые продукты из конкретной категории.
Этап 2. Проектирование
Есть несколько моментов, о которых не стоит забывать и на этапе проектирования. Даже если кажется, что всё уже предельно понятно.
2.1. Тестирование запросов
Даже если мы говорим о наличии подробной официальной документации, сервис проверен или у нас уже был опыт интеграции с ним, тестирование запросов — обязательный шаг перед передачей функциональности в разработку.
Почему это важно:
API меняется и дорабатывается, документация не всегда обновляется автоматически. Можно столкнуться с тем, что она устарела.
Интеграционный партнер может работать нестабильно. Чем раньше это выяснится, тем быстрее можно принять меры.
Формат ответов может зависеть от кастомной настройки в панели системы.
В документации может быть не описана обязательность входных параметров и прочие характеристики. Это может привести к некорректной работе запросов.
Активность зависит от сложности интеграции и доступности системы. Иногда тестирование запросов проводится еще на этапе ресерча.
2.2. Ведение документации для производственной команды
И речь не о ТЗ (хотя без него известно, какой результат).
На этапе проектирования интеграции BA/SA владеет наибольшим количеством информации о самой системе, её особенностях, тестовых данных для получения результата и воспроизведения конкретных кейсов. Наша задача здесь: документировать все неочевидные шаги для команды, чтобы экономить время.
Как узнать, достаточно ли информации мы оставили в документации? Мы можем задать себе вопрос: «Если я уйду в отпуск или на больничный, команда или замещающий сотрудник смогут продолжить работу по интеграции без моей поддержки?».
Пример
Интеграция сервиса Программы лояльности в мобильное приложение.
Необходимые требования
Программа лояльности должна включать в себя возможность использования пользователем Промокодов 3 разных типов: скидка на категорию товаров, фиксированная скидка в рублях, подарочный товар.
Помимо этого, нужно внедрить накопительную систему бонусов.
В процессе проектирования
Мы получаем у клиента доступ к системе заведения Промокодов и разбираемся в настройках каждого типа Промокода. Клиент рассказывает, как можно вручную начислить баллы на бонусную карту.
Документация для команды
На этапе разработки и тестирования команде придётся пополнять баланс бонусной карты для тестирования списания бонусов. А ещё необходимо будет протестировать работу всех типов Промокодов.
Если подготовить документ с доступами в систему и шагами по настройке Промокодов и пополнению баланса и поделиться им с командой, удастся на 30-40% сократить время на коммуникацию и минимизировать свое участие на этапе реализации.
2.3. Управление ожиданиями клиента при столкновении с техническими ограничениями
Предусмотреть все ограничения до старта проектирования практически невозможно.
Если мы сталкиваемся с техническим ограничением, которое мешает реализовать функциональность так, как этого хочет клиент, есть несколько вариантов:
Адаптировать дизайн под возможности системы.
Если изменение незначительное, не нарушает пользовательский путь, не противоречит бизнес-целям продукта, можно изменить дизайн по согласованию с клиентом.
Минусы
Это решение обычно нравится клиенту меньше всего, потому что приходится отходить от ранее согласованного варианта функциональности.
Плюсы
Этот вариант можно быстро реализовать.
Сформировать запрос на доработку настроек системы.
На сайтах некоторых систем можно найти форму, куда разработчики просят писать обращения по доработке API. После обработки обращения, нам могут обозначить приблизительный срок реализации.
Минусы
Придётся ждать. Не всегда интеграционный партнер может гарантировать, что запрос одобрят и передадут в разработку.
Плюсы
Клиенту не нужно платить, а вам - придумывать обходные пути в реализации.
Реализовать часть функциональностей при помощи собственной Административной панели.
Если клиент не готов отказываться от функциональности, а система не позволяет реализовать её в полном объёме, можно предложить управление функциональностью из кастомной Административной панели.
Минусы
Долго и дорого по сравнению с первым решением.
Плюсы
В перспективе есть возможность реализации новых функциональностей без привязки к интегрируемой системе.
2.4. Ведение документации для менеджеров системы и Административной панели
Если мы интегрируемся и с системой с гибкой настройкой, не исключено, что ограничения встретятся нам не только со стороны этой самой системы. Мы и сами будем формировать требования по форматам, контенту и настройкам.
Контекст
Обязательное требование AppStore и Google Play в отношении мобильных приложений — наличие в них функциональности Удаление аккаунта.
Информация о пользователе хранится в системе X, с которой мы интегрированы. Удалить пользователя из системы X можно только вручную.
Доработка
Мы реализовали функциональность удаления аккаунта в мобильном приложении. Полный флоу удаления выглядит так:
Пользователь тапает по кнопке «Удалить аккаунт» и подтверждает удаление.
Фронтенд отправляет бэкенду запрос на удаление аккаунта.
Бэкенд создает запись с данными о пользователе под удаление в Административной панели.
Фронтенд отображает пользователю информацию, что его аккаунт будет удален через N дней.
Менеджер заходит в Административную панель, находит пользователя для удаления.
Менеджер вручную зачищает данные о пользователе в системе X.
Менеджер в Административной панели помечает пользователя статусом «Удалён».
Документация для менеджера
Чтобы не нарушать требования магазинов приложений и не обманывать пользователя, Менеджер административной панели должен мониторить список аккаунтов под удаление раз в N дней и понимать, как с этим списком взаимодействовать.
Если мы не укажем это в документации и не передадим клиенту при сдаче проекта, можем получить последствия в виде негативных отзывов от пользователей или санкций от магазинов.
2.5. Оптимизация взаимодействия с системой
В процессе интеграции придётся задумываться об организации кеша и частоте обращений к системе.
Рассмотрим на базе примера из пункта 1.5. – долгий запрос на получение списка товаров Каталога.
Пример
Мобильное приложение для заказа продуктов курьером на дом. Все бизнес-процессы — бухгалтерия, продукты, стоп-листы — у заказчика настроены в системе Х. Нужна интеграция мобильного приложения с системой.
Мы уже поняли, что нам нужен Middleware — чтобы не заставлять пользователей несколько секунд «наслаждаться» состоянием загрузки.
Новый вопрос: Как часто Middleware должен отправлять запрос системе, чтобы не нагружать сервер и всегда иметь актуальные данные?
Это зависит от бизнеса клиента и динамики изменения Каталога. Если клиент утверждает, что наполнение Каталога меняется раз в сезон, и сотрудники компании следят за наличием товаров, нет нужды отправлять запрос на обновление раз в минуту.
А если мы предположим, что нам понадобится быстро обновить данные Каталога, например, из-за запуска акции? В таком случае можно реализовать кнопку в Административной панели, которая будет триггерить обновление. Конечно, если реализация Административной панели изначально была предусмотрена.
Мы сознательно не говорим подробно о ТЗ, потому что у нас есть согласованный шаблон, на который мы ориентируемся при описании документации.
Тем не менее, не можем не сказать, что пункты выше можно интегрировать в ТЗ.
А выбор формата описания здесь зависит исключительно от удобства восприятия
Этап №3. Завершение интеграции.
Здесь будет всего два пункта, но они очень важны.
3.1. Передача требований и проведение демонстрации
Завершение интеграции должно сопровождаться согласованием и передачей этих требований всем заинтересованным лицам. В отдельных случаях стоит провести демонстрацию (которую можно записать) или обучение.
Что может произойти, если этого не сделать:
активный и ресурсозатратный этап поддержки или гарантийного обслуживания — все вопросы придётся закрывать «точечно»;
появление у пользователей ошибок из-за некорректных настроек. Заниматься локализацией этих ошибок, скорее всего, будет команда исполнителя;
повторная защита решения и требований к определенному формату данных перед заказчиком. Клиент забудет о том, что обсуждали на проектировании, а аргументов в виде проведенной демонстрации не будет;
Следствие из первых трёх пунктов — подрыв доверия со стороны клиента и испорченные деловые отношения.
3.2. Документирование опыта интеграции
Не зря в 1.4 в источниках информации фигурирует пункт «Опыт коллег и внутренняя документация компании». Если позволяют ресурсы, хорошей практикой станет дополнение общей базы знаний наработками о новой системе.
Описание опыта интеграции не только будет полезно для коллег, но и поможет структурировать пройденный путь, выделить главное, подсветить проблемное и сформировать лучшие практики.
Что можно зафиксировать в документации:
описание продуктов системы;
описание технических ограничений, с которыми столкнулись, и решений, которые внедрили;
особые случаи — корнер-кейсы, если они встречались;
ссылки на документацию проекта, официальную документацию системы и дополнительную информацию.
Кажется, рассказали обо всём. Будем рады, если в комментариях вы поделитесь опытом и дополните список!
Кейсы и лучшие практики в области системной и бизнес-аналитики, новости, вакансии и стажировки Surf — в телеграм-канале Surf Tech.