Customise the Android SDK
Personalise the look and feel of the Android SDK, and migrate to the latest version.
Learn how to customise your mobile authorisation UI to match the look and feel of your brand.
You may also want to migrate from an earlier version of the SDK: you can find information about the requirements here.
Style the Android SDK user interface
You can customise the colours and typography of integration. The process depends on the integration type you chose to set up payments and mandates.
Style your Jetpack Compose integration
When integrating via Jetpack Compose, to change colours or typography you have to provide your own version of LightColorDefaults
, DarkColorDefaults
and TypographyDefaults
. You can use .copy()
to override just a single colour.
For example, define your theme as below, and include it within your Jetpack Compose code to process payments or mandates.
TrueLayerTheme(
lightPalette = LightColorDefaults.copy(primary = Color.Red),
darkPalette = DarkColorDefaults.copy(primary = Color.DarkGray),
typography = TypographyDefaults
)
To find a full list of colours you can override, see the details of androidx.compose.material.Colors
in the Android reference documentation.
Material You
The SDK supports Material You and dynamic colours. This can be enabled when creating a theme as below:
TrueLayerTheme(
lightPalette = LightColorDefaults.copy(primary = Color.Red),
darkPalette = DarkColorDefaults.copy(primary = Color.DarkGray),
dynamicColorsEnabled = true
)
Material 3 migration
The SDK now also uses Material 3 components and themes. If you're using Material 2, to customise the theme of the SDK you'll need to make the following changes.
- Add the Compose Material 3 library
// Add to your projects `build.gradle`.
implementation "androidx.compose.material3:material3:1.0.0-alpha15"
- Update the names of colours and typography styles to override by following the migration guide on the Material Design blog.
- To override shapes, replace
androidx.compose.material.Shapes
withandroidx.compose.material3.Shapes
.
When the theme is not explicit
You may choose to integrate the SDK using Theme
without parameters, like this:
setContent {
Theme {
Processor(
...
)
}
}
In this case the SDK reads all styles from the Context
of the enclosing Activity. Ensure that the enclosing activity style is based on the NoActionBar
variant.
Style your Android Activity or AndroidX Activity integration
When integrating via Android Activity or AndroidX Activity, you can define styles of the SDK views using XML files. You need to override style TrueLayerPaymentsTheme
as this is used by the SDK to style internal Activities. To do this, define the style in your theme.xml
file.
<style name="TrueLayerPaymentsTheme" parent="TrueLayerPaymentsParentTheme">
<!-- Primary brand color. -->
<item name="colorPrimary">@android:color/holo_red_light</item>
<item name="colorPrimaryVariant">@android:color/holo_red_dark</item>
<!-- Text colors -->
<item name="android:textColorPrimary">@color/textColorPrimary</item>
<item name="android:textColorSecondary">@color/textColorSecondary</item>
<!-- Status bar -->
<item name="android:statusBarColor">?attr/colorPrimary</item>
<item name="android:windowLightStatusBar" tools:targetApi="m">true</item>
</style>
Although you can set your application theme as a parent, we recommend you use the TrueLayerPaymentsParentTheme
as your parent
to remain up to date with any SDK updates. If you're using your application theme, ensure that the parent of the TrueLayerPaymentsTheme
is the NoActionBar
variant.
Remember to assign this style to your activity in the AndroidManifest.xml
file.
<activity android:name=".screens.examples.ActivityXIntegration"
android:theme="@style/TrueLayerPaymentsTheme"/>
Migrate from Android SDK v1 to v2
Migrating from version 1.x.x of the SDK
If you're migrating to version 2.x.x from version 1.x.x of the SDK, you need to update your project for the following changes:
If you were processing a payment with a Jetpack Compose integration, remove the following code from your activity hosting. This code was required in previous versions, but will now cause user interface issues.
WindowCompat.setDecorFitsSystemWindows(window, false)
@Suppress("DEPRECATION")
window.setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE)
There are some naming changes. The classes and functions that have been moved are listed in the table below:
Original | New location |
---|---|
com.truelayer.payments.ui.models.PaymentContext | com.truelayer.payments.ui.screens.processor.ProcessorContext.PaymentContext |
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorResult | com.truelayer.payments.ui.screens.processor.ProcessorResult |
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorActivityContract | com.truelayer.payments.ui.screens.processor.ProcessorActivityContract |
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorActivity | com.truelayer.payments.ui.screens.processor.ProcessorActivity |
com.truelayer.payments.ui.screens.coordinator.FlowCoordinator | com.truelayer.payments.ui.screens.processor.Processor |
com.truelayer.payments.ui.models.PaymentUseCase | com.truelayer.payments.ui.screens.processor.PaymentUseCase |
com.truelayer.payments.ui.models.PaymentContext.Preferences | com.truelayer.payments.ui.screens.processor.ProcessorContext.PaymentPreferences |
PaymentContext.paymentId | PaymentContext.id |
The SDK now uses Kotlin version 1.7.0
, SDK version 26
at minimum. Previously the minimum SDK version was 24
.
The SDK has removed its dependency on com.google.android.material:material
, replacing it with androidx.compose.material3:material3
. The dependency on com.google.accompanist:accompanist-insets
has also been removed.
Migrating to version 2.3.0 of the SDK
For version 2.3.0 of the SDK, we've extended Android compatibility to Android 5.0+ (API level 21+). If your app supports Android 8.0 or below (API level 26) then when updating to version 2.3.0, you must make sure that your project has desugaring enabled. This is important because without desugaring, in specific scenarios, the SDK may crash on devices running Android below API level 26. The SDK is using version 1.2.2 of the desugaring library.
The following code example can help you to enable desugaring in your project.
android {
...
compileOptions {
coreLibraryDesugaringEnabled true
}
...
}
dependencies {
...
coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:1.2.2"
...
}
In addition, the following dependencies have been update:
Updated Kotlin version:
- Kotlin 1.7.0 -> 1.7.20
Updated tools:
- Android Build Tools 30.0.3 -> 33.0.2
- protobuf gradle version -> 0.9.1
- com.android.tools.build:gradle 7.4.1 -> 7.4.2
- gradle wrapper 7.5 -> 8.0.2
Updated libraries:
- androidx.work:work-runtime-ktx: 2.7.1 -> 2.8.0
- androidx.compose.ui:ui-tooling: 1.3.0 -> 1.3.3
- androidx.compose.ui:ui-tooling-preview: 1.3.0 -> 1.3.3
- androidx.compose.ui:ui 1.3.0 -> 1.3.3
- androidx.compose.material:material-icons-core 1.3.0 -> 1.3.1
- compose_compiler version 1.2.0 -> 1.3.2
- compose_theme_adapter 1.0.18 -> 1.1.1
- org.jetbrains.kotlinx:kotlinx-coroutines-android 1.6.3 -> 1.6.4
- org.jetbrains.kotlinx:kotlinx-coroutines-core 1.6.3 -> 1.6.4
- androidx.appcompat:appcompat 1.6.0-rc01 -> 1.6.1
- androidx.fragment:fragment-ktx 1.5.4 -> 1.5.5
- com.google.android.material:material 1.8.0-alpha02 -> 1.8.0
- androidx.compose.material:material-icons-core 1.8.0-alpha02 -> 1.8.0
- androidx.compose.material:material-icons-extended 1.8.0-alpha02 -> 1.8.0
- androidx.compose.material3:material3 1.0.0 -> 1.0.1
- com.google.protobuf:protobuf-javalite 3.20.0 -> 3.21.12
- com.google.protobuf:protoc 3.20.0 -> 3.21.12
- androidx.room:room-runtime 2.4.3 -> 2.5.0
- androidx.room:room-ktx 2.4.3 -> 2.5.0
- androidx.room:room-compiler 2.4.3 -> 2.5.0
- androidx.work:work-runtime-ktx 2.7.1 -> 2.8.0
- androidx.work:work-multiprocess 2.7.1 -> 2.8.0
Updated 6 months ago