Общая работа с OTApi
Все методы можно увидеть на странице с документацией: http://docs.otapi.net/
Для получения ответа от api в формате xml нужно отправить или POST или GET запрос на адрес http://otapi.net/OtapiWebService2.asmx/
Для получения ответа от api в формате json нужно отправить или POST или GET запрос на адрес http://otapi.net/service-json/
В ответе от 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-токена и при необходимости обновлять его.
Регистрация
Регистрация пользователей осуществляется методом http://docs.otapi.net/ru/Documentations/Method?name=RegisterUser
Перед вызовом этого метода нужно выполнить проверку входных данных:
1. Email, Login, Password - обязательные параметры
2. Длинна строки Password не менее 6 символов
3. Строка с 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=GetUserStatusInfo.
Авторизация
Авторизация пользователей осуществляется методом http://docs.otapi.net/ru/Documentations/Method?name=Authenticate
Перед вызовом этого метода нужно выполнить проверку входных данных:
1. userLogin, userPassword - обязательные параметры
Восстановление пароля
Восстановление пароля осуществляется методом 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 которое содержит сессию авторизованного пользователя. На основе этой сессии нужно сразу залогинить пользователя в приложении, прочую информацию о пользователе можно получить методом 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
Интерфейс приложения должен предоставить пользователю возможность изменять свои предпочтения.