Detailed insturction on how to configure and customize the Travelpayouts SDK for Android.
Connecting SDK to your project
After gaining access to the SDK repository, the following files will be available for download:
1. .gitignore
2. build.gradle.kts
3. travel-sdk-release.aar
These files need to be integrated as an Android Library module, as a dependency:
1. In the build.gradle file of the App module (or the module where you plan to use the SDK), add implementation(project(":travel-sdk")).
2. In the settings.gradle file, add: (include(:travel-sdk")).
SDK Initialization
To use SDK, you need to initialize it in your application. The SDK initialization is done once when the application starts and is performed in the Application class in the onCreate() method.
// SDK Configuration
val config = SdkConfig(
marker = "<marker>", // String. Personal marker in the Travelpayouts system
apiKey = "<apiKey>" // String. API key for accessing SDK features
)
// SDK Initialization
TravelSdk.init(
context = this, // Application context
config = config // Pre-created configuration
)
-
marker — insert your Travelpayouts ID. You can find it in your Travelpayouts account on the White Label App page:
-
apiKey — insert your API token to access flight tickets and hotels data. You can also find the API token in your Travelpayouts account on the White Label App page:
SDK Screens
After initialization, the following screens are available for interaction with various parts of the SDK (available in the TravelSdk.Screen class):
- FLIGHTS: Screen for searching and booking flights.
- HOTELS: Screen for searching and booking hotels.
- INFO: Screen with information and SDK settings.
Each of these screens provides a user-friendly interface for the respective functions and can be invoked from any part of your application.
To open a screen, call the method:
TravelSdk.showScreen(context, TravelSdk.Screen)
Parameter selection screens
If you want to create your own starting screens for flight and hotel searches, you can use the pre-built screens for selecting dates, locations, etc.
- HotelsLocationsFragment – A screen for selecting hotel location parameters.
- HotelsCalendarFragment – A screen for selecting hotel booking dates.
- HotelsGuestsFragment – A screen for selecting guest parameters.
- FlightsLocationsFragment – A screen for selecting airport location parameters.
- FlightsCalendarFragment – A screen for selecting flight dates.
- FlightsPassengersFragment – A screen for selecting passenger parameters.
The screens are opened and results are obtained using the Activity Result API.
To open a specific parameter selection screen, register an ActivityResultLauncher with a specific contract for the desired parameter. All contracts can be found in the com.travelapp.sdk.unlimited.activity.filter.contract folder. The Result will be one of the starting parameters for initiating a flight or hotel search.
Для открытия конкретного экрана выбора параметров зарегистрируйте, с определённым контрактом под конкретный параметр.
Все контракты лежат в папке com.travelapp.sdk.unlimited.activity.filter.contract.
В качестве Result приходит один из стартовых параметров для начала поиска по билетам или отелям.
Example:
```kotlin
private val hotelsCalendarLauncher = registerForActivityResult(
GetHotelsCalendarSelection()
) { result ->
// get result here
}
```
Here is the list of contracts to pass to the registerForActivityResult method to obtain starting search parameters:
- GetHotelsLocationsSelection – returns HotelLocationsSelection.
- GetHotelsCalendarSelection – returns HotelDates.
- GetHotelsGuestsSelection – returns GuestsInfo.
- GetFlightsLocationsSelection – returns FlightsLocationSelection.
- GetFlightsCalendarSelection – returns FlightDates.
- GetFlightsPassengersInfoSelection – returns PassengersInfo.
When invoking this launcher later, you should pass the parameter selection screen to the launch method (if necessary, with initial parameters):
```kotlin
hotelsCalendarLauncher.launch(SelectionFragment.HotelsCalendarFragment(periodDates))
```
Launching a flight or hotel search
After selecting the initial parameters, a method is provided to display the search results screen with the applied parameters. The method is available in the TravelSdkUnlimited class:
- TravelSdkUnlimited.showHotelsSearchResultScreen() – displays the hotel search results screen.
- TravelSdkUnlimited.showFlightsSearchResultScreen() – displays the flight search results screen.
You need to pass the required parameters to these methods to start the search.
Additional Information
For some models, default values are provided that can be used without accessing the SDK. These values can be obtained by calling static methods of the respective classes:
- GuestsInfo.getDefaultGuestsInfo() – returns a guest model with one adult economy-class ticket.
- PassengersInfo.getDefaultPassengersInfo() – returns a hotel guest model with a room for one adult in economy class.
These models can be used for preset selections on your screens.
In cases where the user selects the same city as both the departure and arrival location, it is recommended to block the search to avoid showing an error. For this, the LocationInfo?.isNotSameLocation(otherLocation: LocationInfo?) extension method is provided. If the method returns false, it is recommended to disable the hotel search button by setting its state to disable:
```kotlin
btnFilterFlights.isEnabled =
flightsLocationSelectionDeparture?.locationInfo
.isNotSameLocation(
flightsLocationSelectionArrival?.locationInfo
)
```
Configuration
With SdkConfig, you can configure certain SDK parameters:
-
icons — the type of icons on the SDK screens.
Available values- default (selected by default)
- tint
- sharp
-
cornerType — the type of corner rounding for UI elements on the SDK screens.
Available values- default (selected by default)
- round
- sharp
- flightsFavoritesEnabled (boolean) — flag to enable the favorite feature for flights. Default value: false.
- hotelsFavoritesEnabled (boolean) — flag to enable the favorite feature for hotel searches. Default value: false.
- enabledInfoItems — list of enabled items on the information/settings screen. Default value: emptySet().
- appVersion (string) — application version string for the "About the app" screen.
- email (string) — email address for the "Contact us" section.
- advertising — advertising ID settings.
- sharingLink (string) — host for the "share" link substitution.
- handlingLink (string) — host for intercepting links in the application.
- appsflyerDevKey (string) — key for accessing AppsFlyer.
Icons
You can replace the default icons in your application with your own.
To override an icon, place your version of the icon in the drawable folder in your application's resources. The name of the icon file must follow a specific pattern, which depends on the previously selected configuration of your project:
- ta_ic_default_{iconName} — for IconsType.FILLED and CornerType.DEFAULT/CornerType.ROUND configurations.
- ta_ic_default_line_{iconName} — for IconsType.LINE and CornerType.DEFAULT/CornerType.ROUND configurations.
- ta_ic_default_tint_{iconName} — for IconsType.TINT and CornerType.DEFAULT/CornerType.ROUND configurations.
- ta_ic_sharp_{iconName} — for IconsType.FILLED and CornerType.SHARP configurations.
- ta_ic_sharp_line_{iconName} — for IconsType.LINE and CornerType.SHARP configurations.
- ta_ic_sharp_tint_{iconName} — for IconsType.TINT and CornerType.SHARP configurations.
Replace {iconName} with the name of the icon you want to override.
Replacing text strings
String replacement is done by overriding string keys in the resources. You can see examples of string keys for different languages here. This is what the keys for German look like:
To replace a string, you need to add a line with a new value, but with the same key, in your application's string resources, and then it will override and use the value you specified.
Background Images
Background images on the flight and hotel search screens can be replaced by overriding the ta_img_default_background image in your application's resources.
Color palette generator for SDK
To set up a color palette in the application, just specify the primary color of your brand. The generator will automatically create auxiliary colors based on it. To change individual colors, use the instructions in the Colors section.
Installation and use
To connect the plugin, you need to add it to the classpath in the build.gradle of the project level:
#### Groovy
```groovy
buildScript {
dependencies {
classpath 'com.travelapp.gradle:colorsgenerator:1.0.0'
}
}
```
#### Kotlin
```kotlin
buildScript {
dependencies {
classpath("com.travelapp.gradle:colorsgenerator:1.0.0")
}
}
```
Next, apply the plugin in build.gradle app module:
#### Groovy
```groovy
plugins {
id 'com.travelapp.gradle.colorsgenerator'
}
```
#### Kotlin
```kotlin
plugins {
id("com.travelapp.gradle.colorsgenerator")
}
```
The plugin is configured via the colorsGenerator block in build.gradle:
```groovy
colorsGenerator {
baseColor = "#69BFAA"
method = "lab"
}
```
Parameters:
- baseColor — base color in HEX format (#RRGGBB).
- method — color generation based on hsv or lab color space.
Possible values:
- hsv — this color generation algorithm takes the baseColor value as the base color by changing its Saturation and Value parameters.
- lab — this color generation algorithm takes the baseColor value as the base color by changing its Lightness parameter for dark and light themes. (This algorithm sets the Lightness of the base color in the middle of the range, which may lead to inconsistency with your corporate color).
Colors
Color replacement in the app is done by overriding color keys in the resources. In Android apps, by default, you can override any used resource by creating a new resource with the same name as the original.
To change colors in the SDK, add a new resource to the colors.xml file (or any other location where colors are stored) at the path [YOUR_PROJECT]/app/src/main/res/values. Use the name of the original color as the key, and the new HEX code of the desired color as the value.
The color names can be found in the file.