Customise the Android SDK

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.

1. Add the Compose Material 3 library

// Add to your projects `build.gradle`.
implementation "androidx.compose.material3:material3:1.0.0-alpha15"

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.

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:

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