Documentation for the Lune PFM Android SDK

Requirements

• Android Studio Arctic Fox (2020.3.1) or later
• Kotlin 1.5.10 or later
• Minimum Android API level 21 (Android 5)
• Lune SDK (AAR) file

Installation

There are two options to install the LuneSDK. Follow the instructions below for any of the options you prefer:

• ☁️ Maven Central
• 📦 Manually - using the AAR file

1. Maven Central

To install the LuneSDK into your project from Maven Central:

// Lune SDK
implementation("io.lunedata.lunesdk:lunesdk:$luneSdkVersion")

2. Manually - using the AAR file

You can also add the LuneSDK to your project manually, using the raw aar file.To do so:

// Lune SDK
implementation(files("libs/lunesdk-release.aar"))

implementation("androidx.compose.material:material:1.5.4")
implementation("com.squareup.retrofit2:retrofit:2.9.0")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2")
implementation("com.jakewharton.retrofit:retrofit2-kotlinx-serialization-converter:0.8.0")
implementation("com.squareup.okhttp3:okhttp:4.9.3")
implementation("com.squareup.okhttp3:logging-interceptor:4.9.3")
implementation("androidx.lifecycle:lifecycle-runtime-compose:2.6.2")
implementation("androidx.navigation:navigation-compose:2.6.0")
implementation("androidx.compose.material3:material3:1.2.0-alpha02")
implementation("io.coil-kt:coil-compose:2.3.0")
implementation("com.google.accompanist:accompanist-flowlayout:0.20.0")
implementation("androidx.activity:activity-ktx:1.7.2")
implementation("com.google.android.material:material:1.9.0")

Initialization

To initialize the SDK, you simply have to create an instance of LuneSDKManager  that would be used across your app.

Provided that you will need to initialize LuneSDK with credentials, you may want to do all the prep work within a view-model. That includes things like:

• Getting the credentials
• Setting up a refresh callback (optional, based on the TTL of your credentials)
• Setting up logging (also optional)

You can find specific implementation details for your project setup below:

• 🚀 Jetpack Compose
• 💠 Activities and Fragments

1. Jetpack Compose

Follow the steps below to initialize LuneSDK in your Jetpack Compose Project.

1. Initialize SDK: In your MainActivity, initialize the LuneSDKManager in the onCreate() method:

// MainActivity.kt
class MainActivity : ComponentActivity() {

    private lateinit var luneSDK: LuneSDKManager

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Initialize the SDK manager
        luneSDK = LuneSDKManager(
            baseUrl = "",           // Base URL
            token = "",             // User access token
            customerId = id,        // Customer ID
            refreshTokenCallback = TokenRefresher() // Callback for token refresh
        )

        // Set up the UI using Jetpack Compose
        setContent {
            LuneBankTheme {
                Surface(modifier = Modifier.fillMaxSize()) {
                    RootComposable(luneSDK)
                }
            }
        }
    }
}

2. Using SDK in Composable: Pass the LuneSDKManager instance to any composable in your app:

@Composable
fun TransactionView(luneSDK: LuneSDKManager) {
    // Use the SDK
    luneSDK.TransactionListComponent()
}

💡 Tip:  
‍
While you could create multiple instances of LuneSDKManager, we recommend creating just one instance per app. You could share that single instance with other views by passing it around.

2. Activities and Fragments

Follow the steps below to initialize LuneSDK in your Activities and Fragments Project.

1. Add Lune View to Layout: In your layout file, include the Lune view by specifying its fully qualified class name:

<!-- YourLayoutFile.xml -->
<io.lunedata.lunesdk.library.classes.LuneCompatManager
    android:id="@+id/luneLayout"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    <!-- other attributes -->
/>

2. Initialize SDK in Code: In your Activity or Fragment, create and initialize an instance of LuneSDKManager with the required credentials:

// YourActivity.kt
private lateinit var luneSDK: LuneSDKManager

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Initialize the SDK manager
    luneSDK = LuneSDKManager(
        baseUrl = "",           // Base URL
        token = "",             // User access token
        customerId = id,        // Customer ID
        refreshTokenCallback = TokenRefresher() // Callback for token refresh
    )

    // Optionally set up the callback later
    luneSDK.setupRefreshCallback(TokenRefresher())

    // Configure the Lune view
    val luneView = findViewById<LuneCompatManager>(R.id.luneLayout)
    luneView.manager = luneSDK
    luneView.component = LuneView.ActivityComponent
}

Refresh Token Callback

The refresh token callback is a critical component for managing user authentication tokens. It handles the situation where the user's access token expires and needs to be refreshed.

Implementation:
The callback function is implemented in the TokenRefresher class, which you can customize based on your app's needs:

class TokenRefresher: RefreshTokenCallback {
    override fun refreshToken(): String? {
    // Implement logic to refresh the token and obtain a new access token

     return "" // make sure to return the token here  
    }
}

Usage:‍

• Activities and Fragments:
  The TokenRefresher class is passed as a parameter to the LuneSDKManager during initialization. It can also be set up later using the setupRefreshCallback() method.
  
  ‍
• Jetpack Compose:
  The TokenRefresher class is used in the same way as in Activities and Fragments, ensuring a unified approach across different integration methods
  ‍

Example:

// Setting up the callback during initialization
luneSDK = LuneSDKManager(
    baseUrl = "",           // Base URL
    token = "",             // User access token
    customerId = id,        // Customer ID
    refreshTokenCallback = TokenRefresher() // Callback for token refresh
)

// Setting up the callback later
luneSDK.setupRefreshCallback(TokenRefresher())

This unified approach to implementing the refresh token callback ensures consistency across different integration methods, simplifying the token management process within your application.

Optional

1. To allow buttons to float above the keyboard, add the following attribute in your AndroidManifest.xml file:

<activity android:windowSoftInputMode="adjustResize">
    <!--this allows buttons to float above the keyboard-->
</activity>

Customization

• 📚 Localization and Strings
• 🌄 Images

The SDK has lots of configurable parameters which can be overridden by setting up a JSON file with a schema similar to the one attached below. You could just download the file and modify the values you wish to change.

Once edited, save the JSON file as lune_config.json and place it in the /res/raw directory of your Android project. The final path should be /res/raw/lune_config.json.

1. Localization and Strings

If your app is already localized, the SDK would be localized as well - no configurations needed. If your app is not localized, however, the SDK respects that and stays in English to preserve consistency and uniformity across your app.

String Overrides

You can override specific strings by assigning a different value to the same string keys used by the SDK.

The strings used in the SDK can be found in the localization file attached below.

As you may have noticed, the keys are unique and should not conflict with any other strings in your project.

2. Images

You can override any of the images in LuneSDK by simply giving any other images in your project the exact same name.
‍
Each image is named using the format:

lune_asset_<image_name>

You can find a list of the images you can override here:

Components

The Lune SDK components are broadly divided into full-page views and smaller (mix and match) components.

Full page views

These components are typically large and were designed to be used as stand-alone components on a page. While you could still choose to do so, we strongly discourage adding other widgets as siblings to full page views.
‍

Examples are:

Smaller (mix and match) Components

These components are usually small enough and could easily be arranged as siblings of other widgets on a page.


Examples are: