Customise the Android SDK

Learn how to customise your mobile authorisation UI to match the look and feel of your brand.

🚧

v3 is the latest version of the Android SDK

Use our migration guide to ensure that you're up to date. Check our Github to find the latest version of the Android SDK.

Style the Android SDK user interface

You can manually customise the colours and typography of the Android SDK. The process depends on the integration type you chose to set up payments and mandates.

The table below explains the different values that you can change, and which UI elements they affect.

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 a full list of colours that you can override, see the details of androidx.compose.material.Colors in the Android reference documentation.

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
)

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.

1. Add the Compose Material 3 library

// Add to your projects `build.gradle`.
implementation "androidx.compose.material3:material3:1.1.2"

2. Update the names of colours and typography styles to override by following the migration guide on the Material Design blog.
3. To override shapes, replace androidx.compose.material.Shapes with androidx.compose.material3.Shapes.

Style your Android Activity or AndroidX Activity integration

🚧

Using a Material theme?

Starting from 21 February 2024, you will need to migrate to Android 3.0.1 to ensure that your UI looks consistent between your app and your payment authorisation flow.

For more on how to do this, see Migrate to Android SDK 3.0.1.

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 to Android SDK 3.0.1

To use version 3.x.x of the SDK, you must integrate with Compose to customise your app UI. You can no longer use XML files to do this.

You can integrate without migrating your app to Compose. Here's how:

1. Enable Compose in your project by adding the code snippet below to the android block in your app-level build.gradle file.

buildFeatures {
    compose = true
}

composeOptions {
    kotlinCompilerExtensionVersion = "1.5.4"
}

2. Add the following dependencies to your build.gradle file:

implementation("androidx.activity:activity-compose:$latest-version")
implementation("androidx.compose.material3:material3")

3. Follow the steps for the Compose integration.
4. For a full list of customisation options, read the Compose customisation guide.

Migrate to Android SDK v2

🚧

v3 is the latest version of the SDK

Go straight to the migration guide for v3.

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 payments 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:

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), you must make sure that your project has desugaring enabled. 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 updated:

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