Подробная инстуркция по конфигурации и настройке SDK от Travelpayouts для Android.
Подключение SDK
После получения доступа к репозиторию SDK для скачивания будут доступны следующие файлы:
1. .gitignore
2. build.gradle.kts
3. travel-sdk-release.aar
Их необходимо подключить в качестве Android Library модуля, как зависимость:
1. В файл build.gradle App модуля, либо того модуля в котором планируется использовать SDK, добавьте implementation(project(":travel-sdk")).
2. В файл settings.gradle добавьте (include(:travel-sdk")).
Инициализация SDK
Для использования TravelSDK необходимо выполнить инициализацию в вашем приложении. Инициализация SDK производится один раз при запуске приложения и выполняется в классе Application в методе onCreate().
```
// Конфигурация SDK
val config = SdkConfig(
marker = "<marker>", // String. Персональный маркер в системе Travelpayouts
apiKey = "<apiKey>" // String. Ключ API для доступа к функциям SDK
)
// Инициализация SDK
TravelSdk.init(
context = this, // Контекст приложения
config = config // Предварительно созданная конфигурация
)
```
- В поле marker укажите ваш партнёрский маркер Travelpayouts. Его можно скопировать на странице White Label App в личном кабинете Travelpayouts:
- В поле apiKey укажите ваш API токен. Его также можно найти на странице White Label App в личном кабинете Travelpayouts:
Использование экранов SDK
После инициализации вам станут доступны следующие экраны для взаимодействия с различными частями SDK (доступны в классе TravelSdk.Screen):
- FLIGHTS: Экран для поиска и бронирования авиабилетов.
- HOTELS: Экран для поиска и бронирования отелей.
- INFO: Экран с информацией и настройками SDK.
Каждый из этих экранов предоставляет удобный пользовательский интерфейс для соответствующих функций и может быть вызван из любой части вашего приложения.
Открытие экрана осуществляется путем вызова метода:
```
TravelSdk.showScreen(context, TravelSdk.Screen)
```
Вспомогательные экраны
Если вы хотите создать собственные стартовые экраны поиска авиабилетов и отелей, вы можете использовать готовые вспомогательные экраны для выбора дат, локаций и т.д.
- HotelsLocationsFragment – Экран для отображения выбора параметров локации отеля.
- HotelsCalendarFragment – Экран для отображения выбора дат бронирования отеля.
- HotelsGuestsFragment – Экран для отображения выбора параметров по гостям.
- FlightsLocationsFragment – Экран для отображения выбора параметров локации аэропорта.
- FlightsCalendarFragment – Экран для отображения выбора дат полёта.
- FlightsPassengersFragment – Экран для отображения выбора параметров по пассажирам.
Открытие экранов и получение осуществляется при помощи Activity Result API.
Для открытия конкретного экрана выбора параметров зарегистрируйте ActivityResultLauncher, с определённым контрактом под конкретный параметр.
Все контракты лежат в папке com.travelapp.sdk.unlimited.activity.filter.contract.
В качестве Result приходит один из стартовых параметров для начала поиска по билетам или отелям.
Пример:
```kotlin
private val hotelsCalendarLauncher = registerForActivityResult(
GetHotelsCalendarSelection()
) { result ->
// get result here
}
```
Контракты, которые нужно передать в метод registerForActivityResult, для получения стартовых параметров поиска:
- GetHotelsLocationsSelection – в result передаётся HotelLocationsSelection.
- GetHotelsCalendarSelection – в result передаётся HotelDates.
- GetHotelsGuestsSelection – в result передаётся GuestsInfo.
- GetFlightsLocationsSelection – в result передаётся FlightsLocationSelection.
- GetFlightsCalendarSelection – в result передаётся FlightDates.
- GetFlightsPassengersInfoSelection – в result передаётся PassengersInfo.
При дальнейшем вызове этого launcher мы должны будем передать экран выбора стартовых параметров поиска в метод launch (если потребуется с начальными параметрами):
```kotlin
hotelsCalendarLauncher.launch(SelectionFragment.HotelsCalendarFragment(periodDates))
```
Запуск поиска авиабилетов или отелей
После выбора соответствующих начальных параметров предоставляется метод для отображения экрана с результатами поиска, на которые были применены выбранные параметры (метод доступен в классе TravelSdkUnlimited):
- TravelSdkUnlimited.showHotelsSearchResultScreen() – показывается экран результатов поиска отелей.
- TravelSdkUnlimited.showFlightsSearchResultScreen() – показывается экран результатов поиска авиабилетов.
В методы требуется передать необходимые для старта поиска параметры.
Дополнительно
Для некоторых моделей предусмотрены значения по умолчанию, которые можно использовать без обращения к SDK. Эти значения можно получить, вызвав статические методы соответствующих классов:
- GuestsInfo.getDefaultGuestsInfo() — возвращает модель пассажира с одним взрослым билетом эконом-класса.
- PassengersInfo.getDefaultPassengersInfo() — возвращает модель гостя отеля с номером для одного взрослого человека эконом-класса.
Эти модели можно использовать для предустановки выбора на ваших экранах.
В случае, когда пользователь выбирает один и тот же город в качестве отправления и прибытия, рекомендуется блокировать возможность начала поиска, чтобы избежать отображения ошибки. Для этого предусмотрен extension-метод LocationInfo?.isNotSameLocation(otherLocation: LocationInfo?). Если метод возвращает значение false, рекомендуется отключить кнопку поиска отелей, установив её состояние как disable:
```kotlin
btnFilterFlights.isEnabled =
flightsLocationSelectionDeparture?.locationInfo
.isNotSameLocation(
flightsLocationSelectionArrival?.locationInfo
)
```
Конфигурация
С помощью SdkConfig можно настроить следующие параметры sdk:
-
icons — тип иконок на экранах sdk.
Доступные значения:- default (значение по умолчанию)
- tint
- sharp
-
cornerType — тип скруглений элементов интерфейса на экранах sdk.
Доступные значения:- default (значение по умолчанию)
- sharp
- round
- flightsFavoritesEnabled (boolean) — флаг включения функции избранного для авиабилетов, по умолчанию false.
- hotelsFavoritesEnabled (boolean) — флаг включения функции избранного для поиска отелей, по умолчанию false.
- enabledInfoItems — список включённых пунктов на экране информации/настроек, по умолчанию emptySet().
- appVersion (string) — строка версии приложения для передачи на экран «О приложении».
- email (string) — адрес почты для раздела «Cвязаться с нами».
- advertising — настройки рекламных идентификаторов.
- sharingLink (string) — host для подстановки в ссылку «Поделиться».
- handlingLink (string) — host для перехвата ссылок в приложение.
- appsflyerDevKey (string) — ключ для доступа к AppsFlyer.
Иконки
Вы можете заменить базовые иконки в своем приложении на собственные.
Чтобы переопределить конкретную иконку, разместите свою версию иконки в папке drawable в ресурсах вашего приложения. Название файла иконки должно соответствовать определенному паттерну, который зависит от ранее выбранной конфигурации вашего проекта:
- ta_ic_default_{iconName} — для конфигураций IconsType.FILLED и CornerType.DEFAULT/CornerType.ROUND.
- ta_ic_default_line_{iconName} — для конфигураций IconsType.LINE и CornerType.DEFAULT/CornerType.ROUND.
- ta_ic_default_tint_{iconName} — для конфигураций IconsType.TINT и CornerType.DEFAULT/CornerType.ROUND.
- ta_ic_sharp_{iconName} — для конфигураций IconsType.FILLED и CornerType.SHARP.
- ta_ic_sharp_line_{iconName} — для конфигураций IconsType.LINE и CornerType.SHARP.
- ta_ic_sharp_tint_{iconName} — для конфигураций IconsType.TINT и CornerType.SHARP.
Замените {iconName} на название иконки, которую вы хотите переопределить.
Замена текстовых строк на экране
Замена текстовых строк выполняется путём переопределения ключей. Примеры ключей строк для разных языков можно посмотреть здесь. Вот так выглядят ключи для немецкого языка:
Чтобы заменить текстовую строку, необходимо в строковых ресурсах своего приложения добавить строчку с новым значением, но с таким же ключом, после чего она переопределится и будет использоваться то значение, которое указали вы.
Фоновые изображения
Фоновые изображения на экранах поиска рейсов и отелей можно заменить, переопределив изображение ta_img_default_background в ресурсах вашего приложения.
Генератор цветовой палитры для SDK
Чтобы быстро настроить цветовую палитру в приложении, достаточно указать основной цвет вашего бренда (primary). Генератор автоматически создаст вспомогательные цвета на его основе. Для изменения отдельных цветов используйте инструкции из раздела Цвета.
Установка и использование генератора
Для подключения плагина добавьте его в classpath в build.gradle уровня проекта:
#### Groovy
```groovy
buildScript {
dependencies {
classpath 'com.travelapp.gradle:colorsgenerator:1.0.0'
}
}
```
#### Kotlin
```kotlin
buildScript {
dependencies {
classpath("com.travelapp.gradle:colorsgenerator:1.0.0")
}
}
```
Далее примените плагин в build.gradle app модуля:
#### Groovy
```groovy
plugins {
id 'com.travelapp.gradle.colorsgenerator'
}
```
#### Kotlin
```kotlin
plugins {
id("com.travelapp.gradle.colorsgenerator")
}
```
Настройка плагина выполняется через блок colorsGenerator в build.gradle:
```groovy
colorsGenerator {
baseColor = "#69BFAA"
method = "lab"
}
```
Параметры:
- baseColor — базовый цвет в HEX формате (#RRGGBB).
- method — цветогенерация на основе цветового пространства hsv или lab.
Возможные значения:
- hsv — данный алгоритм цветогенерации за базовый цвет берет значение baseColor изменяя у него параметры Saturation и Value.
- lab — данный алгоритм цветогенерации за базовый цвет берет значение baseColor изменяя у него параметр Lightness для темной и светлой тем. (Данный алгоритм выставляет Lightness основного цвета в середину диапазона, что может привести к несоответствию с вашим фирменным цветом).
Цвета
Замена цветов в приложении выполняется путем переопределения ключей цветов в ресурсах.
В Android-приложениях по умолчанию можно переопределять любые используемые ресурсы, создав новый ресурс с таким же названием, как у оригинала.
Чтобы изменить цвета в SDK, добавьте новый ресурс в файл colors.xml (или в любое другое место, где хранятся цвета) по пути [YOUR_PROJECT]/app/src/main/res/values. В качестве ключа укажите название оригинального цвета, а в качестве значения — новый HEX-код нужного цвета
Названия цветов можно посмотреть в файле.