Общая работа с OTAPI
Все методы можно увидеть на странице с документацией: http://docs.otapi.net/
Для получения ответа от api в формате xml нужно отправить GET/POST запрос на адрес http://otapi.net/service/ или http://otapi.net/OtapiWebService2.asmx/
Для получения ответа от api в формате json нужно отправить GET/POST запрос на адрес http://otapi.net/service-json/
К адресу нужно добавить имя метода, и параметры в GET/POST виде, в зависимости от запроса и его размера. Некоторые параметры могут не поместиться в GET-запрос, поэтому проще сделать всегда POST.
В ответе от api обязательно приходит узел ErrorCode, если он не равен 'Ok' и не равен 'BatchError' - необходимо обработать ошибку. Ошибки необходимо разделять по значению в узлах ErrorCode и/или SubErrorCode.
Некоторые ErrorCode которые можно обрабатывать глобально на уровне приложения:
- SessionExpired - сессия покупателя или администратора истекла, необходимо предложить пользователю авторизоваться и повторить свои действия.
- AccessDenied - для данного пользователя доступ к этому методу запрещен.
- InstanceKeyBan - ключ приложения заблокирован, обратитесь к менеджерам в ваш скайп чат за подробностями. Пользователю приложения, в таком случае, желательно показать заглушку, например "На сайте ведутся технические работы".
В некоторых случаях, необходимо показать пользователю само сообщение об ошибке. Оно хранится в узле ErrorDescription и приходит уже с переводом для языка, который указан при запросе в параметре 'language'.
Старт приложения
При старте приложения, необходимо получить настройки приложения: http://docs.otapi.net/ru/Documentations/Method?name=GetCommonInstanceOptionsInfo с передачей параметра applicationType=MobileApplication.
Из настроек, приложение должно получить список доступных языков, и предоставить пользователю интерфейс по выбору языка приложения (если язык не один в списке). Далее все запросы к api вызываются с этим языком.
Список успешно полученных настроек необходимо кэшировать. Обновлять кэш настроек стоит в фоновом режиме, не замедляя этим запросом работу приложения. Обновлять кэш в фоне стоит или раз в N часов или при каждом старте приложения. Настройки одни на всё приложение и не различаются для разных пользователей.
Мобильное приложение при первом запуске должно запросить у пользователя разрешение на получение push-уведомлений. Если пользователь согласился получать push-уведомления, необходимо отправить push-токен приложения в сервисы http://docs.otapi.net/ru/Documentations/Method?name=SetUserPushNotificationToken. В будущем, приложение должно следить за актуальностью push-токена и при необходимости обновлять его.
Получение сессии (авторизация пользователя)
Работа с пользователем - основные моменты
Часть методов otapi требует параметр сессии покупателя. Перед тем как работать с логикой для пользователей, необходимо получить сессию покупателя. Покупатель может быть авторизован в приложении, тогда приложение создает так называемую анонимную сессию для пользователя (запрос http://docs.dev.otapi.net/ru/Documentations/Method?name=GetAnonymousSession) и сохраняет эту сессию в памяти приложения. Если пользователь прошел процесс авторизации, то нужно сохранить в память новую сессию, которую приложение получит от сервисов в ответ на авторизацию.
Все методы, для работы с пользователем могут вернуть ошибку SessionExpired, в таком случае необходимо предложить пользователю авторизоваться и повторить свои действия.
Получение анонимной сессии
Регистрация
Регистрация пользователей осуществляется методом http://docs.otapi.net/ru/Documentations/Method?name=RegisterUser
Перед вызовом этого метода нужно выполнить проверку входных данных:
- Email, Login, Password - обязательные параметры
- Длина строки Password не менее 6 символов
- Строка с Email действительно является email адресом
На форме регистрации должно быть дополнительное обязательное поле-флаг "Я принимаю пользовательское соглашение", без этого флага не давать выполнить регистрацию.
После успешной регистрации методом RegisterUser проверить в ответе поле Result->IsEmailVerificationUsed. Если IsEmailVerificationUsed = "true" то показать пользователю сообщение "Для активации учетной записи Вам на почту было выслано письмо со ссылкой на активацию". Если IsEmailVerificationUsed = "false" нужно сразу авторизовать пользователя (установить для него новый SessionId полученный в ответ от сервисов).
Активация после регистрации
Вместе с сообщением про то что было отправлено письмо, нужно вывести поле ввода кода активации. Когда пользователь проверит почту, введет код в приложении, нужно вызвать http://docs.otapi.net/ru/Documentations/Method?name=ConfirmEmail. В ответе ConfirmEmail есть поле Result->SessionId->Value которое содержит сессию авторизованного пользователя. На основе этой сессии нужно сразу авторизовать пользователя в приложении.
Авторизация
Авторизация пользователей осуществляется методом http://docs.otapi.net/ru/Documentations/Method?name=Authenticate
На форме авторизации должно быть поля логин(userLogin), поле пароль(userPassword) и флаг запомнить(rememberMe). Перед вызовом метода Authenticate нужно выполнить проверку входных данных:
- userLogin, userPassword - обязательные параметры
Параметр sessionId в методе Authenticate - идентификатор сессии не авторизованного покупателя.
В качестве userLogin может быть передан не только логин, но и email пользователя, возможно стоит как-то подсказать это в интерфейсе.
Авторизация через социальные сети
Авторизация через соцсети (OT API)
Восстановление пароля
Восстановление пароля осуществляется методом http://docs.otapi.net/ru/Documentations/Method?name=RequestPasswordRecovery
Поле userIdentifier может содержать логин или email пользователя. После вызова RequestPasswordRecovery показать пользователю сообщение "На Ваш email высланы дальнейшие инструкции" и отобразить форму с кодом подтверждения и двумя текстовыми полями для ввода пароля. Пользователь смотрит код в почте, возвращается в приложение, вводит код и новый пароль. Если оба поля с паролем совпадают, далее нужно вызвать http://docs.otapi.net/ru/Documentations/Method?name=ConfirmNewPassword. В ответе ConfirmNewPassword есть поле Result->SessionId->Value которое содержит сессию авторизованного пользователя. На основе этой сессии нужно сразу авторизованного пользователя в приложении.
Проверка актуальности сессии
Если любой метод, использующий сессию пользователя, вернул ошибку SessionExpired, это означает что сессия истекла или анонимна. В этом случае нужно перекинуть пользователя снова на авторизацию с соответствующим сообщением, а когда новая сессия будет успешно получена, вернуть пользователя в то место, где возникла ошибка.
Принудительно проверить сессию проще всего методом http://docs.otapi.net/ru/Documentations/Method?name=GetUserStatusInfo. Он наименее затратен по времени среди всех.
Главная страница приложения
Получение подборок
Для получения подборок, используем метод http://docs.otapi.net/ru/Documentations/Method?name=BatchSearchRatingLists . При первом запросе передаем параметры:
<BatchRatingListSearchParameters><UseDefaultParameters>true</UseDefaultParameters></BatchRatingListSearchParameters>
и параметр applicationType=MobileApplication. В полученных данных для каждой подборки имеется порядковый номер для сортировки <Order>0</Order> , нужно отобразить на экране приложения подборки согласно этой сортировке.
Рекомендуется показывать подборки покупателю только из кэша. В кэше подборки необходимо обновлять в фоновом режиме: раз в 60 минут запрашивать метод BatchSearchRatingLists и сохранять результат в кэш. При получении ответа, нужно проверить узел HasTranslateErrors (http://docs.dev.otapi.net/ru/Documentations/Type?name=BatchRatingListsSearchResultAnswer), если узел равен "true", то кэшировать ответ ну нужно. Для каждого элемента RatingList в ответе необходимо проверить узел HasError (http://docs.dev.otapi.net/ru/Documentations/Type?name=RatingListSearchResult), если узел равен "true", то этот элемент подборки кэшировать не нужно.
Таким образом получаем ситуацию, когда покупатель видит подборки, которые находятся в кэше. При этом подборки в кэше не имеют ошибок. Возможна ситуация когда мы показываем пользователю устаревшую информацию, при этом мы уверены что эта информация без ошибок.
Получение баннеров
TODO:
Короткое меню категорий
TODO:
Социальные сети
TODO:
Предпочтения пользователя
- Валюты. Список доступных валют необходимо показать из настроек приложения GetCommonInstanceOptionsInfo узел Currencies.
- Страна доставки. Список доступных стран необходимо показать из настроек приложения GetCommonInstanceOptionsInfo узел DeliveryCountries. Список стран необходимо отображать с учетом текущего языка приложения (все переводы можно найти в узле TranslatableOptions).
Покупатель может иметь ряд предпочтений-настроек, от которых зависят в будущем ответы otapi или поведение системы/приложения.
Получить текущие выбранные предпочтения можно с помощью метода http://docs.otapi.net/ru/Documentations/Method?name=GetUserPreferences
Изменить предпочтение пользователя можно с помощью метода http://docs.otapi.net/ru/Documentations/Method?name=UpdateUserPreferences
Интерфейс приложения должен предоставить пользователю возможность изменять свои предпочтения.