DEV Community: Vincent Tsen

Convert KAPT to KSP - Room and Hilt Examples

Vincent Tsen — Sat, 10 Feb 2024 01:07:31 +0000

Step-by-Step Guide: Migrating from KAPT to KSP for Room Database and Hilt Dependency Injection

KAPT stands for Kotlin Annotation Processing Tool and KSP stands for Kotlin Symbol Processing. Both are annotation-processing tools that are used for code generation.

KAPT is the old way which is Java-based and KSP is the new way which is Kotlin-based, and it builds (generates codes) a lot faster than the KAPT.

The 2 most common Android libraries that use them are Room Database and Hilt Dependency Injection. Let's explore the steps to convert these libraries from KAPT to KPT...

1. Update Kotlin version to minimum version "1.9.10"

In your project build.gradle file (Groovy example):

/*...*/
plugins {
    /*...*/
    id 'org.jetbrains.kotlin.android' version '1.9.10' apply false
    /*...*/
}
/*...*/

2. Add KSP Plugin to your build.gradle file

In your project build.gradle file (Groovy example):

/*...*/
plugins {
    /*...*/
    id 'com.google.devtools.ksp' version '1.9.10-1.0.13' apply false
    /*...*/
}
/*...*/

In your app build.gradle file (Groovy example), replace KAPT

 /*...*/
plugins {
    /*...*/
    id 'kotlin-kapt'
    /*...*/
}
/*...*/

with KSP plugin.

/*...*/
plugins {
    /*...*/
    id 'com.google.devtools.ksp'
    /*...*/
}
/*...*/

3. Replace KAPT configuraiton with KSP configuration

For example, you have the following kapt configuration in your app build.gradle to specify the room schema location.

/*...*/
android {
    /*...*/
    defaultConfig {
        /*...*/     
        kapt {
            arguments {
                arg("room.schemaLocation", "$projectDir/schemas")
            }
        }
        /*...*/
    }
    /*...*/
}
/*...*/

You convert it to KPT configuration as in the following.

/*...*/
android {
    /*...*/
    defaultConfig {
        /*...*/     
        ksp {
            arg("room.schemaLocation", "$projectDir/schemas")
        }
        /*...*/
    }
    /*...*/
}
/*...*/

4. Upgrade to Minimum Compose Compiler Version

Since the Kotlin version has been upgraded to version 1.9.10, it requires upgrading to the minimum compose compiler version of 1.5.3.

/*...*/
android {
    /*...*/
    composeOptions {
        kotlinCompilerExtensionVersion '1.5.3'
    }
    /*...*/
}
/*...*/

5. Replace annotation processor with KSP

Replace KAPT

/*...*/
dependencies {
    /* Room Example*/
    kapt "androidx.room:room-compiler:2.5.2"
    /* Hilt Example*/
    kapt "com.google.dagger:hilt-android-compiler:2.48"
    kaptAndroidTest "com.google.dagger:hilt-android-compiler:$hilt_version"
}
/*...*/

with KSP

/*...*/
dependencies {
    /* Room Example*/
    ksp "androidx.room:room-compiler:2.5.2"
    /* Hilt Example*/
    ksp "com.google.dagger:hilt-android-compiler:2.48"
    kspAndroidTest "com.google.dagger:hilt-android-compiler:$hilt_version"
}
/*...*/

Source Code

GitHub Repository: AndroidNews

Originally published at https://vtsen.hashnode.dev.

Equivalent Perforce Shelving Command in GitHub

Vincent Tsen — Sat, 02 Dec 2023 02:10:55 +0000

Let's explore git stash usages, which is equivalent to (not 100%) perforce shelving files concept

In Perforce, you can shelve files. The idea allows you to save your temporary changes (shelve files) and retrieve them later (unshelve files).

I'm a Perforce guy. So, I wonder what is the equivalent shelving files in GitHub? After doing some research, I think the equivalent Perforce shelving files command in GitHub is git stash.

git stash is Similar to Shelving Files

Well, it is not 100% equivalent. The key difference is git stash is purely local, while Perforce shelved files are in the server. Since it is local, you're the only one who can access the changes. If you want to share with others, you have to create a branch and commit your changes to the remote repository (this will not be covered in this article).

Other than that, I think git stash is pretty much similar to shelving files in Perforce. Let's explore its usages!

git stash save "<description>"

You can also just use git stash but it automatically generates the description for you which is often wrong and incorrect. So, I prefer to use git stash save command instead with a description that I want to save.

C:\Work\AndroidStudy\Demo\CleanEmptyCompose> git stash save "First Changes"
Saved working directory and index state On master: First Changes

Once your changes are stashed, it restores to the original version before you make any changes. You can now make another change and stash it again.

C:\Work\AndroidStudy\Demo\CleanEmptyCompose> git stash save "Second Changes"
Saved working directory and index state On master: Second Changes

git stash list

To see all the stashed files, you can git stash list command.

C:\Work\AndroidStudy\Demo\CleanEmptyCompose> git stash list 
stash@{0}: On master: Second Changes
stash@{1}: On master: First Changes

So, I have 2 changes now.

git stash apply "<stash name>"

To restore my first changes, I run git stash apply "stash{1}" command:

C:\Work\AndroidStudy\Demo\CleanEmptyCompose> git stash apply "stash@{1}"
On branch master
Your branch is up to date with 'origin/master'.

git stash drop"<stash name>"

To delete the stashed files for my first changes, I run git stash drop "stash{1}" command:

C:\Work\AndroidStudy\Demo\CleanEmptyCompose> git stash drop "stash@{1}"
Dropped stash@{1} (5c1cced4511bb453492f27fd6c71d74ff570b7ae)

If you perform git stash list, now you see the first changes stashed files are removed now.

C:\Work\AndroidStudy\Demo\CleanEmptyCompose> git stash list            
stash@{0}: On master: Second Changes

git stash clear

This deletes all the stashed files! git stash list doesn't show anything now after you run the command.

C:\Work\AndroidStudy\Demo\CleanEmptyCompose> git stash clear
C:\Work\AndroidStudy\Demo\CleanEmptyCompose> git stash list

Summary

There are other git stash commands (e.g. git stash pop/ git stash push, etc.) but I think the above commands are good enough for me.

For complete git stash commands, you can refer to the official documentation here.

Originally published at https://vtsen.hashnode.dev.

Simplify ViewModelProvider.Factory() Implementation with Kotlin Lambda and Object Expressions

Vincent Tsen — Sat, 16 Sep 2023 00:00:00 +0000

Learn how to streamline the implementation of ViewModelProvider.Factory() using Kotlin Lambdas and Object Expressions with examples.

If you are like me and still have not gotten used to the Dependency Injection framework (don't you think it complicates things?), you probably have been implementing the ViewModelProvider.Factory() interface for your view models that has custom constructor parameters.

Multiple ViewModel Factory Classes

class AViewModelFactory(private val repository: ARepository) :
    ViewModelProvider.Factory {
    override fun <T : ViewModel> create(modelClass: Class<T>): T {
        return AViewModel(repository) as T
    }
}

For example, AViewModelFactory is the view model factory class that creates ViewModel which takes in ARepository as a constructor parameter. So what if you have another ViewModel to create? Then, you need to implement another factory class (i.e. BViewModelFactory)

class BViewModelFactory(private val repository: BRepository) :
    ViewModelProvider.Factory {
    override fun <T : ViewModel> create(modelClass: Class<T>): T {
        return BViewModel(repository) as T
    }
}

Well, this seems redundant and can be simplified.

Kotlin Lambda and Object Expressions

You can simply the implementation without explicitly having these factory classes using Kotlin Lambda Functions and Object Expressions as you can see in the following createViewModelFactory() helper function.

fun <VM : ViewModel> createViewModelFactory(createViewModel: () -> VM)
    : ViewModelProvider.Factory {

    return object : ViewModelProvider.Factory {
        override fun <T : ViewModel> create(modelClass: Class<T>): T {
            return createViewModel() as T
        }
    }
}

The createViewModel is the lambda where the callers define how they want to create the ViewModel. The return of this function is the implementation of ViewModelProvider.Factory() interface for the ViewModel that you want to create.

So, instead of creating the ViewModel like this:

@Composable()
fun WithoutHelperFunctions() {
    val aViewModel: AViewModel = viewModel(
        factory = AViewModelFactory(ARepository()),
    )

    val bViewModel: AViewModel = viewModel(
        factory = BViewModelFactory(BRepository()),
    )
}

You can create the ViewModel with this createViewModelFactory() helper function:

@Composable()
fun WithHelperFunctions() {
    val aViewModel: AViewModel = viewModel(
        factory = createViewModelFactory {
            AViewModel(ARepository())
        }
    )

    val bViewModel: BViewModel = viewModel(
        factory = createViewModelFactory {
            BViewModel(BRepository())
        }
    )
}

The benefit is, you no longer need to declare multiple factory classes. You just need to have one createViewModelFactory() helper function.

ViewModel Creation Articles

If you're not familiar with ViewModel creations, you may want to visit my following blog posts:

Source Code

GitHub Repository: Demo_ViewModelFactory

Originally published at https://vtsen.hashnode.dev.

Integrate Firebase Realtime Database and User Authentication into your Android App

Vincent Tsen — Fri, 04 Aug 2023 13:13:56 +0000

A Step-by-Step tutorial to integrate Firebase Realtime Database and User Authentication into your Android app with Kotlin and Jetpack Compose

This is part of the Firebase tutorial series:

Part 1 - Simple Firebase Sign-in UI Demo App
Part 2 - Integrate Firebase Realtime Database and User Authentication into your Android App

This article is the continuity of the previous article, in which we learned how to create a simple Firebase sign-in/authentication in the Android app.

So, this assumes you have already set up the Firebase console project for your app. The overview of the demo app looks like this.

1. Enable Realtime Database in Firebase Project

On the left panel of your Firebase project, click Build -> Realtime Database.

Click Create Database.

In Database options, let's use the database location from the US. Click Next.

In Security rules, let's choose test mode and click Enable.

It doesn't matter what you choose here, we're going to change the security later.

Congratulation! Now Firebase Realtime Database is enabled in your project.

2. Change Security Rules to Content-owner only Access

Go to Realtime Database -> Rules, you see something like this.

It means everyone who installs your app can read or write to your database before the expiration date. That is usually for development purposes.

What we want here is only the authenticated user can only access a certain path of the database.

So, I'm going to change the rules to the following.

{
  "rules": {
    "users": {
      "$uid": {
        ".read": "auth !== null && auth.uid === $uid",
        ".write": "auth !== null && auth.uid === $uid"
      }
    }
  }
}

These rules mean only the authenticated user can access (read from and write to) the \users\<uid> path. uid is the unique string ID that is assigned to the |Firebase user.

The official document reference is here.

3. Add Firebase Database SDK to your App

build.gradle/kts (app level)

 dependencies {
     /*...*/
    implementation("com.google.firebase:firebase-database-ktx:20.1.0") 
 }

4. Write User Data to Database

The Firebase Realtime Database supports the Kotlin data class serialization and deserialization. So instead of operating on every single user data directly, you can create UserData data class below to hold them.

data class UserData (
    val name:String?,
    val age: Int?,
    val favoriteFood:List<String>?
) {
    //Note: this is needed to read the data from the firebase database
    //firebase database throws this exception: UserData does not define a no-argument constructor
    constructor() : this(null, null, null)
}

The gotcha is you MUST create a no-argument conustructor(). Firebase database throws the exception when you try to read the data from it. Damn it, it tooks me sometime to figure this out and it is not documented anywhere.

Write Data to Database

Once we signed in, we can retrieve the FirebaseUser from FirebaseAuth.getInstance().currentUser. From here, we can get the FirebaseUser.uid.

To get the reference to /users/<uid> path in the database, we use Firebase.database.reference.child("users").child(user.uid). A Firebase reference represents a particular location in your Database and can be used for reading or writing data to that Database location.

Then, we can call DatabaseReference.setValue() to write the data into the database.

val user = FirebaseAuth.getInstance().currentUser
user?.run {
    val userIdReference = Firebase.database.reference
        .child("users").child(user.uid)
    val userData = UserData(
        name = displayName,
        age = 7,
        favoriteFood = listOf("Apple", "Orange")
    )
    userIdReference.setValue(userData)
}

Before you write the data, in the Firebase console Realtime Database data tab, it looks like this, which doesn't contain any data.

After you write data into it, it becomes like this.

5. Read User Data from Database

Read Data from Database (One-time Read)

The DatabaseReference.Get() returns Task<DataSnapshot> which allows you to register a callback from the task. To read data, we register this callback task, Task.addOnSuccessListener().

val user = FirebaseAuth.getInstance().currentUser
user?.run {
    val userIdReference = Firebase.database.reference
        .child("users").child(uid)

    userIdReference.get().addOnSuccessListener { dataSnapShot ->
        val userData = dataSnapShot.getValue<UserData?>()
        //successfully read UserData from the database
    }
}

Read Data from Database (Continuous Read)

If you want to continuously reading the data instead reading on-demand, you register this ValueEventListener with DatabaseReference.addValueEventListener(). In the onDataChange() callback, you can expose the UserData to either Flow or StateFlow.

val user = FirebaseAuth.getInstance().currentUser
val userIdReference = Firebase.database.reference
    .child("users").child(user!!.uid)

userIdReference.addValueEventListener(object : ValueEventListener {
    override fun onDataChange(dataSnapshot: DataSnapshot) {
        val userData = dataSnapshot.getValue<UserData?>()
        //expose userData as flow or stateFlow here     
    }

    override fun onCancelled(error: DatabaseError) {
    }
})

Next Steps

The Firebase Realtime database is easy to set up (maybe not? Because it took me a while, too). The drawback of using it is not completely free, especially after you finish your quota. I will explore MangoDB next...

Source Code

GitHub Repository: Demo_FirebaseSignInRealtimeDB

Originally published at https://vtsen.hashnode.dev.

How to Add Spotless Code Formatter to your Android Project?

Vincent Tsen — Sat, 08 Jul 2023 00:00:00 +0000

Steps-by-steps guide to add spotless code formatter to your Android project for both Kotlin script (KTS) and Groovy build Gradle files

I have been seeing this spotless in many open-source codes, and it turns out it is a pretty popular coding style plugin for the Gradle build system used in Android development.

So I gave it a try and use it in my project. Here are the steps I took to add this spotless plugin to my existing projects, which consist of both Kotlin script (KTS) and Groovy build Gradle files.

1. Add com.diffplug.spotless Plugin

Add com.diffplug.spotless in the project-level build.gradle/.kts.

KTS

plugins {
    /*...*/
    id("com.diffplug.spotless") version "6.19.0" apply false
}

Groovy

plugins {
    /*...*/
    id 'com.diffplug.spotless' version '6.19.0' apply false
}

2. Configure the Spotless

Add the following at the end of your project-level build.gradle/.kts.

KTS

subprojects {
    apply(plugin = "com.diffplug.spotless")
    configure<com.diffplug.gradle.spotless.SpotlessExtension> {
        kotlin {
            target("**/*.kt")
            targetExclude("$buildDir/**/*.kt")

            ktlint()
            licenseHeaderFile(rootProject.file("spotless/copyright.kt"))
        }

        kotlinGradle {
            target("*.gradle.kts")
            ktlint()
        }
    }
}

Groovy

subprojects {
    apply plugin: 'com.diffplug.spotless'
    spotless {
        kotlin {
            target '**/*.kt'
            targetExclude("$buildDir/**/*.kt")

            ktlint()
            licenseHeaderFile rootProject.file('spotless/copyright.kt')
        }

        groovyGradle {
            target '*.gradle'
            greclipse()
        }
    }
}

Few notes:

target("**/*.kt") is needed to include all the Kotlin files in the subdirectories. ** indicates the subdirectories.
licenseHeaderFile adds the copyright text header in every Kotlin file. An example of the spotless/copyright.kt file can be found here.
Don't need to explicitly use ** in target("*.gradle.kts"), it includes the subdirectories already.

3. Run the Spotless Code Formatter

Run the following commands in your Android Studio terminal.

To check without making changes:

 .\gradlew spotlessCheck

To check and apply the changes:

 .\gradlew spotlessApply

spotlessCheck is a bit useless to me. I usually just run the spotlessApply directly.

It won't apply the change directly if it encounters errors. Some of the errors I get are

Wildcard Imports is Used

rule: standard:no-wildcard-imports

Wildcard import

java.lang.AssertionError: Error on line: 5, column: 1

rule: standard:no-wildcard-imports

Wildcard import

No Whitespace Start of Function Body

rule: standard:function-start-of-body-spacing

Expected a single white space before start of function body

java.lang.AssertionError: Error on line: 7, column: 57

rule: standard:function-start-of-body-spacing

Expected a single white space before start of function body

After you fix all the errors, it applies the copyright header and default coding style to your files.

4. Automate spotlessApply in Build

If you're lazy to run .\gradlew spotlessApply every time, you can automate it whenever you build an Android project.

Add this in your project-level build.gradle/.kts file to run the spotlessApply task before the preBuild task.

KTS / Groovy

subprojects {
    /*...*/
    afterEvaluate {
        tasks.named("preBuild") {
            dependsOn("spotlessApply")
        }
    }
}

Issues Faced with Spotless

Official document sucks - I follow the doc here. No, it doesn't work!
One error at a time - No kidding, I have many wildcard imports in my project. I have to fix each error and rerun the spotlessApply to get to the next errors. Luckily, I can search the file content instead of relying on the spotless.
Can't disable the rule - I tried, but I didn't get it working. So I have no idea whether this is feasible. This is no documentation on this at all.

[Updated - Feb 17, 2024]: When I updated the spotless version to from "6.19.0"

to "6.25.0", I got the following error:

"Function name should start with a lowercase letter (except factory methods) and use camel case"

To fix that, you need to create a new .editorconfig in your project root directory and add this ktlint_function_naming_ignore_when_annotated_with=Composable

.editorconfilg example

# https://editorconfig.org/
# This configuration is used by ktlint when spotless invokes it

[*.{kt,kts}]
ktlint_function_naming_ignore_when_annotated_with=Composable

However, the Android Studio has this warning indicates the ktlint_function_naming_ignore_when_annotated_with is not supported, but it is incorrect. So, I guess, you can ignore this warning.

Warning:(5, 1) The property is not supported

Example

GitHub Repository: Demo_CleanEmptyCompose

master branch (KTS)
master_groovy branch (Groovy)

Originally published at https://vtsen.hashnode.dev.

How to Request Android Runtime Permissions using Jetpack Compose?

Vincent Tsen — Sat, 01 Jul 2023 00:00:00 +0000

A simple app example and proper way to request Android runtime permission workflow using Accompanist Permissions library for Jetpack Compose

There are 2 types of permissions:

Install-time permissions
Runtime permissions

An example of the most common install-time permissions is internet permissions. The Android OS system automatically grants your app the permission when the app is installed. You just need to declare the permission in the AndroidManifest.xml.

Unlike runtime permissions, in addition to declaring the permissions in the AndroidManifest.xml, you also need to manually request the permissions in your app. There are some gotchas on requesting runtime permissions, which will be discussed later.

Why Accompanist Permissions?

After playing around with different Android permission implementations in Jetpack Compose, I prefer to use Accompanist permissions library over rememberLauncherForActivityResult() for the following reasons:

Permissions state checking is slightly easier using rememberPermissionState() or rememberMultiplePermissionsState() instead of waiting for callback results from the activity result launcher.

Accessing to shouldShowRequestPermissionRationale() in composable function is not that straight forward. You probably want to override the shouldShowRequestPermissionRationale() in Activity and do something like this, and figure out how this can be accessed from your composable function.

class MainActivity : ComponentActivity() {
    /*...*/
    override fun shouldShowRequestPermissionRationale(
        permission: String) : Boolean 
    {
        return if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            super.shouldShowRequestPermissionRationale(permission)
        } else {
            false
        }
    }
}

In Accompanist permission, you can just access the PermissionStatus.shouldShowRationale variable from PermissionState.

Request Runtime Permission Gotchas

Permission Request Dialog is Dismissible

Request runtime permission allows user to dismiss the permission dialog in certain Android version (I think is starting from Android 11/ API level 30). You can either click outside the permission request dialog or simply press the back button to dismiss the permission request dialog.

The problem is, when the permission dialog is dismissed, the PermissionState data remains unchanged. So we have no idea, the user has dismissed the permission request dialog.

What I did to workaround with this issue is I launch the permission request on top of another OptionalLaunchPermissionDialog() which is the wrapper for AlertDialog().

@OptIn(ExperimentalPermissionsApi::class)
@Composable
fun OptionalSinglePermissionScreen(
    permission: String,
) {
    /*...*/
    OptionalLaunchPermissionDialog(
        permission,
        permissionState,
        dismissCallback = { launchPermissionDialog = false}
    )

    SideEffect {
        permissionState.launchPermissionRequest()
    }        
}

So, when the permission request is dismissed, the AlertDialog() is shown to allow user to relaunch or cancel the permission request (if the permission request is optional).

Don't Launch Permission Request when shouldShowRationale is True

When shouldShowRationale is True, it means the permission has been denied before. The launchPermissionRequest() was first called before. If you call launchPermissionRequest() the second time, it still works. However, if you deny the permission this time, the shouldShowRationale is now set to false. You call launchPermissionRequest(), nothing will happen.

So after this stage, you completely lost the permission state status. You do not know the runtime permission request has been permanently denied. So, the best practice here in my opinion is to show the rational UI to guide user to enable the permission manually when shouldShowRationale is set to True.

@OptIn(ExperimentalPermissionsApi::class)
@Composable
fun OptionalSinglePermissionScreen(
    permission: String,
) {
    val permissionState = rememberPermissionState(permission)

    if (permissionState.status.isGranted) {
        // permission granted - do nothing here
    } else if (permissionState.status.shouldShowRationale) {
        // permission denied - show rational UI here
    } else {
        // launch runtime permission request here
    }
}

Request Runtime Permission App Demo

This demo app has the following examples:

Optional Single Runtime Permission Request
Required Single Runtime Permission Request
Optional Multiple Runtime Permissions Request
Required Multiple Runtime Permissions Request

The step-by-step guide here refers to Optional Single Runtime Permission Request. For the rest, you can refer to the source code.

1. Declare Permission in Your Manifest File

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.CALL_PHONE" />
    <!-- ... -->
</manifest>

2. Add Accompanist Permissions Dependency

dependencies {
    /*...*/
    implementation ("com.google.accompanist:accompanist-permissions:0.31.0-alpha")
}

3. Implement Permission Request Logic

@OptIn(ExperimentalPermissionsApi::class)
@Composable
fun OptionalSinglePermissionScreen(
    permission: String,
) {
    var permissionStatusText by remember { mutableStateOf("") }
    val permissionState = rememberPermissionState(permission)

    var launchPermissionDialog by remember { mutableStateOf(true) }
    var showRationale by remember { mutableStateOf(true) }

    if (permissionState.status.isGranted) {
        permissionStatusText = "Granted"
    }

    else if (permissionState.status.shouldShowRationale) {
        permissionStatusText = "Denied"

        if(showRationale) {
            OptionalRationalPermissionDialog(
                permission,
                dismissCallback = {showRationale = false}
            )
        }

    } else {
        permissionStatusText = "N/A"
        if (launchPermissionDialog) {
            OptionalLaunchPermissionDialog(
                permission,
                permissionState,
                dismissCallback = { launchPermissionDialog = false}
            )

            SideEffect {
                permissionState.launchPermissionRequest()
            }
        }

    }

    Column(
        modifier = Modifier.fillMaxSize(),
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text("Optional Permission status: $permissionStatusText")
    }
}

This is the OptionalLaunchPermissionDialog() that allows you to relaunch the permission request when the permission request dialog is dismissed.

@OptIn(ExperimentalPermissionsApi::class)
@Composable
fun OptionalLaunchPermissionDialog (
    permission: String,
    permissionState: PermissionState,
    dismissCallback: () -> Unit
) {
    val context = LocalContext.current
    val permissionLabel = stringResource(
        context.packageManager.getPermissionInfo(permission, 0).labelRes
    )

    AlertDialog(
        onDismissRequest = { dismissCallback()},
        title = { Text(text = "Permission Required!") },
        text = { Text(text = permissionLabel) },
        confirmButton = {
            Button(onClick = {
                permissionState.launchPermissionRequest()
            }) {
                Text(text = "Launch")
            }
        },
        dismissButton = {
            Button(onClick = {
                dismissCallback()
            }) {
                Text(text = "Cancel")
            }
        }
    )
}

This stringResource(context.packageManager.getPermissionInfo(permission, 0).labelRes) provides a more user-friendly permission string.
Since this is an optional permission request, we allow the user to dismiss this dialog.

OptionalRationalPermissionDialog() shows the reasons why the app needs the permission and guide the user to grant the permission manually.

@Composable
fun OptionalRationalPermissionDialog (
    permission: String,
    dismissCallback: () -> Unit
) {
    val context = LocalContext.current
    val permissionLabel = stringResource(
        context.packageManager.getPermissionInfo(permission, 0).labelRes
    )

    AlertDialog(
        onDismissRequest = { dismissCallback()},
        title = { Text(text = "Permission Required!") },
        text = { Text(text = permissionLabel) },
        confirmButton = {
            Button(onClick = {
                val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS)
                    .apply {
                        data = Uri.fromParts("package", context.packageName, null)
                    }
                ContextCompat.startActivity(context, intent, null)
            }) {
                Text(text = "Go to settings")
            }
        },
        dismissButton = {
            Button(onClick = {
                dismissCallback()
            }) {
                Text(text = "Cancel")
            }
        }
    )
}

This creates an activity intent that brings you to the app setting which you manually grant the permission to your app.

val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS)
    .apply {
        data = Uri.fromParts("package", context.packageName, null)
    }
ContextCompat.startActivity(context, intent, null)

Well, that is it!

4. Revoke Runtime Permissions

For testing, we often want to revoke the runtime permissions and rerun the app again. So I gave this ADB command a try.

 adb shell pm revoke vtsen.hashnode.dev.runtimepermissiondemoapp android.permission.CALL_PHONE

It does remove the permission, but it has an unexpected behavior. The shouldShowRationale is now set to True. I want it to be False. To completely revoke the runtime permissions, I either need to reinstall the app or clear the app storage.

Conclusion

Multiple permissions request is similar. Instead of having single PermissionState, it has List<PermissionState>. I will probably use it by default in my app because it can also support single permission request. Last but not least, when shouldShowRationale is True, do NOT launch the runtime permission request.

Source Code

GitHub Repository: Demo_RuntimePermission

Originally published at https://vtsen.hashnode.dev.

@RequiresApi() and @ChecksSdkIntAtLeast() Annotation

Vincent Tsen — Sat, 24 Jun 2023 00:00:00 +0000

@RequiresApi() and @ChecksSdkIntAtLeast() Annotations are used by lint tool in Android Studio to provide proper warning/error messages

One of the things I am confused about in Android development is these lint tool annotations. These annotations do not sound like lint tool annotations to me, but they are.

So, I call them lint tool annotations because it makes them clear to me on their purposes which provides you with the proper lint warning/error messages to you in Android Studio.

`@RequiresAPI()`

Let's say you have a function that calls an Android API that requires min SDK 23, anything below 23 won't work. You annotate @RequiresAPI(23) in your function to let the caller knows that it won't work if the Android device is running below SDK 23.

@RequiresApi(23)
fun callFunctionThatRequiresAPI23() {
   /* code here only applicable for SDK API 23 and above */
}

So, you call it from another function.

fun callerFunction(){
   callFunctionThatRequiresAPI23()
}

You will get this lint error if you're running on minSdk below 23. This error message is coming from the @RequiresApi(23) annotation that I have in the previous function.

Call requires API level 23 (current min is 21): callFunctionThatRequiresAPI23

If you're on minSdk 23, you won't get this error message, and this makes sense because SDK 23 has no problem running the code. Please note that there isn't any build error here, it is a lint error.

Based on the suggested fix, you annotate the function with @RequiresApi(23) to get rid of the error message.

@RequiresApi(23)
fun callerFunction(){
   callFunctionThatRequiresAPI23()
}

Well, this is wrong! You shouldn't do this because calling this function on a device that running below 23 won't work. It defeats the original purpose of the error message.

Instead, you should implement the code for SDK < 23. Without the need to add @RequiresApi(23), the error message goes away too if the following conditional check.

fun callerFunction(){
    if (Build.VERSION.SDK_INT >= 23) {
        callFunctionThatRequiresAPI23()
    } else {
        // implement code for SDK < 23
    }
}

`@ChecksSdkIntAtLeast()`

If you extract out Build.VERSION.SDK_INT >= 23 to a function,

fun checkSDK23Version():Boolean = Build.VERSION.SDK_INT >= 23

and call it in the callerFunction(),

fun callerFunction(){
    if(checkSDK23Version()) {
        callFunctionThatRequiresAPI23()
    } else {
        // implement code for SDK < 23
    }
}

nothing happens. The lint tool is smart enough to figure out the checkSDK23Version() is indeed checking for minimum SDK 23 version.

Let's modify checkSDK23Version() to be slightly not straightforward.

fun checkSDK23Version(): Boolean {
    Log.d("vtsen", "do something here")
    return Build.VERSION.SDK_INT >= 23
}

The lint tool in Android Studio now complains of the same error message again.

Call requires API level 23 (current min is 21): callFunctionThatRequiresAPI23

In this scenario, you annotate the function with @ChecksSdkIntAtLeast(23) to tell the lint tool that this checkSDK23Version() is indeed checking for the SDK version.

@ChecksSdkIntAtLeast(23)
fun checkSDK23Version():Boolean {
    Log.d("vtsen", "do something here")
    return Build.VERSION.SDK_INT >= 23
}

The error message is now gone!

Summary

As a best practice, don't simply add @RequiresAPI() to get rid of the lint warnings/errors. Instead, add the conditional logic to handle the unsupported SDK version. On the hand, you can safely add @ChecksSdkIntAtLeast() to get rid of the lint errors.

If you don't like to hard code the build version code, you can check this BuiltUtils Android library out. It is nothing fancy here and probably missing some checks that you need. If so, feel free to contribute. This is a very beginner-friendly Android library for contribution anyway.

BuildUtils Android Library

Originally published at https://vtsen.hashnode.dev.

Simple Preferences & Proto DataStore Demo App

Vincent Tsen — Sat, 17 Jun 2023 00:00:00 +0000

Beginner's friendly step-by-step guide to learn how to use Preferences and Proto DataStore, Room Database is not covered.

abc.com

There are a few ways you can store data locally on your Android devices:

SharedPreferences (replaced by Preferences DataStore)
Preferences DataStore
Proto DataStore
Room Database

SharedPreferences is the old way, which has been replaced by Preferences DataStore due to its shortcomings (e.g. not safe to be called from the UI thread).

In this article, I'm going to share how to store data using both Preferences DataStore and Proto DataStore. Room Database will be covered later in the next article.

Prefer which way to store data?

Preferences DataStore stores data in a simple key-value format. It is usually for a small and simple dataset. If you have a more complex data format, use Proto DataStore.

Proto DataStore stores data in custom data type format, which is defined using protocol buffers. This is usually for a medium size dataset and it doesn't support partial updates. So for a very large dataset, it is better to use the Room Database.

Room Database is similar to Proto DataStore which can store data in custom data type in a relational database (SQLite) format. Since it supports partial updates, so there won't be any problem storing a very large and complex Database.

Preferences DataStore

Here is a simple app example to store 2 setting values in preferences DataStore. One is Boolean format and another is Int format.

1. Add Preferences DataStore Library

dependencies {
    implementation("androidx.datastore:datastore-preferences:1.0.0")
}

2. Create a Preferences DataStore

It can be created anywhere and usually, you can do it at the file level of your main activity.

val Context.prefsDataStore by preferencesDataStore(name = "settings")

You can also create more than one DataStore but make sure you give it a unique name.

val Context.prefsDataStore1 by preferencesDataStore(name = "settings1")
val Context.prefsDataStore2 by preferencesDataStore(name = "settings2")
val Context.prefsDataStore3 by preferencesDataStore(name = "settings3")

3. Access Preferences DataStore in Composable

To access the DataStore in Composable, you can pass it in from your activity as a parameter or simply use the LocalContext CompositionLocal which I prefer.

@Composable
fun YourComposable() {
    val dataStore = LocalContext.current.prefsDataStore
}

4. Setup the Preferences Key and Name

Before we can use Preferences DataStore(read from it and write to it), you need to set up the preferences key and name.

This creates booleanPreferencesKey() which allows you to read from / write to the DataStore.

 private val booleanOptionName = "Boolean Option"
 private val booleanOptionKey = booleanPreferencesKey(booleanOptionName)

Here is the list of supported preferences key data types:

intPreferencesKey
doublePreferencesKey
stringPreferencesKey
booleanPreferencesKey
floatPreferencesKey
longPreferencesKey
stringSetPreferencesKey

If these data types do not meet your needs, Proto DataStore is probably what you need.

5. Write to a Preferences DataStore

This is what I have in my view model. To write to a preferences DataStore, you use the DataStore<Preferences>.edit() suspend API. Since it is a suspend function, you need to launch it under a coroutine.

class PrefsDataStoreScreenViewModel(
    private val dataStore: DataStore<Preferences>
) : ViewModel() {
    /*...*/
    private val booleanOptionName = "Boolean Option"
    private val booleanOptionKey = booleanPreferencesKey(booleanOptionName)

    fun saveBooleanOptionValue(value: Boolean) {
        viewModelScope.launch {
            dataStore.edit { preferences ->
                preferences[booleanOptionKey] = value
            }
        }
    }
}

The preferences here is the MutablePreferences very much behave the same as MutableMap in Kotlin which you can assign key-value pairs.

6. Read from a Preferences DataStore

To read, we use DataStore<Preferences>.data flow API which exposes Flow<Preferences>

Typically, I don't want to expose the flow directly in ViewModel. I prefer to expose the StateFlow instead because I don't want the flow to keep emitting whenever there is a new collector.

class PrefsDataStoreScreenViewModel(
    private val dataStore: DataStore<Preferences>
) : ViewModel() {

    private val booleanOptionName = "Boolean Option"
    private val booleanOptionKey = booleanPreferencesKey(booleanOptionName)

    val booleanOptionState = dataStore.data.map { preferences ->
            preferences[booleanOptionKey] ?: false
        }.stateIn(
            scope = viewModelScope,
            started = SharingStarted.Eagerly,
            initialValue = false
        )
    /*...*/
}

It looks complex, but let me break it out.

This converts Flow<Preferences> to Flow<Boolean> using Flow<T>.map() API. When the value is null, it returns false since we don't want the nullable Boolean (e.g. Flow<Boolean?>)

val booleanFlow = dataStore.data.map { preferences ->
    preferences[booleanOptionKey] ?: false
}

Then, we convert Flow<Boolean> to StateFlow<Boolean> using the Flow<T>.stateIn() API.

val booleanStateFlow = booleanFlow.stateIn(
    scope = viewModelScope,
    started = SharingStarted.Eagerly,
    initialValue = false
)

To collect the StateFlow in composable function, you can use collectAsStateWithLifecycle().

@Composable
fun PrefsDataStoreScreen(doneCallback: ()->Unit) {
    /*...*/
    val booleanOptionValue by 
        viewModel.booleanOptionState.collectAsStateWithLifecycle()
    /*...*/
}

If you have trouble understanding this, you may want to refer to this article.

Convert Flow to SharedFlow and StateFlow

For the rest, please refer to the source code. The code also uses a custom ViewModelFactory. If you're not familiar with it, you can read this article.

View Model Creation in Jetpack Compose

Now, let's move on to Proto DataStore...

Proto DataStore

I implemented the bookmarked articles for my RSS feed reader app using Proto DataStore. So, I'm going to use it as an example here, which is to store a list of bookmarked articles.

1. Add DataStore & protobuf-javalite Libraries

dependencies {
    implementation("androidx.datastore:datastore:1.0.0")
    implementation("com.google.protobuf:protobuf-javalite:3.21.12")
}

Setting up DataStore is straightforward, but not the protocol buffers library and plugin. The official documentation has missed this information, so I have to figure it out by myself.

2. Add protobuf Plugins

plugins {
    /*...*/
    id ("com.google.protobuf") version("0.9.0")
}

3. Add Java Protobuf-lite code Generation

Add the following code at the end of your app-level build.gradle/kts file.

Groovy

plugins {
    /*...*/
    id "com.google.protobuf" version '0.9.0'
}

android {
    /*...*/
}

dependencies {
    /*...*/
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:3.19.4"
    }

    generateProtoTasks {
        all().each { task ->
            task.builtins {
                java {
                    option 'lite'
                }
            }
        }
    }
}

Kotlin (KTS)

plugins {
    /*...*/
    id ("com.google.protobuf") version("0.9.0")
}

android {
    /*...*/
}

dependencies {
    /*...*/
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:3.19.4"
    }

    generateProtoTasks {
        all().forEach { task ->
            task.builtins {
                create("java") {
                    option("lite")
                }
            }
        }
    }
}

I added both Groovy and Kotlin versions here because there are not exactly 1-to-1 matches. I have issues converting from Groovy to Kotlin.

all().each is Groovy needs to be changed to all().forEach in Kotlin/KTS

Java's option in Groovy is not recognized by Kotlin/KTS.

4. Define a ProtoBuf Scheme

The data structure format that you want to store is defined in this ProtoBuf scheme file (*.proto) and you need to create this proto file in app/src/main/proto/ directory in your app module.

In this example, I would like to store the list of bookmarked article IDs in string format and here is the ProtoPreferences.proto file.

syntax = "proto3";

option java_package = "vtsen.hashnode.dev.datastoredemoapp";
option java_multiple_files = true;

message ProtoPreferences {
  //first field 
  map<string, bool> bookmarked_article_ids = 1;
  //second field
  map<string, bool> read_article_ids = 2;
}

syntax="proto3" indicates the definition follows proto3 version rules
java_package refers to the applicationId in your build.gradle.kts file.
java_multiple_files = true configure each message has it's own Java class file.
message ProtoPreferences is a message type that has 2 fields in the above example.
map<string, bool> is the map data structure where the key is the article Id in string format and the value is a boolean that indicates whether the article is bookmarked.

Tip: If you name your proto file name the same as the message name (e.g. ProtoPreferences), make sure you use the same capitalization. For example, protopreferences.proto won't work. It must be ProtoPreferences.proto or some other name.

Compile the code, make sure you get the successful build and the ProtoPreferences Java class should be generated.

5. Implement DataStore Serializer Interface

Implement the Serializer interface singleton object for generated ProtoPreferences Java class (ProtoBuf scheme) that you created in step 4 above.

object ProtoPreferencesSerializer : Serializer<ProtoPreferences> {
    override val defaultValue: ProtoPreferences
        = ProtoPreferences.getDefaultInstance()

    override suspend fun readFrom(
        input: InputStream
    ): ProtoPreferences{
        try {
            return ProtoPreferences.parseFrom(input)
        } catch (exception: InvalidProtocolBufferException) {
            throw CorruptionException("Cannot read proto.", exception)
        }
    }

    override suspend fun writeTo(
        t: ProtoPreferences, 
        output: OutputStream) = t.writeTo(output)
}

This is pretty standard code to read from and write to the serializer, so I'm not going to explain it here.

6. Create a Proto DataStore

Similar to Preferences DataStore, instead of using by preferenceDataStore delegate, you use by dataStore

val Context.protoDataStore: DataStore<ProtoPreferences> by dataStore(
    fileName = "ProtoPreferences.pb",
    serializer = ProtoPreferencesSerializer
)

In this example, it is created in the main activity. Depending on your need, you can also create it in the repository class if it is only referenced there. You can see the example here.

7. Write to a Proto DataStore

DataStore<T>.updateData() suspend function is used to update the Proto DataStore data. It needs a builder to build a MessageTypeas you can see below.

class ProtoDataStoreScreenViewModel(
    private val dataStore: DataStore<ProtoPreferences>
) : ViewModel() {
    /*...*/    
    fun saveBookmarkedArticle(articleId: String, bookmarked: Boolean) {
        viewModelScope.launch {
            dataStore.updateData { protoPreferences ->
                protoPreferences.toBuilder()
                    .putBookmarkedArticleIds(articleId, bookmarked)
                    .build()
            }
        }
    }
    /*...*/
}

putBookmarkedArticleIds() API is auto-generated based on what you define in the ProtoBuf scheme. For other generated APIs, refer to the generated ProtoPreferences.java file.

8. Read from a Proto DataStore

Reading is very similar to Preferences DataStore.

DataStore<ProtoPreferences>.data flow API exposes Flow<ProtoPreferences>. Then, it is converted to Flow<Map<String, Boolean>> using flow mapping. Finally, it is converted to StateFlow<Map<String, Boolean>> using stateIn flow operator.

class ProtoDataStoreScreenViewModel(
    private val dataStore: DataStore<ProtoPreferences>
) : ViewModel() {
    /*...*/
    val bookmarkedArticlesState = dataStore.data.map { protoPreferences ->
            protoPreferences.bookmarkedArticleIdsMap
        }.stateIn(
            scope = viewModelScope,
            started = SharingStarted.Eagerly,
            initialValue = null)
}

Here is the usage which you are probably already familiar with.

@Composable
fun ProtoDataStoreScreen(doneCallback: ()->Unit) {

    val viewModel: ProtoDataStoreScreenViewModel = viewModel(
        factory = ViewModelFactory(LocalContext.current.protoDataStore)
    )

    val articles by viewModel.bookmarkedArticlesState
        .collectAsStateWithLifecycle()

    /*...*/
}

Conclusion

Preferences DataStore is relatively easy to implement with comprehensive documentation available. However, setting up Proto DataStore can be a bit challenging due to the lack of proper documentation.

To address this, I have taken the initiative to document the process here, providing a valuable reference for anyone encountering similar difficulties.

Source Code

GitHub Repository: Demo_DataStore

Originally published at https://vtsen.hashnode.dev.

Simple Firebase Sign-in UI Demo App

Vincent Tsen — Sat, 10 Jun 2023 00:00:00 +0000

Simple Jetpack Compose example to demonstrate how to sign in with a Firebase Authentication pre-build UI using FirebaseUI

This is part of the Firebase tutorial series:

Part 1 - Simple Firebase Sign-in UI Demo App
Part 2 - Integrate Firebase Realtime Database and User Authentication into your Android App

In this demo app, we will guide you through the steps to enable FirebaseUI for authentication and demonstrate how to integrate it into your Jetpack Compose application.

We're going to add these 2 sign-in methods:

Email/Password
Google

Connect Your App to Firebase

Go to the Firebase console, and log in with your Google account.
Add project and follow on-screen instructions
Turn off Enable Google Analytics for this project, and click Create project.
Register the app with Android package name (applicationId in your build.gradle file)

* Add **app nickname** (it can be any name)

* Add **Debug signing certificate SHA-1** if you want to use Google sign-in method. In the Android Studio terminal, run this command **./gradlew signingReport.** Copy the SHA-1 and paste it here.

Download google-services.json to your project app folder.
Go to Authentication -> Sign-in method. Add and enable Email/Password, and Google sign-in providers.

The google-services.json and debug singing certificate fingerprints can also be accessed from the Project Overview -> Project settings at the top left corner.

Add Firebase Authentication SDK to your app

Add Google services Gradle plugin in your project-level build.gradle.kts.

buildscript {
    dependencies {
        classpath("com.google.gms:google-services:4.3.15")
    }
}

Add Google service Gradle plugin in your app-level build.gradle.kts/

plugins {
    /*...*/
    id ("com.google.gms.google-services")
}

Add FirebaseUI and Play Services Auth libraries

dependencies {
    /*...*/
    implementation ("com.firebaseui:firebase-ui-auth:7.2.0")
    implementation ("com.google.android.gms:play-services-auth:20.5.0") 
}

The Play Services Auth library is required for the Email/Password sign-in method.

In Android Studio, all the above steps can be automated with the Firebase Assistant (Tools -> Firebase) except that you need to manually add the Debug signing certificate SHA-1 and also manually modify the library dependencies.

Integrate pre-build Firebase Sign-in UI

Quick steps on what you need to do to launch the pre-build Sign-in UI:

Create ActivityResultLauncher
Choose authentication providers

Create and launch sign-in intent. Here is an example of SignInScreen() composable functions:

@Composable
fun SignInScreen(
    onSignInResult: (FirebaseAuthUIAuthenticationResult) -> Unit
) {
    // (1) Create ActivityResultLauncher
    val launcher = rememberLauncherForActivityResult(
        contract = FirebaseAuthUIActivityResultContract(),
        onResult = onSignInResult
    )

    // (2) Choose authentication providers
    val providers = arrayListOf(
        AuthUI.IdpConfig.GoogleBuilder().build(),
        AuthUI.IdpConfig.EmailBuilder().build(),
    )

    // (3) Create and launch sign-in intent
    val intent = AuthUI.getInstance()
        .createSignInIntentBuilder()
        .setAvailableProviders(providers)
        .build()

    LaunchedEffect(true){
        launcher.launch(intent)
    }
}

Handle the sign-in result callback

SignInScreen { result ->
    // (4) Handle the sign-in result callback
    if (result.resultCode == ComponentActivity.RESULT_OK) {
        signInStatus = "Signed In"
        val user = FirebaseAuth.getInstance().currentUser
        userId = user!!.uid

    } else {
        val response = result.idpResponse
        signInStatus = if (response == null) {
            "Not Signed In"
        } else {
            val errorCode = response.getError()?.getErrorCode()
            "Failed - Error Code: $errorCode"
        }
    }    
    /*...*/
}

When the response is null, the user cancels the sign-in operation (e.g. press the back button)

Some Thoughts

The Firebase Assistant in Android Studio is quick and helpful, but if you're new, I recommend you go through the Firebase console project setup steps above to fully understand the actual steps that need to be done.

Next Step

Well, this is just a quick demo app to demonstrate the Firebase sign-in APIs. I probably should move the sign-in state to a ViewModel when I port this change to my actual app.

[Updated - Aug 08, 2023]: Yeah, I have moved the sign-in state to the VIewModel if you look at the source code.

I also want to learn how to store the user data in the remote server using Firebase real-time database instead of using Preferences and Proto DataStore on the local phone.

Source Code

GitHub Repository: Demo_FirebaseSignInRealtimeDB

Originally published at https://vtsen.hashnode.dev.

How to add Google Play In-app Review Dialog?

Vincent Tsen — Sat, 03 Jun 2023 00:00:00 +0000

A step-by-step guide how you can let users review your app using Google Play In-app review API and test it out using Internal App Sharing

This is just a quick guide and a simple example of how to add the Google Play In-app review dialog in your app. This is what it looks like after I implemented this in RSS feed reader app.

1. Add Review API Libraries

This example of build.gradle.kts (Kotlin script/KTS) in your app module.

dependencies {
    /*...*/
    implementation("com.google.android.play:review:2.0.1")
    implementation("com.google.android.play:review-ktx:2.0.1")
    /*...*/
}

2. Create ReviewManager in the Activity

It is better to implement the ReviewManger in activity rather than a composable function because its APIs needs an activity. Well, you can technically do it in composable function (through LocalContext), but it is not a good practice because composable functions shouldn't need to know about the activity.

This creates the ReviewManager using ReviewManagerFactory.create() API in your activity. Of course, only when it is accessed because of the lazy delegate is used here.

class MainActivity : ComponentActivity() {
    /*...*/
    private val reviewManager by lazy {
        ReviewManagerFactory.create(this)
    }
    /*...*/
}

3. Add showReviewDialog() Function

Let's create a function that requests the review flow and launch the review dialog.

class MainActivity : ComponentActivity() {
    /*...*/
    private fun showReviewDialog() {
        val request = reviewManager.requestReviewFlow()
        request.addOnCompleteListener { task ->
            if (task.isSuccessful) {
                val reviewInfo = task.result
                reviewManager.launchReviewFlow(this, reviewInfo)
            }
        }
    }
    /*...*/
}

Then, set this function to be a callback from your composable function.

override fun onCreate(savedInstanceState: Bundle?) {
    /*...*/
    setContent {
        /*...*/
        MainScreen(showReviewDialog = ::showReviewDialog)
    }
}

What I did is simply add a drop-down "Rate Me" menu to the app.

Well, this is for educational purposes and is not recommended to implement this way because there are no callbacks to indicate whether Google Play review dialog is shown or not. If the dialog is not shown (for the reasons below), this appears to be a broken user flow, which we want to avoid!

There are quotas on how many times this API can be called. Clicking the "Rate Me" the second time, won't show the Google Play review dialog anymore. I also noticed if you have already reviewed the app, call the ReviewManager.launchReviewFlow() API does nothing too.

For more information, you can refer to the official document here.

4. Test In-app Reviews

The issue is you can't test it in your emulator directly because it requires your app to be published in Play Store.

There are a few ways you can test it out (as you can read from the documentation here) but the easiest way in my opinion is internal app sharing.

Here are the steps to upload your app for internal app sharing:

In Google Play Console, go to Setup -> Internal App Sharing
Create an Internal Testers email lists. Separate the emails with a comma.
In Manage testers, select Restrict access to email lists
In Manage uploaders, click this link, https://play.google.com/console/internal-app-sharing. After that, you can upload your app bundle or APK here.
Copy the link and sent it to your testers (it could be yourself). The tester needs to open the link on his/her phone and it looks like this. Click OPEN IN PLAY STORE APP.
You get this if your Google Play has not enabled Internal app sharing. Click the Google Play Settings.
In Google Play Settings, go to About, and click Play Store Version 7 times. This enables the developer options.
Go to General -> Developer options, and enable the Internal app sharing. You get this prompt, so just click Turn on.
Go back to step 5, and click OPEN IN PLAY STORE APP again. It brings you to Google Play Store, to install the app.

If the app has already been installed previously, it asks you to uninstall it first.
Now, you should be able to test the Google Play In-App Review Dialog.

In this testing mode, the quotas do not apply here. You can call this Google Play In-App review API as many times as you wish. The only thing is the Submit button is disabled.

Conclusion

Implementing the Google Play in-app review dialog is quite simple, but testing is a bit tricky. It will be nice if we can test it out directly from the emulator.

Deciding when to trigger the in-app review is also a bit tricky for a very simple app like this one. Unlike games after the player finished a level, you can trigger in-app reviews.

Maybe I can do something like prompting the in-app review after the user installed the app after a certain period? Yeah, I will do that next.

[Updated - July 09, 20 23]: This is an example of getting the duration after the app was first installed using PackageInfo.firstInstallTime from PackageManager.

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        showReviewDialog()
        super.onCreate(savedInstanceState)
        /*...*/
    }

    private fun showReviewDialog() {        
        val packageInfo = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            packageManager.getPackageInfo(packageName, PackageManager.PackageInfoFlags.of(0))
        } else {
            packageManager.getPackageInfo(packageName, 0)
        }

        val installTime = packageInfo.firstInstallTime
        val currentTime = System.currentTimeMillis()
        val durationInMillis = currentTime - installTime
        val durationInDays = durationInMillis / (1000 * 60 * 60 * 24)
        /*...*/
    }
}

Example

GitHub Repository: AndroidNews

Originally published at https://vtsen.hashnode.dev.

How to Add Deep Links in Jetpack Compose?

Vincent Tsen — Sat, 27 May 2023 00:00:00 +0000

Step-by-step and easy-to-follow guide to implement deep links in your Android app using Navigation Compose library

This is part of the Jetpack Compose navigation series:

Part 1 - Simple Jetpack Compose Navigation Example
Part 2 - Compose Destinations - Navigation Library
Part 3 - How to Add Bottom Navigation in Jetpack Compose?
Part 4 - How to Add Navigation Drawer in Jetpack Compose?
Part 5 - How to Add Deep Links in Jetpack Compose?

A deep link is a hyperlink that takes you directly to a certain screen on your app.

For example, clicking on my blog's URL, the Android OS shows a list of apps that can be used to open the URL as you can see below.

Note: The UI above may look a bit different on different Android OS

Since my blog's app supports deep links, it shows up as one of the apps, the first one from the left. If I open it with my blog's app, it takes me to specify screen content within my app. That's the called deep link.

To demonstrate how to implement the deep link, I use this simple Jetpack Compose navigation as an example. Let's add the deep link.

Overview

The example app has 4 screens:

Login Screen
Home Screen
Profile Screen
Search Screen

I'm going to add the deep link for each screen in this example app.

1. Add hostname in the activity's intent filter

In AndroidManifest.xml, add the <data>, <category> and <action> tags in the activity's intent filter as shown below.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
...
    <activity
        ...
        <intent-filter>
            <data android:host="vinchamp77.github.io"
                android:scheme="https" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <action android:name="android.intent.action.VIEW" />
        </intent-filter>

    </activity>
...
</manifest>

Note: Hostname is case-sensitive and needs to be lowercase characters.

2. Add NavDeepLink in NavGraphBuilder.composable()

The following code in NavGraph.kt needs to be updated by adding the deepLinks parameter when calling the NavGraphBuilder.composable().

// Login Screen
navGraphBuilder.composable(
    route = NavRoute.Login.path,
    deepLinks = listOf (
        navDeepLink {
            uriPattern = "https://vinchamp77.github.io/deeplink/login"
            action = Intent.ACTION_VIEW
        }
    ),
) {
    /*...*/
}

// Home Screen
navGraphBuilder.composable(
    route = NavRoute.Home.path,
    deepLinks = listOf (
        navDeepLink {
            uriPattern = "https://vinchamp77.github.io/deeplink/home"
            action = Intent.ACTION_VIEW
        }
    ),
) {
    /*...*/
}

// Profile Screen
navGraphBuilder.composable(
    route = NavRoute.Profile.withArgsFormat(NavRoute.Profile.id, NavRoute.Profile.showDetails),
    deepLinks = listOf (
        navDeepLink {
            uriPattern = "https://vinchamp77.github.io/deeplink/profile?id={id}&showDetails={showDetails}"
            action = Intent.ACTION_VIEW
        }
    ),
    /*...*/
) {
    /*...*/

}

// Search Screen
navGraphBuilder.composable(
    route = NavRoute.Search.withArgsFormat(NavRoute.Search.query),
    deepLinks = listOf (
        navDeepLink {
            uriPattern = "https://vinchamp77.github.io/deeplink/search?query={query}"
            action = Intent.ACTION_VIEW
        }
    ),
    /*...*/
) {
    /*...*/
}

You build the list of NavDeepLink using navDeepLink() helper function by specifying the uriPattern and the action parameters.

URI pattern without any argument is straightforward, no big deal. However, when the URI pattern has arguments, it must follow the standard URL query parameters format.

It took me a while to figure this out. For example, the following URI pattern won't work.

 uriPattern = "https://vinchamp77.github.io/deeplink/search/{query}"

It works only if you have one deep link defined. If there is more than one deep link, it falls back to the first deep link that you defined.

So it must be in this format.

uriPattern = "https://vinchamp77.github.io/deeplink/search?query={query}"

3. Test the Deep Link

The easiest way to test the deep link is to use the Tools -> App LInks Assistant in Android Studio.

Go to step 4 - Test on device or emulator directly.

Then, add the URL that you would like to test and click Run Test.

Note: These are equivalent adb commands.

$ adb shell setprop log.tag.AppIndexApi VERBOSE
$ adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d 'https://vinchamp77.github.io/deeplink/search?query="liang moi"'

Click JUST ONCE or ALWAYS to open with Simple Navigation Compose App.

The search screen is shown with the search query that we passed in from the URL.

You're not done! Deep links are finally implemented for your app.

4. Verify Deep Link Host Name

Well, not really. If you run this app on Android 12 (API level 31). The link doesn't take you to the app at all. It requires you to verify the deep links' hostname belongs to your app.

To do that, you first need to generate a Digital Asset Links file and upload it to your as specify location on your website.

<your hostname>/.well-know/assetlinks.json

Now, proceed to step 3 - Associate website in the App Links Assistant

A lot of info should be already pre-filled for you. Select Signing config -> Debug, and click Generate Digital Asset Links File.

For a production build, select Select keystore file instead

Once the file is generated, you can click Save file to download the file. You need to copy the file to your website. In this example, the file location is

https://vinchamp77.github.io/.well-known/assetlinks.json

If you are using a <username>.github.io page like mine, there are some things you need to be aware of for the .well-known folder to be recognized.

Method 1 - If you have _config.yml, you need to add the include: [".well-known"]. This is an example of my github page's _config.yml.

theme: jekyll-theme-minimal
title: Vincent Tsen
description: Self-taught Hobbyist Native Android Kotlin Developer
include: [".well-known"]

Method 2 - If you don't have _config.yml, you add .nojekyll in your root directory**.** The .nojekyII is just an empty file without any content.

Click Link and Verify and you should see

Success! Your app is associated with the selected domain(s).

The Android Studio also automatically added the autoVerify to the intent filter elements.

<intent-filter android:autoVerify="true">
    <data android:host="vinchamp77.github.io"
        android:scheme="https" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <action android:name="android.intent.action.VIEW" />
</intent-filter>

Try to test the app link in step 3 above on Android 12 (API level 31) and above, it works!

You may also notice that it doesn't prompt you to choose from a list of apps, but instead takes you directly to your app. This is also the benefit of verifying your hostname.

Summary

Deep link is quite useful because it brings you directly to a specific screen. One thing I noticed is if the URL doesn't match any of the URL patterns, it falls back to the first deep link. For example, the first deep link in this example is the login screen. All the invalid URL brings you to the login screen directly.

Other than triggering a deep link from URL, you can also trigger the deep link from another app using PendingIntent. I will cover the PendingIntent topic later on. Enjoy!

Source Code

GitHub Repository: Demo_SimpleNavigationCompose (deep link branch)

Originally published at https://vtsen.hashnode.dev.

Kotlin Flow - Combine, Merge and Zip

Vincent Tsen — Sat, 20 May 2023 00:00:00 +0000

Exploring the Power of Kotlin Flow: Combining, Merging, and Zipping Streams

This is part of the asynchronous flow series:

Part 1 - Exploring Android LiveData Usages and Behaviors
Part 2 - Introduction to Kotlin Flows and Channels
Part 3 - Exploring Different Ways to Collect Kotlin Flow
Part 4 - Convert Flow to SharedFlow and StateFlow
Part 5 - Flow, SharedFlow, StateFlow Class Diagram
Part 6 - Kotlin Flow - Combine, Merge and Zip

I have 2 flows here.

Flow1 emits int starting from 1 -> 1000 every 1 second.



private val flow1: Flow<Int> = flow {
    repeat(10000) { value ->
        delay(1000)
        Log.d(tag, "[Flow1]: emitting $value")
        emit(value)
    }
}

Flow 2 emits char from A to Z every 2 seconds.



private val flow2: Flow<Char> = flow {
    var value = 'A'
    while(true) {
        delay(2000)
        Log.d(tag, "[Flow2]: emitting $value")
        emit(value)
        if (value == 'Z') {
            value = 'A'
        } else {
            value += 1
        }
    }
}

Combine Flow

This combines flow1 and flow2 into combineFlow using the Flow.combine() extension function flow operator.



val combineFlow = flow1.combine(flow2) { flow1Value,flow2Value  ->
    "${flow1Value}_${flow2Value}"
}

The limitation of this Flow.combine() extension function is it is limited to combining 2 flows. To combine more than 2 flows, you can use combine() function directly which supports up to 5 flows.



val combineFlow = combine(flow1, flow2) { flow1Value, flow2Value ->
    "${flow1Value}_${flow2Value}"
}

To collect the flow, I use the LaunchedEffect() side effect for this demonstration purpose. The recommended way is either using collectAsStateWithLifeCylce()or repeatOnLifecycle(Lifecycle.State.STARTED), see here.



LaunchedEffect(true) {
    viewModel.combineFlow.collect { value ->
        Log.d(tag, "[Combine Flow]: $value")
    }
}

So this is the output. It combines the latest value from flow1 and flow2.

Merge Flow

This merges flow1 and flow2 into mergeFlow,



val mergeFlow = merge(flow1, flow2)

and here is the output:

1 and A are emitted at the same time, followed by 2, then 3 and B and so on.

Zip Flow

This zips flow1 and flow2 into zipFlow,



val zipFlow = flow1.zip(flow2) { flow1value,flow2value  ->
    "${flow1value}_${flow2value}"
}

and here is the output:

As you can see from this output, Zip pairs up the data from flow1 and flow2.

Conclusion

The above diagrams help me to understand the difference between combine, merge and zip flow operators.

I have been using combine() in this project here which combines the flow from a ROOM database(articles) with another flow from a Proto DataStore(user settings). I do not have any chance to use Merge() and Zip(). :)

Source Code

GitHub Repository: Demo_AsyncFlow (see the CombineMergeZipFlowActivity)

Originally published at https://vtsen.hashnode.dev.