For years, Android developers have been locked in a dramatic, often tragic, romance with Bluetooth. We've wrestled with its quirks, begged it to just work, and shed silent tears over its mysterious connection drops.

But what if I told you that things are about to get better? What if I told you that with Android 16, the Bluetooth gods have finally smiled upon us? It's not a dream, my friends. It's the AOSP 16 Bluetooth Scanner, and it's here to bring a new hope to our weary developer souls.

In this handbook, we're going on a journey. A journey into the heart of AOSP 16's new Bluetooth features. We'll laugh, we'll cry (hopefully from joy this time), and we'll learn how to wield these new powers for good. We'll explore the magic of passive scanning, the drama of bond loss reasons, and the sheer convenience of getting service UUIDs without all the usual fuss.

By the end of this epic saga, you'll be able to:

• Build a Bluetooth scanner that's so efficient, it's practically psychic.

• Debug connection issues like a seasoned detective.

• Impress your friends and colleagues with your newfound Bluetooth mastery.

Prerequisites:

Before we dive in, it's a good idea to have a basic understanding of Android development and Kotlin. If you've ever tried to make two devices talk to each other and ended up wanting to throw your computer out the window, you're more than qualified.

So grab your favorite beverage, put on your coding cape, and let's get ready for the Bluetooth awakening!

Table of Contents

1. A Brief History of Bluetooth in Android

2. What's New in AOSP 16: The Three Musketeers

3. Deep Dive #1: Passive Scanning

4. Understanding the BluetoothLeScanner

5. Hands-On: Building Your First Passive Scanner

6. Deep Dive #2: Bluetooth Bond Loss Reasons

7. Deep Dive #3: Service UUIDs from Advertisements

8. Advanced Topics: Leveling Up Your Scanning Game

9. Real-World Use Cases: Where the Bluetooth Hits the Road

10. API Version Checking: How to Not Crash Your App

11. Testing and Debugging: The Fun Part (Said No One Ever)

12. Performance and Best Practices: How to Be a Good Bluetooth Citizen

13. Conclusion: The Future is Passive (and That's Okay)

A Brief History of Bluetooth (Or: How We Learned to Stop Worrying and Love the Radio Waves)

The Dark Ages: Classic Bluetooth

In the beginning, there was Classic Bluetooth. It was the digital equivalent of a loud, boisterous party guest. It could carry a lot of data (like your favorite tunes to a speaker), but it sure was a battery hog. It was great for streaming audio, but for small, infrequent data transfers? It was like using a fire hose to water a houseplant. Overkill, and frankly, a little messy.

Developers in this era spent their days wrestling with BluetoothAdapter, BluetoothDevice, and the dreaded BluetoothSocket. It was a time of great uncertainty, where a simple connection could take seconds, or... well, let's just say you could go make a cup of coffee. And the battery drain? Your users would watch their phone's power level plummet faster than a lead balloon.

The Renaissance: Enter Bluetooth Low Energy (BLE)

Then, with Android 4.3, a new hero emerged: Bluetooth Low Energy, or BLE. This wasn't your dad’s Bluetooth. BLE was sleek, efficient, and mysterious. It was designed for short bursts of data, sipping power like a fine wine instead of chugging it.

BLE was the cool kid on the block. It introduced us to a whole new world of possibilities: heart-rate monitors, smart watches, and a million and one IoT devices that could run for months on a single coin-cell battery. It was a game-changer.

But with great power came... great complexity. We had to learn a whole new language of GATT, GAP, services, and characteristics. It was like going from writing simple scripts to composing a full-blown opera. The potential was huge, but the learning curve was steep.

The Problem Child: Scanning

And then there was scanning. The act of finding these new, power-sipping devices. In the early days of BLE, scanning was still a bit of a wild west. It was an active, noisy process. Your phone would shout into the void, "IS ANYONE OUT THERE?", and then listen for replies. This worked, but it was still a significant power drain, especially if your app needed to scan for long periods.

It was the classic developer dilemma: you need to find devices, but you don't want to be the reason your user's phone is dead by lunchtime. For years, we walked this tightrope, balancing the need for discovery with the desperate plea for battery life.

This is the world that AOSP 16 was born into. A world crying out for a better way to scan. A world ready for a hero. And that hero, my friends, is passive scanning. But more on that in a bit...

What's New in AOSP 16? (Spoiler: It's Actually Cool)

Alright, let's get to the good stuff. What shiny new toys did the Android team give us in AOSP 16? It turns out, quite a few! But before we unwrap the presents, let's talk about the new delivery schedule, because even that is a little different now.

A Tale of Two Releases

In a shocking plot twist, Android decided to grace us with two major API releases in 2025. First, we got the main event, Android 16 (codenamed "Baklava," because who doesn't love a good pastry?), which landed in Q2. This is your traditional, big-bang release with all the behavior changes you've come to know and love (or fear).

But then, in Q4, we get a surprise second act: a minor release, which is where our new Bluetooth goodies made their grand entrance. This release is all about new features and APIs, without the scary, app-breaking changes. It's like getting a free dessert after you've already paid the bill.

The Three Musketeers of Bluetooth

So, what did this Q4 release bring to the Bluetooth party? I'm glad you asked. It brought three new heroes, ready to save us from our Bluetooth woes. I call them... The Three Musketeers.

These aren't just minor tweaks, folks. These are quality-of-life improvements that will fundamentally change how we build and debug Bluetooth-enabled apps. It's as if the Android team actually listened to our collective cries for help. (I know, I'm shocked too.)

In the next few sections, we're going to get up close and personal with each of these new features. We'll dive into the code, explore the use cases, and learn how to harness their power. So, get ready to meet our first musketeer: the strong, silent type known as Passive Scanning.

Deep Dive #1: Passive Scanning

Imagine you're in a library. You're looking for a friend, but you don't know where they are. You have two options:

• Active Scanning: You stand in the middle of the library and shout, "HEY, STEVE! ARE YOU HERE?" This is effective, but it's also loud, disruptive, and will get you kicked out by the librarian (who, in this analogy, is your user's battery).

• Passive Scanning: You quietly walk around the library, listening for your friend's distinctive, wheezing laugh. You don't say a word. You just listen. This is stealthy, efficient, and won't drain your social (or actual) battery.

For years, Android's Bluetooth scanning has been the guy shouting in the library. But with AOSP 16, we can finally be the quiet listener. This is the magic of passive scanning.

Active vs. Passive: The Technical Showdown

In the world of BLE, devices send out little packets of information called "advertisements." It's their way of saying, "Hey, I'm here, and this is what I do!"

• Active Scanning: When your phone performs an active scan, it hears an advertisement and then sends back a SCAN_REQ (Scan Request). It's basically saying, "Tell me more!" The peripheral device then replies with a SCAN_RSP (Scan Response), which contains extra information.

• Passive Scanning: With passive scanning, your phone hears the advertisement... and that's it. It doesn't send anything back. It just takes note of the initial advertisement and moves on. It's a one-way conversation.

Why Go Passive? The Power of Silence

So, why is this such a big deal? Two words: power consumption. Every time your phone's radio has to transmit something (like a SCAN_REQ), it uses energy. If your app is scanning for devices all the time, those little transmissions add up, and your user's battery pays the price.

By switching to passive scanning, you're telling the radio to just listen. No talking, just listening. This dramatically reduces the power needed for scanning, making it a perfect solution for apps that need to monitor for nearby devices over long periods.

The Code: How to Become a Bluetooth Ninja

So, how do we implement this newfound stealth mode? It's surprisingly simple. It all comes down to the ScanSettings you use when you start your scan.

Previously, you might have done something like this:

val settings = ScanSettings.Builder()
    .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
    .build()

Now, with AOSP 16, we have a new option. To enable passive scanning, you simply set the scan type:

// This is the magic line!
.setScanMode(ScanSettings.SCAN_TYPE_PASSIVE)

Wait, that can't be right. The documentation says SCAN_TYPE_PASSIVE is a scan type, not a scan mode. And you're right! My apologies, I got a little too excited. The correct way to do this is by setting the scan mode to passive. Let's try that again.

val settings = ScanSettings.Builder()
    // The actual magic line!
    .setScanMode(ScanSettings.SCAN_MODE_OPPORTUNISTIC) // This is the closest to passive
    .build()

Hold on, that's not quite right either. It seems I've gotten my wires crossed. Let's consult the official scrolls... Ah, here it is! The ScanSettings.Builder has a new method in Android 16 QPR2. It's not setScanMode, it's a whole new setting.

Let's get this right once and for all. Here is the correct way to enable passive scanning:

// Available in Android 16 QPR2 and later
val settings = ScanSettings.Builder()
    // This is the REAL magic line, I promise!
    .setScanType(ScanSettings.SCAN_TYPE_PASSIVE) 
    .build()

And there you have it. With that one line, you've transformed your app from a loud, battery-guzzling tourist to a silent, efficient Bluetooth ninja. Your users' batteries will thank you.

Of course, there's a trade-off. Since you're not sending a SCAN_REQ, you won't get the extra data from the SCAN_RSP. But for many use cases, the initial advertisement is all you need. And the power savings are more than worth it.

Now that we've mastered the art of silent scanning, let's move on to the next piece of the puzzle: understanding the BluetoothLeScanner itself.

Understanding BluetoothLeScanner (The Star of Our Show)

Before we can truly master the art of Bluetooth scanning, we must first understand our primary weapon: the BluetoothLeScanner. Think of it as the PKE Meter from Ghostbusters. It's the tool we use to detect the invisible energy (in our case, BLE advertisements) floating all around us. But how does this ghost-hunting gadget actually work?

The Architecture: A Peek Behind the Curtain

At a high level, the process is pretty straightforward. Your app, living comfortably in its own little world, decides it wants to find some BLE devices. It grabs an instance of the BluetoothLeScanner and says, "Hey, go look for stuff."

Under the hood, a lot is happening. The BluetoothLeScanner talks to the Android Bluetooth stack (codenamed "Fluoride," which sounds like something your dentist would be very proud of). The stack then communicates with the device's Bluetooth controller, the actual hardware that does the sending and receiving of radio waves. It's a classic case of "it's more complicated than it looks."

The Alphabet Soup: GATT, GAP, and Friends

When you venture into the world of BLE, you'll quickly run into a whole bunch of acronyms. Don't panic! They're not as scary as they look. The two most important ones to understand are GAP and GATT.

• GAP (Generic Access Profile): This is all about how devices discover and connect to each other. Think of GAP as the bouncer at a nightclub. It decides who gets to talk to whom. It manages advertising (the device shouting "I'm here!") and scanning (your app listening for those shouts). Our BluetoothLeScanner is a key player in the GAP-verse.

• GATT (Generic Attribute Profile): Once two devices are connected, GATT takes over. It defines how they exchange data. Think of GATT as the actual conversation happening inside the nightclub. It's all about Services, Characteristics, and Descriptors. A device might have a "Heart Rate Service," which contains a "Heart Rate Measurement Characteristic." Your app reads from or writes to these characteristics to get the data it needs.

For the purpose of scanning, we're mostly living in the world of GAP. We're the ones standing outside the club, listening for interesting advertisements.

The Scanning Lifecycle: A Dramatic Play in Three Acts

The life of a Bluetooth scan is a simple, yet elegant, drama.

• Act I: The Preparation. Your app decides it's time to scan. It gets the BluetoothLeScanner, creates a set of ScanFilters (to only find specific devices) and ScanSettings (to define how to scan, like our new passive mode), and defines a ScanCallback.

• Act II: The Scan. Your app calls startScan(). The Bluetooth radio springs to life, listening for advertisements that match your filters. When it finds one, it reports back to your app via the onScanResult() method in your ScanCallback.

• Act III: The End. When your app has had enough (or, more importantly, when you've found what you're looking for), it calls stopScan(). The radio powers down, and all is quiet once more. It's crucial to always stop your scan when you're done. A rogue scan is the number one cause of "my battery dies in an hour" complaints from users.

And that's the BluetoothLeScanner in a nutshell. It's our gateway to the world of BLE discovery. It's powerful, it's complex, but as we're learning, it's getting smarter and more efficient with every new Android release. Now that we know our tool, let's get our hands dirty and build our first passive scanner!

Hands-On: Building Your First Passive Scanner

Theory is great, but let's be honest, we're developers. We learn by doing (or by copying pasting from Stack Overflow). It's time to roll up our sleeves, fire up Android Studio, and build something. We're going to create a simple app that uses our newfound passive scanning powers to find nearby BLE devices.

Step 1: The Permission Inquisition

Before we write a single line of Kotlin, we must appease the Android permission gods. This is a sacred and often frustrating ritual. For Bluetooth scanning, the rules have changed a bit over the years.

First, open your AndroidManifest.xml and add the following:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- For Android 12 (API 31) and above -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

<!-- For older versions, you needed location permissions -->
<!-- You might still need this if you support older devices -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Looking at the permissions we've declared above, you can see the evolution of Android's Bluetooth permission model playing out in real-time.

The first two permissions, BLUETOOTH and BLUETOOTH_ADMIN, are the old guard. They've been around since the early days of Android and provide basic Bluetooth functionality and the ability to discover devices. Then we have BLUETOOTH_SCAN, which was introduced in Android 12 (API 31) and represents a major shift in how Google thinks about privacy.

Yes, you're seeing that right. In the good old days (before Android 12), Google decided that finding a Bluetooth device was basically the same as knowing your user's exact location. It kind of made sense: after all, if you can see which Bluetooth beacons are nearby, you can triangulate your position. But it was also a bit creepy to ask for location just to find a pair of headphones. This led to the awkward situation where users would see a simple Bluetooth scanner app asking for their precise location and understandably get suspicious.

Thankfully, with Android 12, they introduced the BLUETOOTH_SCAN permission, which is much more sensible. This permission finally allows apps to scan for Bluetooth devices without needing to ask for location access, which makes a lot more sense from a user perspective. You'll still need to request this permission at runtime, but at least you don't have to explain to your users why your simple gadget-finder app wants to know where they live.

However, notice those last two permissions for location access. Those are the remnants of the old system. If you're building an app that needs to support older devices running Android 11 or below, you'll need to keep these location permissions in your manifest for backwards compatibility. On modern devices, the BLUETOOTH_SCAN permission alone will do the job.

Step 2: The Code Awakens

Alright, let's get to the fun part. Here's a breakdown of how to implement the passive scanner in your Activity or Fragment.

Get the Scanner

First, we need to get an instance of the BluetoothLeScanner.

private val bluetoothAdapter: BluetoothAdapter? by lazy {
    val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
    bluetoothManager.adapter
}

private val bleScanner: BluetoothLeScanner? by lazy {
    bluetoothAdapter?.bluetoothLeScanner
}

Let's break down what's happening in the code above. We're using Kotlin's lazy delegation, which is a fancy way of saying "don't create this object until I actually need it." This is a good practice because getting the Bluetooth adapter involves system calls, and there's no point in doing that work if we never actually use it.

First, we grab the BluetoothManager from the system services. Think of the BluetoothManager as the gatekeeper to all things Bluetooth on your device. From this manager, we get the BluetoothAdapter, which represents your device's physical Bluetooth hardware. Notice that we're declaring it as nullable (BluetoothAdapter?) because, believe it or not, not every Android device has Bluetooth. Some tablets or obscure devices might not have the hardware, so we need to be prepared for that possibility.

Once we have the adapter, we can ask it for the BluetoothLeScanner. This is the actual object we'll use to perform our scans. Again, we're using the safe call operator (?.) because if the adapter is null (no Bluetooth hardware), we definitely can't get a scanner from it. This defensive programming might seem paranoid, but it's what separates apps that crash mysteriously from apps that gracefully handle edge cases.

Define the Callback

This is where the magic happens. The ScanCallback is an object that will listen for scan results. We need to override two methods: onScanResult and onScanFailed.

private val scanCallback = object : ScanCallback() {
    override fun onScanResult(callbackType: Int, result: ScanResult) {
        // We found a device! 
        // The 'result' object contains the device, RSSI, and advertisement data.
        Log.d("BleScanner", "Found device: ${result.device.address}, RSSI: ${result.rssi}")
    }

    override fun onScanFailed(errorCode: Int) {
        // This is the universe's way of telling you to take a break.
        // Or that something went horribly wrong.
        Log.e("BleScanner", "Scan failed with error code: $errorCode")
    }
}

The ScanCallback we've defined above is your app's ears in the Bluetooth world. When the scanner finds a device, it doesn't just store the information somewhere, it actively calls back to your app through this callback object. This is classic event-driven programming, and it's how Android keeps your app responsive without blocking the main thread.

The onScanResult method is called every time the scanner discovers a device that matches your filters (or any device if you're not using filters). The result parameter is a treasure trove of information. It contains the BluetoothDevice object (which has the device's MAC address and name), the RSSI value (Received Signal Strength Indicator – basically how close the device is, with higher numbers meaning closer), and the raw advertisement data that the device is broadcasting.

In our simple example above, we're just logging the MAC address and RSSI, but in a real app, you'd probably want to update your UI, add the device to a list, or trigger a connection.

The callbackType parameter tells you why this callback was triggered. It could be CALLBACK_TYPE_ALL_MATCHES (the default, meaning "here's every device we found"), CALLBACK_TYPE_FIRST_MATCH (the first time we saw this device), or CALLBACK_TYPE_MATCH_LOST (we haven't seen this device in a while, so it probably left). We'll dive deeper into these types in the advanced section.

Then there's onScanFailed, the method we all hope never gets called but that we absolutely need to handle. This is invoked when something goes catastrophically wrong with the scan. Maybe the Bluetooth adapter got turned off mid-scan, maybe your app doesn't have the right permissions, or maybe the Bluetooth controller just had a bad day. The errorCode will give you a hint about what went wrong, and you should always log this and handle it gracefully – perhaps by showing a message to the user or attempting to restart the scan after a delay.

Configure the Scan

Now, we create our ScanSettings. This is where we tell Android that we want to be a passive, battery-saving ninja.

val scanSettings = ScanSettings.Builder()
    .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER) // Let's be nice to the battery
    .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES)
    .setMatchMode(ScanSettings.MATCH_MODE_AGGRESSIVE)
    .setNumOfMatches(ScanSettings.MATCH_NUM_ONE_ADVERTISEMENT) // Report each ad once
    .setReportDelay(0L) // Report immediately
    // And here's the star of the show!
    .setScanType(ScanSettings.SCAN_TYPE_PASSIVE)
    .build()

The ScanSettings object we're building above is like a detailed instruction manual for the Bluetooth scanner. Each method call fine-tunes exactly how the scan should behave, and getting these settings right is the difference between a battery-friendly app and one that gets uninstalled within hours.

Let's walk through each setting. First, setScanMode(SCAN_MODE_LOW_POWER) tells the scanner to use a low-power scanning mode, which means it will scan in intervals rather than continuously. This is perfect for most use cases where you don't need instant results and want to preserve battery life. The scanner will wake up, scan for a bit, sleep, and repeat. It's the Bluetooth equivalent of taking power naps.

Next, setCallbackType(CALLBACK_TYPE_ALL_MATCHES) means we want to be notified every time the scanner finds a matching device. This is the default behavior and is what you'll use most of the time. As we mentioned earlier, you can also use CALLBACK_TYPE_FIRST_MATCH or CALLBACK_TYPE_MATCH_LOST for more sophisticated presence detection.

The setMatchMode(MATCH_MODE_AGGRESSIVE) setting controls how aggressively the hardware should try to match devices against your filters. MATCH_MODE_AGGRESSIVE means "report matches quickly, even if you're not 100% certain," while MATCH_MODE_STICKY means "wait until you're really sure before reporting." Aggressive mode gives you faster results but might occasionally give you false positives.

Then we have setNumOfMatches(MATCH_NUM_ONE_ADVERTISEMENT), which tells the scanner to report a device after seeing just one advertisement from it. The alternative is MATCH_NUM_FEW_ADVERTISEMENT, which waits for multiple advertisements before reporting. Using one advertisement gives you faster discovery, while waiting for a few reduces false positives from devices that are just passing by.

The setReportDelay(0L) setting is crucial. A delay of 0 means "report results immediately." If you set this to, say, 5000 milliseconds, the scanner would batch up results and deliver them every 5 seconds. Batching is great for background scanning (as we discussed in the advanced section), but for foreground scanning where the user is actively waiting, immediate reporting is what you want.

And finally, the star of our show: setScanType(SCAN_TYPE_PASSIVE). This is the new API from Android 16 QPR2 that transforms our scanner into a silent listener. Instead of actively sending scan requests to every device it hears, it just listens to the advertisements floating through the air. This single setting can dramatically reduce your app's battery consumption during scanning. It's the feature we've been waiting for, and it's glorious.

Start and Stop the Scan

Finally, we need functions to start and stop our scan. Remember: always stop your scan! A forgotten scan is a battery-killing monster.

private fun startBleScan() {
    // Don't forget to request permissions first!
    if (bleScanner != null) {
        // You can add ScanFilters here to search for specific devices
        val scanFilters: List<ScanFilter> = listOf() 
        bleScanner.startScan(scanFilters, scanSettings, scanCallback)
        Log.d("BleScanner", "Scan started.")
    } else {
        Log.e("BleScanner", "Bluetooth is not available.")
    }
}

private fun stopBleScan() {
    if (bleScanner != null) {
        bleScanner.stopScan(scanCallback)
        Log.d("BleScanner", "Scan stopped.")
    }
}

These two functions above are the on/off switches for your Bluetooth scanner, and they're deceptively simple for how important they are. Let's break down what's happening in each one.

In startBleScan(), we first check if the bleScanner is not null. This is our safety net: if the device doesn't have Bluetooth hardware or if Bluetooth is disabled, the scanner will be null, and we don't want to crash by trying to call methods on a null object. If the scanner exists, we call startScan() with three parameters: a list of ScanFilter objects, our carefully crafted ScanSettings, and the ScanCallback we defined earlier.

The scanFilters list is currently empty in our example, which means "find all BLE devices." In a real-world app, you'd typically add filters here to narrow down your search.

For instance, if you're building an app that only works with heart rate monitors, you'd create a filter that only matches devices advertising the Heart Rate Service UUID. This is crucial for both performance and battery life: why wake up your app for every random Bluetooth toothbrush when you only care about fitness trackers?

The startScan() method kicks off the scanning process. From this point on, the Bluetooth radio is actively (or in our case, passively) listening for advertisements, and your scanCallback will start receiving results. This is an asynchronous operation, meaning your code doesn't block here waiting for results – rather, it continues executing, and the results come in through the callback whenever they're available.

Now let's talk about stopBleScan(), which might be the most important function you write. When you call stopScan() with your callback, you're telling the Bluetooth radio, "Okay, we're done here, you can go back to sleep." This immediately stops the scanning process and releases the resources.

The critical thing to understand is that if you don't call this, the scan will continue running indefinitely, draining your user's battery like a vampire at an all-you-can-eat blood bank. This is why we emphasize it so much: a forgotten stopScan() call is one of the most common causes of battery drain complaints in Bluetooth apps.

Notice that we're passing the same scanCallback object to stopScan() that we used in startScan(). This is how Android knows which scan to stop – you might theoretically have multiple scans running with different callbacks (though that's rarely a good idea). Always make sure you're stopping the same scan you started by using the same callback reference.

Putting It All Together

Here's a complete example you can drop into an Activity. Just remember to handle the runtime permissions!

// In your Activity class

class MainActivity : AppCompatActivity() {

    // ... (lazy properties for adapter and scanner from above)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ... your UI setup ...

        // Example: Start scan on button click
        val startButton = findViewById<Button>(R.id.startButton)
        startButton.setOnClickListener {
            // You MUST request permissions before calling this!
            startBleScan()
        }

        // Example: Stop scan on another button click
        val stopButton = findViewById<Button>(R.id.stopButton)
        stopButton.setOnClickListener {
            stopBleScan()
        }
    }

    // ... (scanCallback, startBleScan, stopBleScan functions from above)

    override fun onPause() {
        super.onPause()
        // Always stop scanning when the activity is not visible.
        stopBleScan()
    }
}

The complete example above shows how all the pieces fit together in a real Activity. This is a minimal but functional Bluetooth scanner that you can actually run. Let's highlight a few important patterns we're using here.

First, notice how we're tying the scan lifecycle to user actions through button clicks. This is a common pattern: the user explicitly starts and stops the scan, giving them control over when the app is using Bluetooth. This is both good UX and good for battery life, as the scan only runs when the user wants it to.

But here's the really important part: the onPause() override. This is a critical safety net. When your Activity goes into the background (maybe the user pressed the home button, or they switched to another app), onPause() is called, and we immediately stop the scan. This is essential because if the user can't see your app, they don't need scan results, and there's no reason to drain their battery. This pattern ensures that even if the user forgets to press the "Stop" button, the scan won't run forever in the background.

You might be wondering, "What about onResume()? Shouldn't we restart the scan when the user comes back?" That's a design decision. In some apps, you might want to automatically restart scanning in onResume(). In others, you might want the user to explicitly press "Start" again. It depends on your use case. For a device-finding app where the user is actively searching, auto-resuming makes sense. For a monitoring app that runs in the background, you might want more explicit control.

One crucial thing we haven't shown in this example is runtime permission handling. Remember those permissions we declared in the manifest? On Android 6.0 and above, you can't just declare them, you have to actually request them from the user at runtime. Before calling startBleScan(), you should check if you have the necessary permissions and, if not, request them using ActivityCompat.requestPermissions(). If you try to start a scan without the proper permissions, it will fail silently (or loudly, depending on the Android version), and you'll be left scratching your head wondering why nothing is working.

And there you have it! You've just built your first AOSP 16 passive Bluetooth scanner. It's lean, it's mean, and it's incredibly power-efficient. The scanner listens silently for BLE advertisements, reports them through your callback, and stops gracefully when it's not needed.

Now, let's move on to our next topic: what to do when things go wrong. It's time to talk about breakups... Bluetooth bond breakups, that is.

Deep Dive #2: Bluetooth Bond Loss Reasons

Ah, the Bluetooth bond. It's a beautiful, sacred thing. It's the digital equivalent of exchanging friendship bracelets. When you bond your phone with your headphones, you're creating a long-term, trusted relationship. They share secret keys, they remember each other, and they promise to connect automatically, saving you the hassle of pairing every single time. It's a beautiful romance.

Until it's not.

Suddenly, one day, they just... forget each other. The connection is gone. The trust is broken. And your app is left in the middle, trying to play therapist, with no idea what went wrong. You've been ghosted. And until now, Android has been no help. You'd get a notification that the bond state is now BOND_NONE, but that's it. No explanation. No closure. Just the cold, hard silence of a failed connection.

Finally, Some Closure!

But our friends on the Android team have clearly been through some tough breakups, because in AOSP 16, they've given us the gift of closure. Introducing BluetoothDevice.EXTRA_BOND_LOSS_REASON. It's a new extra that comes with the ACTION_BOND_STATE_CHANGED broadcast, and it's here to tell you why the bond was lost. It's like getting a breakup text that actually explains what happened!

Now, when a bond is broken, you can get a specific reason code. Think of them as the classic breakup excuses, but for Bluetooth:

The Code: Playing Detective

So, how do we get this juicy gossip? We need to set up a BroadcastReceiver to listen for bond state changes.

// Create a BroadcastReceiver to listen for bond state changes
private val bondStateReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == BluetoothDevice.ACTION_BOND_STATE_CHANGED) {
            val device: BluetoothDevice? = intent.getParcelableExtra(BluetoothDevice.EXTRA_DEVICE)
            val bondState = intent.getIntExtra(BluetoothDevice.EXTRA_BOND_STATE, BluetoothDevice.ERROR)
            val previousBondState = intent.getIntExtra(BluetoothDevice.EXTRA_PREVIOUS_BOND_STATE, BluetoothDevice.ERROR)

            // Check if we went from bonded to not bonded
            if (bondState == BluetoothDevice.BOND_NONE && previousBondState == BluetoothDevice.BOND_BONDED) {
                Log.d("BondBreakup", "We got dumped by ${device?.address}!")

                // Now, let's find out why...
                val reason = intent.getIntExtra(BluetoothDevice.EXTRA_BOND_LOSS_REASON, -1)

                when (reason) {
                    // Note: The actual constant values are in the Android SDK
                    BluetoothDevice.BOND_LOSS_REASON_REMOTE_DEVICE_REMOVED -> {
                        Log.d("BondBreakup", "Reason: The remote device removed the bond.")
                        // You could show a message to the user: "Your headphones seem to have forgotten you. Please try pairing again."
                    }
                    // ... handle other reasons ...
                    else -> {
                        Log.d("BondBreakup", "Reason: It's complicated (Unknown reason code: $reason)")
                    }
                }
            }
        }
    }
}

// In your Activity or Service, register the receiver
override fun onResume() {
    super.onResume()
    val filter = IntentFilter(BluetoothDevice.ACTION_BOND_STATE_CHANGED)
    registerReceiver(bondStateReceiver, filter)
}

override fun onPause() {
    super.onPause()
    // Don't forget to unregister!
    unregisterReceiver(bondStateReceiver)
}

The code above implements a detective system for Bluetooth bond breakups, and it's more sophisticated than it might first appear. Let's walk through how this broadcast receiver pattern works and why it's so powerful.

First, we're creating a BroadcastReceiver, which is Android's way of letting your app listen for system-wide events. Think of it as subscribing to a notification service, whenever something interesting happens in the Android system (like a bond state change), the system broadcasts an "intent" to all registered listeners. Our receiver is one of those listeners.

In the onReceive() method, we first check if the incoming intent's action is ACTION_BOND_STATE_CHANGED. This is crucial because broadcast receivers can potentially receive many different types of intents, and we only care about bond state changes. Once we've confirmed this is the right type of event, we extract the relevant information from the intent using getParcelableExtra() and getIntExtra().

The device object tells us which Bluetooth device this event is about. After all, you might be bonded to multiple devices (your headphones, your smartwatch, your car), and we need to know which one just broke up with us. The bondState tells us the current state (are we bonded, bonding, or not bonded?), and previousBondState tells us what the state was before this change occurred.

The key logic happens in our conditional check: if (bondState == BluetoothDevice.BOND_NONE && previousBondState == BluetoothDevice.BOND_BONDED). This is checking for the specific transition from "bonded" to "not bonded," which is the digital equivalent of a breakup. We're not interested in the bonding process itself (going from none to bonding to bonded) – we only care about when an existing bond is lost.

Once we've detected a breakup, we extract the new EXTRA_BOND_LOSS_REASON from the intent. This is the star feature from AOSP 16 that finally gives us closure. The reason code tells us exactly why the bond was lost – was it the remote device that ended things? Did the user manually forget the device? Did authentication fail? Each reason code corresponds to a different scenario, and you can handle each one appropriately.

In the example above, we're using a when expression to handle different reason codes. For BOND_LOSS_REASON_BREDR_INCOMING_PAIRING, we know the other device initiated the breakup, so we can show a helpful message like "Your headphones seem to have forgotten you. Please try pairing again." For other reasons, you'd add more branches to handle them specifically.

Now, notice the lifecycle management at the bottom. We register our receiver in onResume() and unregister it in onPause(). This is critical: if you forget to unregister a broadcast receiver, it will continue to receive broadcasts even after your Activity is destroyed, which can cause memory leaks and crashes. The pattern of registering in onResume() and unregistering in onPause() ensures that we only listen for bond changes when our Activity is visible and active.

This is a huge step forward for debugging and for user experience. Instead of just telling the user "Connection failed," you can now give them actionable advice based on the specific reason the bond was lost. It's like being a helpful, informed relationship counselor instead of a confused bystander who can only shrug and say "I don't know what happened."

Now that we've dealt with the emotional baggage of breakups, let's move on to something a little more lighthearted: speed dating for Bluetooth devices.

Deep Dive #3: Service UUIDs from Advertisements

Let's talk about finding a compatible partner... for your app. In the world of BLE, not all devices are created equal. A heart rate monitor is very different from a smart lightbulb. So how does your app know if it's talking to the right kind of device? The answer is the Service UUID.

What in the World is a Service UUID?

A Service UUID (Universally Unique Identifier) is like a device's job title. It's a unique, 128-bit number that says, "I am a device that provides a Heart Rate Service" or "I am a device that provides a Battery Service." It's the single most important piece of information for determining what a device can do.

The Old Way: The Awkward First Date

Traditionally, finding out a device's services was a whole ordeal. It was like going on a full, three-course dinner date just to find out the other person's job. The process went something like this:

1. Scan: Find the device.

2. Connect: Establish a connection (a slow and power-hungry process).

3. Discover Services: Ask the device, "So... what do you do for a living?" and wait for it to list all its services.

4. Evaluate: Check if the list of services contains the one you're interested in.

5. Disconnect (or stay connected): If it's not the right device, you have to break up (disconnect) and move on. What a waste of time and energy!

This is incredibly inefficient, especially if you're in a crowded room with dozens of BLE devices and you're only looking for one specific type.

The New Way: The Glorious Name Tag

Wouldn't it be great if everyone at a party just wore a name tag with their job title on it? That's exactly what AOSP 16 has given us with BluetoothDevice.EXTRA_UUID_LE. Many BLE devices are already polite enough to include their primary service UUID in their advertisement packets. It's their way of shouting, "I'M A HEART RATE MONITOR!" to the whole room.

Before AOSP 16, getting this information out of the advertisement packet was a messy, manual process of parsing the raw byte array of the scan record. It was doable, but it was the kind of code that you'd write once, pray it worked, and never touch again.

Now, Android does the dirty work for us! The system automatically parses the advertising data and, if it finds any service UUIDs, it conveniently hands them to you in the ScanResult.

The Code: Reading the Name Tag

This new feature makes our ScanCallback even more powerful. We can now check the device's job title the moment we discover it, without ever having to connect.

private val scanCallback = object : ScanCallback() {
    override fun onScanResult(callbackType: Int, result: ScanResult) {
        Log.d("BleSpeedDating", "Found device: ${result.device.address}")

        // Let's check their name tag!
        val serviceUuids = result.scanRecord?.serviceUuids
        if (serviceUuids.isNullOrEmpty()) {
            Log.d("BleSpeedDating", "This one is mysterious. No service UUIDs in the ad.")
            return
        }

        // Define the UUID we're looking for (e.g., the standard Heart Rate Service UUID)
        val heartRateServiceUuid = ParcelUuid.fromString("0000180D-0000-1000-8000-00805F9B34FB")

        if (serviceUuids.contains(heartRateServiceUuid)) {
            Log.d("BleSpeedDating", "It's a match! This is a heart rate monitor. Let's connect!")
            // Now you can proceed to connect to result.device, knowing it's the right one.
            stopBleScan() // We found what we were looking for
            // connectToDevice(result.device)
        } else {
            Log.d("BleSpeedDating", "Not a match. Moving on.")
        }
    }

    // ... onScanFailed ...
}

The code above demonstrates the power of reading service UUIDs directly from advertisement data, and it's a game-changer for device discovery. Let's break down exactly what's happening and why this is such a significant improvement.

When we receive a scan result in our callback, the result object contains a scanRecord property. This scan record is essentially the raw advertisement packet that the BLE device broadcast into the air.

Before AOSP 16, if you wanted to extract service UUIDs from this data, you'd have to manually parse the byte array, understand the BLE advertisement format, handle different data types, and pray you didn't make an off-by-one error. It was the kind of code that worked once and then you never touched it again out of fear.

Now, with the improvements in AOSP 16, Android does all that messy parsing for us. We can simply call result.scanRecord?.serviceUuids and get back a nice, clean list of ParcelUuid objects. The safe call operator (?.) is important here because not all devices include a scan record in their results, and we need to handle that gracefully.

After retrieving the service UUIDs, we check if the list is null or empty. Some devices don't include service UUIDs in their advertisements. They might be using a proprietary format, or they might just be poorly configured. If there are no UUIDs, we log a message and return early. There's no point in continuing if we can't identify what the device does.

Next, we define the UUID we're looking for. In this example, we're searching for heart rate monitors, so we use the standard Heart Rate Service UUID: 0000180D-0000-1000-8000-00805F9B34FB. This is a UUID defined by the Bluetooth SIG (Special Interest Group), and any compliant heart rate monitor will advertise this UUID. You can find a complete list of standard service UUIDs in the Bluetooth specifications, or you can use custom UUIDs if you're building your own BLE peripherals.

The magic happens in the if (serviceUuids.contains(heartRateServiceUuid)) check. This is where we're doing our speed dating: we're checking the device's "name tag" to see if it matches what we're looking for.

If it does, we've found our match! We can immediately stop scanning (because why keep looking when we've found what we need?) and proceed to connect to the device. We know, with certainty, that this device is a heart rate monitor, so we won't waste time and battery connecting to random devices only to discover they're not what we need.

If the UUID doesn't match, we simply log "Not a match" and move on. The callback will be called again when the next device is found, and we'll repeat this process until we find our heart rate monitor or the user stops the scan.

This is a massive performance improvement over the old approach. Previously, you'd have to connect to every device you found, perform service discovery (which involves multiple round-trip communications with the device), check if it has the services you need, and then disconnect if it doesn't. Each connection attempt takes time, uses battery, and creates unnecessary radio traffic.

Now, you can filter and identify devices at lightning speed, all at the scanning stage. No more awkward first dates where you connect to a smart lightbulb thinking it might be a fitness tracker. Just efficient, targeted connections.

This is particularly useful for apps that need to find a specific type of sensor or peripheral in a sea of irrelevant devices. Imagine you're in a hospital with hundreds of BLE-enabled medical devices, or in a smart home with dozens of sensors and actuators. Being able to instantly identify the right device from its advertisement is the difference between a responsive, professional app and one that feels sluggish and unreliable.

We've now met all three of our Bluetooth musketeers: passive scanning for battery efficiency, bond loss reasons for better debugging, and service UUIDs from advertisements for faster device identification. But our journey isn't over. It's time to venture into the deep woods of advanced scanning techniques.

Advanced Topics: Filtering, Batching, and Other Sorcery

Alright, you've mastered the basics. You can scan passively, you can get closure on your connection breakups, and you can speed-date devices like a pro. You're no longer a Bluetooth padawan. It's time to become a Jedi Master.

Let's dive into the advanced arts of filtering, batching, and other optimization sorcery that will make your app a true battery-saving champion.

Hardware Filtering: Your Personal Assistant

Imagine you're a celebrity, and you've hired a personal assistant. You don't want to be bothered by every single person who wants an autograph. So, you give your assistant a list: "Only let me know if you see my agent or my mom." Your assistant then stands at the door and only bothers you when someone on the list shows up.

This is exactly what hardware filtering does. Instead of your app's code (the celebrity) being woken up for every single Bluetooth device the radio sees, you can offload the filtering logic to the Bluetooth controller itself (the personal assistant). This is a feature that's been around since Android 6.0, but it's more important than ever.

Why is this so great? Because your app's code can stay asleep. The main processor (the AP) doesn't have to wake up every time a random Bluetooth toothbrush advertises itself. The Bluetooth controller, which is much more power-efficient, handles the filtering. The AP only wakes up when the controller finds a device that matches your criteria.

The Code: Building Your VIP List

You implement this using ScanFilter. You can filter by a device's name, its MAC address, or, most usefully, by the Service UUID it's advertising.

// We only want to be bothered if we see a heart rate monitor.
val heartRateServiceUuid = ParcelUuid.fromString("0000180D-0000-1000-8000-00805F9B34FB")

val filter = ScanFilter.Builder()
    .setServiceUuid(heartRateServiceUuid)
    .build()

val scanFilters: List<ScanFilter> = listOf(filter)

// Now, when you start your scan, pass in this list
bleScanner.startScan(scanFilters, scanSettings, scanCallback)

The code above shows how to create a hardware-level filter that dramatically improves both battery life and app performance. Let's dive deep into what's happening here and why this is such a powerful technique.

We start by defining the service UUID we're interested in – in this case, the standard Heart Rate Service UUID. This is the same UUID we used in the previous example, but now we're using it in a fundamentally different way. Instead of checking the UUID in our app's code after receiving scan results, we're telling the Bluetooth hardware itself to only report devices that match this UUID.

The ScanFilter.Builder() is our tool for constructing this filter. It's a builder pattern, which means we can chain multiple methods together to configure exactly what we're looking for. In this example, we're calling setServiceUuid(heartRateServiceUuid), which tells the filter to only match devices that advertise this specific service.

But the builder has many other options you can use:

• setDeviceName() – Match devices with a specific name (like "My Heart Monitor")

• setDeviceAddress() – Match a specific device by its MAC address (useful if you've already paired with a device and want to find it again)

• setManufacturerData() – Match devices based on manufacturer-specific data in their advertisements

• setServiceData() – Match based on service data included in the advertisement

You can even combine multiple criteria in a single filter. For example, you could create a filter that matches devices with a specific service UUID and a specific manufacturer ID. The more specific your filter, the fewer false positives you'll get.

After building our filter, we create a list containing it. Why a list? Because you can have multiple filters, and a device will match if it satisfies any of the filters in the list. For instance, you might create one filter for heart rate monitors and another for blood pressure monitors, and your scan will report devices that match either one. This is an OR operation: the device doesn't need to match all filters, just one of them.

Finally, we pass this list of filters to startScan() along with our scan settings and callback. This is where the magic happens. When you provide filters, Android doesn't just filter the results in your app's code. It pushes these filters down to the Bluetooth controller hardware itself. This means the filtering happens at the lowest level, before your app is even notified.

Here's why this is so powerful: without filters, every time the Bluetooth radio hears an advertisement from any device (your neighbor's smart toaster, someone's fitness tracker walking by, the Bluetooth speaker three rooms away), it has to wake up your app's process, deliver the scan result, and let your code decide if it cares about this device. Each of these wake-ups costs battery and processing time.

With hardware filters, the Bluetooth controller silently ignores all the devices that don't match your criteria. Your app stays asleep. The main processor stays asleep. Only when a heart rate monitor is detected does the hardware wake up your app and deliver the result. It's like having a bouncer at a club who only lets in people on the VIP list. Everyone else is turned away at the door, and you never even know they were there.

By using a ScanFilter, you're telling the hardware, "Don't wake me up unless you see a heart rate monitor." It's the ultimate power-saving move for background scanning. Combined with passive scanning and batch reporting, you can create a Bluetooth scanning system that runs for hours or even days with minimal battery impact. This is how professional-grade apps handle long-term device monitoring without destroying battery life.

Batch Scanning: The Daily Report

Let's go back to our celebrity analogy. Sometimes, you don't need to be interrupted the moment your mom shows up. You'd rather just get a report at the end of the day: "Today, your mom stopped by twice, and your agent called once." This is batch scanning.

Instead of delivering scan results to your app in real-time, the Bluetooth controller can collect them and deliver them in a big batch. This is another incredible power-saving feature. Your app can sleep for long periods, then wake up, process a whole bunch of results at once, and go back to sleep.

You enable this with the setReportDelay() method in your ScanSettings.

val scanSettings = ScanSettings.Builder()
    // ... other settings ...
    // Deliver results every 5 seconds (5000 milliseconds)
    .setReportDelay(5000)
    .build()

When you use a report delay, your onScanResult callback will be replaced by onBatchScanResults, which gives you a List<ScanResult>.

private val scanCallback = object : ScanCallback() {
    override fun onBatchScanResults(results: List<ScanResult>) {
        Log.d("BatchScanner", "Here's your daily report! Found ${results.size} devices.")
        for (result in results) {
            // Process each result
        }
    }

    // ... onScanFailed ...
}

The batch scanning mechanism shown above is one of the most underutilized power-saving features in Android Bluetooth, and understanding how it works can transform your app's battery profile. Let's break down exactly what's happening under the hood and when you should use this technique.

When you set a report delay of 5000 milliseconds (5 seconds) in the code above, you're fundamentally changing how the scanning pipeline works. Instead of the Bluetooth controller immediately waking up your app every time it sees a device, it acts like a diligent assistant taking notes. For those 5 seconds, the controller silently collects every scan result it encounters, storing them in its own internal buffer. Your app remains completely asleep during this time – no CPU cycles wasted, no battery drained by context switches or process wake-ups.

After the 5-second delay expires, the controller delivers all the accumulated results in one batch to your onBatchScanResults() callback. This is where the power savings come from: instead of waking up your app 50 times if 50 devices were detected, it wakes up once and hands you all 50 results at the same time. Your app can then efficiently process this batch – maybe updating a UI list, logging the data, or checking for specific devices – and then go back to sleep until the next batch arrives.

The results parameter in onBatchScanResults() is a List<ScanResult>, and each ScanResult in the list represents a single advertisement that was heard during the batching period. It's important to note that if the same device advertises multiple times during the delay period, you might receive multiple results for that device in the batch. The list isn't automatically deduplicated – that's your job if you need it.

In the example above, we're simply logging the number of devices found and then iterating through each result. In a real application, you might want to do more sophisticated processing. For instance, you could build a map of devices keyed by MAC address to track how many times each device advertised, calculate average RSSI values to estimate distance, or filter the batch to only process devices that meet certain criteria.

Warning: Batch scanning is a powerful tool, but it's not for every situation. If you need to react to a device's presence immediately (for example, if you're building a "find my keys" app where the user is actively searching), a report delay is not your friend. The user doesn't want to wait 5 seconds to see results – they want instant feedback. In these cases, set setReportDelay(0) for immediate reporting.

But for long-term monitoring or data collection scenarios, batch scanning is a battery's best friend. Consider these use cases:

• Background presence monitoring: Your app checks every minute to see if the user's smartwatch is still in range, but doesn't need second-by-second updates.

• Environmental sensing: You're collecting data from temperature sensors throughout a building and only need to update your dashboard every 30 seconds.

• Beacon analytics: You're tracking how many people pass by a retail location based on their phone's BLE advertisements, and you aggregate the data every 10 seconds.

The sweet spot for report delay depends on your use case. Too short (like 1 second), and you're not getting much benefit, you're still waking up frequently. Too long (like 60 seconds), and your app might feel unresponsive or miss time-sensitive events. For most background monitoring tasks, delays between 5 and 30 seconds work well.

One more thing to be aware of: batch scanning has limits. The Bluetooth controller has a finite buffer for storing scan results. If you set a very long delay and you're in an environment with hundreds of BLE devices, the buffer might fill up before the delay expires. When this happens, the oldest results get dropped. Android doesn't give you a warning when this occurs, so if you're missing data, consider reducing your report delay or using more aggressive filters to reduce the number of results being collected.

OnFound/OnLost: The Drama of Presence

Since Android 8.0, scanning has gotten even more dramatic. You can now ask the hardware to not only tell you when it finds a device, but also when it loses one. This is done using the CALLBACK_TYPE_FIRST_MATCH and CALLBACK_TYPE_MATCH_LOST flags in your ScanSettings.

val scanSettings = ScanSettings.Builder()
    .setCallbackType(ScanSettings.CALLBACK_TYPE_FIRST_MATCH or ScanSettings.CALLBACK_TYPE_MATCH_LOST)
    .build()

Now, in your ScanCallback, the callbackType parameter in onScanResult will tell you what happened.

override fun onScanResult(callbackType: Int, result: ScanResult) {
    when (callbackType) {
        ScanSettings.CALLBACK_TYPE_FIRST_MATCH -> {
            Log.d("PresenceDetector", "Found them! ${result.device.address} has entered the building.")
        }
        ScanSettings.CALLBACK_TYPE_MATCH_LOST -> {
            Log.d("PresenceDetector", "They're gone! ${result.device.address} has left the building.")
        }
    }
}

The presence detection mechanism shown above represents a fundamental shift in how we think about Bluetooth scanning. Instead of treating scanning as a continuous stream of "here's what I see right now," we're now working with events: "this device appeared" and "this device disappeared." Let's dive deep into how this works and why it's so powerful.

When you set the callback type using the bitwise OR operator (or in Kotlin, | in Java), you're telling the Bluetooth hardware to track the presence state of devices over time. The code CALLBACK_TYPE_FIRST_MATCH or CALLBACK_TYPE_MATCH_LOST combines both flags, meaning you want to be notified both when a device first appears and when it disappears. You can use these flags individually if you only care about one type of event, but using both together gives you complete presence awareness.

Let's understand what "first match" and "match lost" actually mean. When the Bluetooth controller hears an advertisement from a device that matches your filters for the first time, it triggers a CALLBACK_TYPE_FIRST_MATCH event. This is different from CALLBACK_TYPE_ALL_MATCHES (the default), which would trigger every single time the device advertises. A device might advertise multiple times per second, so the difference is significant. With FIRST_MATCH, you get one notification when the device enters your scanning range, not a flood of notifications as it continues to advertise.

The CALLBACK_TYPE_MATCH_LOST event is even more interesting. The Bluetooth controller keeps track of when it last heard from each device. If a device stops advertising (because it moved out of range, was turned off, or its battery died), the controller notices the absence and triggers a MATCH_LOST event. This happens automatically: you don't have to manually track timestamps or implement timeout logic in your app. The hardware does it for you.

But how does the hardware know when a device is "lost"? It uses an internal timeout. If the controller hasn't heard from a device for a certain period (typically a few seconds, though the exact duration is implementation-dependent and not exposed to apps), it considers the device lost. This means there's a slight delay between when a device actually leaves range and when you get the MATCH_LOST callback, but this delay is usually acceptable for presence detection use cases.

In the code example above, we're using a when expression to handle the different callback types. When we receive a FIRST_MATCH, we know the device has just entered our scanning range, so we log "Found them!" This is perfect for triggering actions like unlocking a door when your phone comes near, or starting to sync data when your fitness tracker is detected.

When we receive a MATCH_LOST, we know the device has left our scanning range or stopped advertising, so we log "They're gone!" This is ideal for triggering cleanup actions like locking the door when your phone leaves, or stopping a data sync when your tracker disconnects.

This is incredibly useful for presence detection scenarios. Is your smart lock in range? Is your fitness tracker still connected? Is the user's phone nearby? Now you can know, with hardware-level certainty, and you can react to changes in presence without constantly polling or maintaining complex state machines in your app code.

Here's a practical example of how you might use this in a smart home app:

private val presenceCallback = object : ScanCallback() {
    override fun onScanResult(callbackType: Int, result: ScanResult) {
        when (callbackType) {
            ScanSettings.CALLBACK_TYPE_FIRST_MATCH -> {
                // User's phone detected - they're home!
                Log.d("SmartHome", "Welcome home! Unlocking door and turning on lights.")
                unlockFrontDoor()
                turnOnLights()
                adjustThermostat(COMFORTABLE_TEMP)
            }
            ScanSettings.CALLBACK_TYPE_MATCH_LOST -> {
                // User's phone is gone - they left!
                Log.d("SmartHome", "Goodbye! Locking door and entering away mode.")
                lockFrontDoor()
                turnOffLights()
                adjustThermostat(ENERGY_SAVING_TEMP)
                armSecuritySystem()
            }
        }
    }

    override fun onScanFailed(errorCode: Int) {
        Log.e("SmartHome", "Presence detection failed: $errorCode")
    }
}

One important consideration: FIRST_MATCH and MATCH_LOST are mutually exclusive with CALLBACK_TYPE_ALL_MATCHES. If you combine them with ALL_MATCHES, the behavior becomes undefined and varies by device. Stick to either ALL_MATCHES for continuous reporting, or FIRST_MATCH/MATCH_LOST for presence detection – don't try to use both at once.

Also, be aware that presence detection works best when combined with hardware filtering. If you're scanning for all devices without filters, the controller has to track the presence state of every single BLE device in range, which can overwhelm its internal tracking tables. Always use ScanFilter to narrow down which devices you care about when using presence detection.

By combining these advanced techniques – hardware filtering, batch scanning, and presence detection – you can build incredibly sophisticated and power-efficient Bluetooth applications. You're not just a developer anymore. You're a Bluetooth wizard, wielding the power to create apps that are aware of their surroundings, responsive to changes, and respectful of battery life.

Now, let's see where we can apply these magical powers in the real world.

Real-World Use Cases: Where the Bluetooth Hits the Road

Okay, we've learned a ton of cool new tricks. We're basically Bluetooth black belts at this point. But what's the use of all this power if we don't use it for good (or at least for a cool app)? Let's explore some real-world scenarios where the new features in AOSP 16 can turn a good app into a great one.

1. The "Find My Everything" App

We've all been there. You're late for work, and your keys have decided to play a game of hide-and-seek in another dimension. This is the classic use case for a BLE tracker.

• The Old Way: Your app would be constantly doing active scans, draining your battery while you frantically search. It would connect to every tracker in your house just to see if it's the right one.

• The AOSP 16 Way: Your app runs a passive scan in the background with a hardware filter for your tracker's specific Service UUID. The battery impact is minimal. When you open the app to find your keys, it already knows they're in the house because it's been listening silently. You hit the "Find" button, the app connects, and your keys start screaming from inside the couch cushions. And if the connection fails? Bond loss reason tells you if the tracker's battery died, so you're not looking for a dead device.

2. The Smart Supermarket

Imagine an app that gives you coupons for products as you walk past them in the store. This is the dream of proximity marketing, a dream that has been historically thwarted by, you guessed it, battery drain.

• The Old Way: The app would need to constantly scan for beacons, turning the user's phone into a hot potato and a dead battery by the time they reach the checkout line.

• The AOSP 16 Way: The supermarket places BLE beacons in each aisle. Your app uses a passive, batched scan. It wakes up every minute or so, gets a list of all the beacons it has seen, and then goes back to sleep. When it sees you've been loitering in the cookie aisle for five minutes (it knows, it always knows), it uses the Service UUID from the advertisement to identify the "Cookie Aisle Beacon" and sends you a coupon for Oreos. It's targeted, it's efficient, and it doesn't kill your battery before you can pay.

3. The Overly-Attached Smart Home

Your smart home should be, well, smart. It should know when you're home and when you've left. It should lock the door behind you and turn on the lights when you arrive.

• The Old Way: You'd have to rely on GPS (a notorious battery hog) or Wi-Fi connections, which can be unreliable. BLE was an option, but constant scanning was a problem.

• The AOSP 16 Way: Your phone is the key. Your smart hub (acting as a central device) runs a continuous, low-power passive scan. When it sees your phone's BLE advertisement, it knows you're home. But what if you just walk by the house? This is where the OnFound/OnLost feature comes in. The hub can be configured to only trigger the "Welcome Home" sequence after it has seen your device consistently for a minute (OnFound), and to trigger the "Goodbye" sequence only after it hasn't seen you for five minutes (OnLost). It's a smarter, more reliable presence detection system that finally makes the smart home feel... smart.

4. The Corporate Asset Tracker

In a large hospital or warehouse, keeping track of expensive, mobile equipment (like IV pumps or forklifts) is a huge challenge. BLE tags are the solution.

• The Old Way: Employees would have to walk around with a tablet, doing active scans to take inventory. It's slow, manual, and inefficient.

• The AOSP 16 Way: A network of fixed BLE gateways is installed throughout the building. Each gateway is a simple device (like a Raspberry Pi) running a continuous passive scan. They collect all the advertisement data from the asset tags and send it to a central server. The server can now see, in real-time, that IV Pump #34 is in Room 201, and Forklift #3 is currently in the loading bay. No manual scanning required. It's a low-cost, low-power, real-time location system, all thanks to the efficiency of passive scanning.

These are just a few examples. From fitness trackers to industrial sensors, the new Bluetooth features in AOSP 16 open up a world of possibilities for building apps that are not only powerful but also polite to your user's battery. Now, let's talk about how to make sure our shiny new app works on all devices, not just the new ones.

API Version Checking: How to Not Crash Your App

So, you've built a beautiful, battery-sipping app using all the new hotness from AOSP 16's Q4 release. You're ready to ship it, become a millionaire, and retire to a private island. But then, a bug report comes in. Your app is crashing on a brand new Android 16 device. What gives?!

Welcome, my friend, to the wonderful world of API version checking. With Android's new release schedule, this has become more important (and slightly more complicated) than ever.

The Problem: A Tale of Two Android 16s

As we discussed, 2025 gave us two Android 16 releases:

• The Q2 Release: The main "Baklava" release. Let's call this API level 36.0.

• The Q4 Release: The minor, feature-drop release. This is where our new Bluetooth toys live. Let's call this API level 36.1.

Our new passive scanning API, setScanType(), only exists on 36.1 and later. If you try to call it on a device that's running the initial Q2 release (36.0), your app will crash with a NoSuchMethodError. It's the digital equivalent of asking for a menu item that was only added last night. The chef (your app) just gets confused and has a meltdown.

The Old Guard: SDK_INT

For years, our trusty friend for checking API levels has been Build.VERSION.SDK_INT. It's simple and effective.

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
    // Use an API from Android 12 (S) or higher
}

But SDK_INT only knows about major releases. For both Android 16 Q2 and Q4, SDK_INT will just report 36. It has no idea about the minor version. It's like asking someone their age, and they just say "thirties." Not very specific.

The New Hotness: SDK_INT_FULL

To solve this, the Android team has given us a new, more precise tool: Build.VERSION.SDK_INT_FULL. This constant knows about both the major and minor version numbers. And to go with it, we have a new set of version codes: Build.VERSION_CODES_FULL.

So, to safely call our new passive scanning API, we need to do a more specific check:

// Let's build our ScanSettings
val scanSettingsBuilder = ScanSettings.Builder()
    .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER)

// Now, let's check if we can go passive
if (Build.VERSION.SDK_INT_FULL >= Build.VERSION_CODES_FULL.BAKLAVA_1) {
    Log.d("ApiCheck", "This device is cool. Going passive.")
    // This is the new API from the Q4 release (36.1)
    scanSettingsBuilder.setScanType(ScanSettings.SCAN_TYPE_PASSIVE)
} else {
    Log.d("ApiCheck", "This device is old school. Sticking to active scanning.")
    // Fallback for devices that don't have the new API
    // We don't need to do anything here, as active is the default
}

val scanSettings = scanSettingsBuilder.build()

Graceful Degradation: The Art of Falling with Style

This brings us to a crucial concept: graceful degradation. It means your app should still work on older devices, even if it can't use the latest and greatest features. It should fall back gracefully.

In our example above, if the setScanType method isn't available, we just... don't call it. The app will default to a normal, active scan. It won't be as battery-efficient, but it will still work. The user on the older device gets a functional app, and the user on the newer device gets a more optimized experience. Everybody wins.

Here's a table to help you remember when to use which check:

Mastering this new API checking is non-negotiable. It's the key to writing modern Android apps that are both innovative and stable. Now that we know how to build a robust app, let's talk about how to fix it when it inevitably breaks.

Testing and Debugging: The Fun Part (Said No One Ever)

There are two universal truths in software development:

• It works on my machine, and

• It will break in the most spectacular way possible during a live demo.

Bluetooth development, in particular, seems to delight in this second truth. It's a fickle, invisible force that seems to have a personal vendetta against developers.

So, how do we fight back? With a solid testing and debugging strategy. It's not glamorous, but it's the only way to stay sane.

The Emulator: A Land of Make-Believe

Android Studio's emulator is a fantastic tool. It's fast, it's convenient, and it can simulate all sorts of devices. And for Bluetooth? It can... sort of help. The emulator does have virtual Bluetooth support. You can enable it, and your app will think it has a Bluetooth adapter. It's great for testing your UI and making sure your app doesn't crash when it tries to get the BluetoothLeScanner.

But here's the catch: it's not real. The emulator can't actually interact with the radio waves in your room. You can't use it to find your real-life BLE headphones. For that, you need to venture into the real world.

The Real World: Where the Bugs Live

There is no substitute for testing on real, physical devices. Every phone manufacturer has its own special flavor of Bluetooth stack, its own quirky antenna design, and its own unique way of making your life difficult. A scan that works perfectly on a Google Pixel might fail miserably on another brand. The only way to know is to test.

Your testing arsenal should include:

• A variety of phones: Different brands, different Android versions. The more, the better.

• A variety of BLE peripherals: Don't just test with one type of device. Get a few different beacons, sensors, or wearables. You'll be amazed at how differently they behave.

Common Errors: The Usual Suspects

When your scan inevitably fails, it will give you an error code. Here are a few of the most common culprits:

Debugging Tools: Your Ghost-Hunting Kit

When things go wrong, you need the right tools to see what's happening in the invisible world of Bluetooth.

• logcat: This is your best friend. Be generous with your log statements. Log when you start a scan, when you stop a scan, when you find a device, and when a scan fails. Create a filter for your app's tag so you can see the signal through the noise.

• Android's Bluetooth HCI Snoop Log: This is the holy grail of Bluetooth debugging. It's a developer option that records every single Bluetooth packet that goes in or out of your device. It's incredibly detailed and can be overwhelming, but it's the ultimate source of truth. You can open the generated log file in a tool like Wireshark to see the raw, unfiltered conversation between your phone and the BLE device. It's like having a wiretap on the radio waves.

• nRF Connect for Mobile: This is a free app from Nordic Semiconductor, and it's an essential tool for any BLE developer. It lets you scan for devices, see their advertising data, connect to them, and explore their GATT services. If your app can't find a device, the first thing you should do is see if nRF Connect can. If it can't, the problem is likely with the peripheral, not your app.

Testing and debugging Bluetooth is a marathon, not a sprint. It requires patience, a methodical approach, and a healthy dose of self-deprecating humor. But with the right tools and techniques, you can tame the beast.

Now, let's talk about how to make sure our well-behaved app is also a good citizen when it comes to performance.

Performance and Best Practices: How to Be a Good Bluetooth Citizen

Writing code that works is one thing. Writing code that works well, is efficient, and doesn't make your users want to throw their phone against a wall is another thing entirely. When it comes to Bluetooth, being a good citizen is all about one thing: battery, battery, battery.

The Bluetooth radio is a powerful piece of hardware, but it's also a thirsty one. Every moment it's active, it's sipping power. Your job is to make sure it's only sipping when absolutely necessary. Here are the golden rules of being a good Bluetooth citizen.

1. Don't Scan If You Don't Have To

This sounds obvious, but it's the most common mistake. Before you even think about starting a scan, ask yourself: "Do I really need to do this right now?" If the user is not on the screen that needs scan results, don't scan. If the app is in the background, be extra critical. Background scanning is a huge drain on battery and is heavily restricted by Android for that very reason.

2. Stop Your Scan!

I'm going to say it again because it's that important: always stop your scan when you're done. A scan that's left running is like a leaky faucet for your battery. It will drain and drain until there's nothing left. The best practice is to tie your scan lifecycle to your UI lifecycle.

override fun onPause() {
    super.onPause()
    // The user can't see the screen, so they don't need the results.
    stopBleScan()
}

override fun onResume() {
    super.onResume()
    // The user is back on the screen, let's start scanning again.
    startBleScan()
}

If you find the device you're looking for, stop the scan immediately. There's no need to keep looking.

3. Choose the Right Scan Mode

ScanSettings gives you a few different modes. Choose wisely.

• SCAN_MODE_LOW_POWER: This is your default, everyday mode. It scans in intervals, balancing discovery speed and battery life. Use this for most foreground scanning.

• SCAN_MODE_BALANCED: A middle ground. It scans more frequently than low power mode.

• SCAN_MODE_LOW_LATENCY: This is the "I need to find it NOW" mode. It scans continuously. This will find devices the fastest, but it will also drain your battery the fastest. Only use this for short, critical operations.

• SCAN_MODE_OPPORTUNISTIC: This is the ultimate passive mode. Your app doesn't trigger a scan at all. It just gets results if another app happens to be scanning. It uses zero extra battery, but you have no guarantee of getting results. Use this for non-critical background updates.

And of course, if you're on AOSP 16 QPR2 or later, use setScanType(SCAN_TYPE_PASSIVE) whenever you don't need the scan response data. It's the new king of power efficiency.

4. Use Hardware Filtering and Batching

We covered this in the advanced section, but it's a best practice that's worth repeating. If you're looking for a specific device, use a ScanFilter. If you're doing a long-running scan, use setReportDelay() to batch your results. These two techniques offload the work to the power-efficient Bluetooth controller and let your app's code sleep, which is the number one way to save battery.

5. Be Mindful of Memory

Every ScanResult object that your app receives takes up memory. If you're in a crowded area with hundreds of BLE devices, and you're not using filters, your app can quickly get overwhelmed and run out of memory. This is another reason why filtering is so important. Only get the results you actually care about.

By following these rules, you can build a Bluetooth app that is not only powerful and feature-rich but also respectful of your user's device. You'll be a true Bluetooth sensei. Now, let's wrap things up and look to the future.

Conclusion: The Future is Passive (and That's Okay)

We've been on quite a journey, haven't we? We've traveled back in time to the dark ages of Classic Bluetooth, witnessed the renaissance of BLE, and emerged into the brave new world of AOSP 16. We've learned to be silent ninjas with passive scanning, played detective with bond loss reasons, and mastered the art of speed dating with service UUIDs from advertisements.

If there's one big takeaway from all of this, it's that the future of Bluetooth on Android is smarter, more efficient, and a whole lot less frustrating. The Android team is clearly listening to the pain points of developers and giving us the tools we need to build better, more battery-friendly apps. The introduction of passive scanning isn't just a new feature – it's a change in philosophy. It's an acknowledgment that sometimes, the best way to communicate is to just listen.

As developers, these new tools empower us to move beyond the simple "connect and stream" use cases. We can now build sophisticated, context-aware applications that are constantly aware of their surroundings without turning our users' phones into expensive paperweights. The dream of a truly smart, seamlessly connected world is a little bit closer, and it's going to be built on the back of these power-efficient technologies.

So, what's next? The world of Bluetooth is always evolving. We have Bluetooth 5.4 with Auracast, mesh networking, and even more precise location-finding on the horizon. The one thing we can be sure of is that the tools will continue to get better, and the challenges will continue to get more interesting.

For now, take a moment to appreciate the progress we've made. The next time you start a Bluetooth scan and it just works, take a moment to thank the hardworking engineers who made it possible. And the next time your app's battery graph is a beautiful, flat line instead of a terrifying ski slope, give a little nod to the power of passive scanning.

The Bluetooth beast may never be fully tamed, but with AOSP 16, we've been given a much stronger leash. Now go forth and build amazing things. And for the love of all that is holy, remember to stop your scan.

Table of Contents

• What is a Page Size?

• Why is this Change Being Implemented Now?

• What are the Pros and Cons of this Change?

• Should You worry About this Change?

• Is this Mandatory?

• What if You Don’t Upgrade Your App?

• How Does this Affect Hybrid Apps?

• What Would be the Code Change for This?

• How to Verify if Your App is Upgraded to a 16 KB Page Size

• Conclusion

What is a Page Size?

Think of your device's memory like a book. An operating system doesn't read memory one tiny word at a time; it reads in chunks. These chunks are called "pages." For a long time, on most ARM64 Android devices, these pages were 4 KB in size. Now, for some newer Android devices (specifically those launching with Android 13 and later), that page size has quadrupled to 16 KB.

Why is this Change Being Implemented Now?

It's all about making Android run better on modern hardware. Here are some of the reasons why is it being implemented:

Better Performance: Modern processors can handle larger memory chunks more efficiently. A 16 KB page size means the CPU spends less time managing tiny bits of memory and more time doing actual work, which can lead to faster app performance.

Smoother Operations: With fewer, larger pages to keep track of, the system itself has a little less overhead, making things a bit more streamlined.

Keeping Up with Tech: This change helps Android align with how newer ARM64 processors are designed to work best.

What are the Pros and Cons of this Change?

Every big change has its own pros and cons.

Pros

• Apps that move a lot of data around or are memory-intensive might just feel a bit snappier

• The system could run a bit more efficiently, benefiting all apps indirectly

Cons

• If your native code is constantly asking for very small bits of memory (less than 16 KB), each of those might now take up a full 16 KB page, potentially using a little more memory than before.

• If your native code makes assumptions that "memory pages are always 4 KB," it could run into issues on 16 KB page devices.

Should You worry About this Change?

You need to pay attention if:

• Your app includes native libraries (like .so files) written in C/C++. This is where the impact is most direct. If your native code does anything with memory mapping (mmap, shmem) or file I/O where it calculates offsets or sizes based on a fixed page size.

• You're developing games or other highly performance-sensitive apps with native components.

• You're targeting Android 15+ with your app updates.

You need not worry if:

• Your app is built purely in Java or Kotlin with no native components. The Android Runtime (ART) handles memory for you, so these underlying page size changes are largely invisible. You'll still get the performance benefits!

• You're using React Native or Flutter, unless you've added custom native modules that directly deal with memory mapping or page-size-dependent operations

Is this Mandatory?

Yes. Google Play is making this a requirement for app updates. You would have received an email from Google Play if your app does not support 16 KB page size yet.

As the screenshot clearly shows, "From Nov 1, 2025, if your app updates do not support 16 KB memory page sizes, you won't be able to release these updates" for apps targeting Android 15+. This gives us a solid timeframe to get things ready.

What if You Don’t Upgrade Your App?

You could notice some serious issues if your app has native libraries that aren't ready for the 16 KB page size by the deadline. Here are a few:

• Crashes: This is the most serious. Your app might crash unexpectedly (often with a "segmentation fault") if it tries to access memory incorrectly due to old page size assumptions.

• Wasted Memory: If your code allocates memory in smaller chunks than 16 KB, it could end up using more memory than necessary, potentially slowing things down or hitting memory limits.

• Performance Hit: Instead of gaining speed, your app might actually run slower if its memory operations aren't aligned with the larger page size.

Essentially, your app might work fine today, but become unstable or inefficient on newer Android devices if its native components aren't updated.

How Does this Affect Hybrid Apps?

Generally, if you're building a standard hybrid app (React Native or Flutter app) without custom native modules, you're in a pretty good spot. The frameworks themselves, and the underlying runtimes (JavaScript engine for React Native, Dart VM for Flutter), usually handle memory management, abstracting away the page size.

However, if you've implemented custom native modules in C++ for performance-critical tasks or specific hardware interactions, then you do need to check those modules.

For the vast majority of standard React Native and Flutter apps, you likely won't need direct code changes related to page size, but always ensure you're using the latest SDK versions for your framework to benefit from any underlying platform updates.

What Would be the Code Change for This?

The biggest thing to avoid in your native code is making assumptions about memory page sizes. Instead of hardcoding 4096 (for 4 KB), always ask the operating system what its current page size is.

Steps to Take:

1. Audit Your Native Code: Search your .cpp, .c, and .h files for any direct use of 4096 or 4 KB in memory allocation, buffer sizing, or alignment calculations

2. Replace with sysconf(_SC_PAGESIZE) or getpagesize(): Update any fixed values to dynamically retrieve the actual page size.

3. Recompile with Latest NDK: Make sure you're building your native libraries with a recent Android NDK (r25 or newer is a good target). This ensures your toolchain is aware of the 16 KB page size and provides correct system definitions.

How to Verify if Your App is Upgraded to a 16 KB Page Size

You can verify if your app is upgraded by running extensive testing. However, here are the few more steps.

1. Check Your Test Device's Page Size:

   • Connect your Android 13+ test device (preferably a newer one like a Pixel) via ADB

   • Run adb shell getconf PAGE_SIZE

   • If it returns 16384, you're testing on a 16 KB page device! If it returns 4096, you'll need to find a different device to properly test for this change

   • Here’s an example screenshot from my device

     

2. Run Your App Extensively: Once you have a 16 KB page device, put your app through its paces. Try all features, especially those involving native code, heavy data loading, or complex operations.

3. Monitor for Crashes: Keep a close eye on your crash reporting tools (like Crashlytics). Specifically look for native crashes (SIGSEGV, SIGBUS) coming from Android 13+ devices, as these could be related to page size issues.

4. Memory Profiling: While less direct, if you suspect memory inefficiency in your native code, use Android Studio's Memory Profiler to see if allocations are unexpectedly large or if there's excessive memory usage.

Conclusion

In this blog, we learnt about page size in Android, and why and how to upgrade your app to support 16 KB page size. I hope you have a clear idea about 16 KB page size in Android. By being proactive now, you can avoid last-minute scrambling and ensure your apps continue to perform beautifully on the latest Android devices, well past the November 2025 deadline!

You can follow my Twitter/X account to receive the top AI news everyday. If you wish to learn more about mobile app development, subscribe to my email newsletter (https://5minslearn.gogosoon.com/) and follow me on social media.

Update your Play Core Maven dependency to an Android 14 compatible version! Your current Play Core library is incompatible with targetSdkVersion 34 (Android 14), which introduces a backwards-incompatible change to broadcast receivers to improve user security. As a reminder, from August 31, Google Play requires all new app releases to target Android 14. Update to the latest Play Core library version dependency to avoid app crashes: https://developer.android.com/guide/playcore#playcore-migration

You may not be able to release future versions of your app with this SDK version to production or open testing.

Looks frightening, doesn’t it?

Don’t be so worried. It is actually easier than it looks.

What the Change is Actually About

Basically, Google stopped releasing new versions of the play core library back in early 2022.

The last version of play core library released

And from April 2022, they have broken down the original play core library into four separate libraries:

• Play Assets Delivery Library
• Play Feature Delivery Library
• Play In-App Reviews Library
• Play In-App Updates Library

Each library has its own functionality and responsibility.

Since the older core play library only supports up to a certain API level, you need to migrate your application to use the newer libraries that have support for the most recent API levels.

In essence, you need to figure out which functionality of the original core play library you are using and then download the correct part. For example, if you had logic to notify users when a newer version of your application was available, you need to take the Play In-App-Updates library.

We will be presenting two uses cases here:

• Native Android application
• Flutter application

Use Case – Native Android App

If you have a native Android application, whether it is written in Kotlin or Java, you need to do the following:

1. Open your application level build.gradle file
2. Most probably you will see under the dependencies block, this line:

implementation 'com.google.android.play:core-ktx:1.8.1'

3. You will need to remove it and replace it according to what you used in the previous core library

4. If you need to take the Play In-App-Updates library, then you need to add these to the dependencies block:

implementation 'com.google.android.play:app-update:2.1.0'
//Add the dependency below if you are using Kotlin in your application
implementation 'com.google.android.play:app-update-ktx:2.1.0'

5. Rebuild your application and see that everything works as it should.

✋ You might also need to change import statements from import com.google.android.play.core.tasks.*; to import com.google.android.gms.tasks.*;.

Use Case – Flutter Application

Since Flutter is a framework that caters to both Android and iOS, this scenario is a bit different from the one above. If you receive the warning to upgrade the core play library in your Flutter application, you need to have a look at the libraries you are using in your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  ...
  in_app_update: ^3.0.0

As you can see above, the application depends on the in_app_update library, which has to do with notifying users when a newer version of the application is available. When we head over to in_app_update’s pub.dev changelog page, we can see that:

version 4.1.0 added the required support

So we need to update our pubspec.yaml file to use that version (at the very least).

dependencies:
  flutter:
    sdk: flutter
  ...
  in_app_update: ^4.1.0

Run Pub get and you should be good to go.

You may have come across multi-library projects in your line of work, or you may be looking into converting your library into sub-modules for better structure and organization. No matter the case, you should be well aware of what lies in front of you before diving in.

Writing your own library in Android is neat. You get a chance to write some code that can help other developers (or even yourself).

Since libraries can’t be a standalone project by themselves, they are usually always paired in a project with an application. This allows developing the library to be a simple process where you add a feature/fix a bug and then you can test it directly with the application you have in the project. Thus, simulating (in a local way) how a developer will integrate your library.

But, what if your library relies on another library you are developing?

If you are not aware of it, you should know that a library (read aar) cannot contain another local library within it. It can rely on libraries remotely (via dependencies), but not on something local.

This is not supported in Android, and while some solutions popped up during the years (FatAar), these didn’t always solve the problem and are not up to date. There is even a Google Issue Tracker requesting this feature that has been open for quite some time and is receiving plenty of attention from the community. But let’s identify which walls we can break and which we cannot.

Imagine your project hierarchy looks like this:

-- App
|
 -- OuterLib
   |
    --- InnerLib

So, since InnerLib can’t be part of your original project, where can it reside? And also how would you be able to work locally while developing features inside InnerLib?

We are going to answer these questions in this article.

Git Submodule

For most technical problems, there isn’t always just one solution. Usually, there are more, but each solution has its drawbacks. It's all a question of which drawbacks you are more comfortable living with at the end of the day.

To answer our first question, where can InnerLib reside, we have several options:

1. Make InnerLib a submodule of our original project
2. Make InnerLib a remote dependency of its own

If you are not aware of submodules in Git, Git’s documentation is a good place to familiarize yourself with them. Quoting from it (the first paragraph):

It often happens that while working on one project, you need to use another project from within it. 👉 Perhaps it’s a library that a third party developed or that you’re developing separately and using in multiple parent projects. 👈 A common issue arises in these scenarios: you want to be able to treat the two projects as separate yet still be able to use one from within the other.

This paragraph shows us that this is exactly our use case. Using a submodule has its benefits. All your code is in one place, is easy to manage, and is easy to develop locally.

But submodules have some weaknesses. One is the fact that you must always be aware of which branch your submodule is pointing to. Imagine a scenario where you are on a release branch in your main repository and your sub-module is on a feature branch. If you don’t notice, you release a version of your code with something that is not ready for production. Whoops.

Now think about this within a team of developers. One careless mistake can be costly.

If the first option sounds problematic for you, then hosting your library in another repository is your second choice. Setting up the repository is pretty simple, but how do you work locally now?

Working Locally

Now that we've gotten our project set up properly, we will probably have a line similar to this in our OuterLib build.gradle file:

dependencies {
  implementation 'url_to_remote_inner_lib_repository'
}

How can we make the development cycle efficient and easy to work with? If we develop some feature in InnerLib, how do we test things out in OuterLib? Or in our application?

One solution that might come up is to import our InnerLib locally to our OuterLib project, while having InnerLib .gitignored in our OuterLib project. You can do so easily by right clicking on the name of the project in the left hand side menu in Android Studio and going to New → Module.

How to import a module (Step 1)

Then in the window that opens up, you can choose the Import option at the bottom left:

How to import a module (Step 2)

That sounds easy and simple so far, but what’s the catch?

Each time you modify a file that belongs to InnerLib, the changes won’t be reflected inside InnerLib since it is ignored. So, each change you want to make has to happen inside of InnerLib and then you have to import it again inside OuterLib to see the changes.

This doesn’t seem right. There must be a better way of doing this.

With just a few lines in our settings.gradle file, we can make sure our files stay in sync when we make changes in InnerLib.

When we imported InnerLib into our project, Android Studio made a copy of InnerLib and cached it. That is why we needed to re-import the library for every change we made inside of it. We can tell Android Studio where to reference the files from using the projectDir attribute.

Our settings.gradle might look something like this:

include ':outerLib', ':innerLib', ':app'

To reference our InnerLib locally, we would have to change settings.gradle into this:

include ':outerLib', ':innerLib', ':app'
project('innerLib').projectDir = new File('PATH_TO_INNER_LIB')

Using this approach, our InnerLib files will be linked to our working directory, so every change we make will be reflected immediately.

But, we would like flexibility when working locally on OuterLib with a remote version of InnerLib. What we wrote above inside the settings.gradle file will only allow us to work locally and surely we don’t want to commit that as it is.

Maven Local

If the approach above doesn’t sit quite right with you, there is a different one you can take. Just like you would publish your library publicly with maven, you can do the same thing locally with maven local. Maven local is a set of repositories that sit locally on your machine.

Below are the paths for mavenLocal depending on the operating system of your machine:

• Mac → /Users/YOUR_USERNAME/.m2
• Linux → /home/YOUR_USERNAME/.m2
• Windows → C:\Users\YOUR_USERNAME.m2

In essence you can publish your library locally and then link to it in your project. Doing it this way, we can link our project to InnerLib.

In order to allow this configuration in our project, we need to do the following things:

1. Add mavenLocal() as a repository inside our repositories clause. This is to allow our project the ability to search for repositories locally

buildscript {
    repositories {
        mavenLocal()
    }
}

...

allprojects { 
    repositories { 
        mavenLocal() 
    }
}

2. Change our implementation line inside our dependencies clause to reference our InnerLib as if it we are referencing it remotely

3. To publish InnerLib locally, we will create a file called publishingLocally.gradle that will contain the following:

apply plugin: 'maven-publish' 

project.afterEvaluate {
    publishing { 
      publications {
            library(MavenPublication) { 
                    setGroupId groupId          //your library package
                    setArtifactId artifactId              
                    version versionName         //I.E. 1.0

                    artifact bundleDebugAar

                    pom.withXml { 
                        def dependenciesNode = asNode().appendNode('dependencies')
                        def dependencyNode = dependenciesNode.appendNode('dependency')
                        dependencyNode.appendNode('groupId', 'your_group_id')
                        dependencyNode.appendNode('artifactId', 'your_artificat_id')
                        dependencyNode.appendNode('version', 'your_version')
                    } 
                }
            }
        }
}

4. Inside your application level build.gradle file, add the line:

apply from: '/.publishingLocally.gradle

If this option seems a bit too good to be true, it is. While on one hand, we can develop things locally seamlessly just as if we were working with a remote library. On the other, if we make any change inside InnerLib while working locally, it is required to publish it locally again. While this isn’t a costly task, it does create a need to perform tedious tasks over and over.

A Solution for Working Locally and Remotely

We want to avoid the constant need to re-publish our InnerLib package whenever we make a change locally. We need to figure out a way to make our project be aware of those changes.

In the Working Locally section, we found out how to do that, but we had an issue with committing the settings.gradle file. To solve this problem so we can work both locally and remotely with our InnerLib, we will use a parameter we will define in our gradle.properties file.

The gradle.properties file is a place where you can store project level settings that configure your development environment. This helps make sure that all the developers on a team have a consistent development environment.

Some settings you might be familiar with that are found inside this file are AndroidX support (android.useAndroidX=true) or the JVM arguments (org.gradle.jvmargs=-Xmx1536m).

To help us solve our situation, we can add a parameter here to indicate whether we want to work locally or not. Something along the lines of:

workingLocally = false

This parameter will grant us the ability to distinguish between which settings we are working with, either locally or with production code. First, let’s alter what we have in our settings.gradle file by wrapping it in a condition that checks if our parameter is true:

include ':outerLib', ':innerLib', ':app'
if (workingLocally.booleanValue()) {
  project('innerLib').projectDir = new File('PATH_TO_INNER_LIB')
}

This way, we indicate to the project to get the files for our InnerLib locally from our machine.

Another place where we need to change our logic is in our build.gradle file. Here, instead of getting the code to our library remotely in our dependencies block, we can indicate whether we are depending on it locally or not.

dependencies {
   if (workingLocally.booleanValue()) {
      implementation 'innerLib'
   } else {
     implementation 'url_to_remote_repository'
  }
}

⚠️ Word of warning: You should never commit the gradle.properties file when working locally.

The journey was long and may have seemed quite exhausting. But now we have a full-proof setup for working locally and remotely on a multiple library project.

If you encounter any issues or would like to give your take on this, feel free to leave a comment.

Following that, I wanted to see what it would be like to write tests for the Proto DataStore in that application using the knowledge I gained.

Searching online for guidance didn’t provide much relief, so I figured I would share my knowledge for those that might be looking for it. In the worst case, it would be for my progeny.

In my search, I did find this article, but that focuses mostly on testing the Preferences DataStore and not the Proto DataStore. It does state that:

“However, keep in mind you can use this material for setting up Proto DataStore testing, as it would be very similar to Preferences.”

But having followed it, I found out that besides the dependencies, there aren’t many similarities here and you need to introduce separate logic to test your own Proto DataStore.

Setting Things Up

In your application’s build.gradle file, add the following dependencies:

dependencies {
  ///.....
  androidTestImplementation "androidx.compose.ui:ui-test-junit4:$compose_version"
  debugImplementation "androidx.compose.ui:ui-test-manifest:$compose_version"
}

$compose_version is the variable you defined in your project level build.gradle file.

Then, go to your androidTest directory and create a new file. Usually, you would have a repository class that interacts with your Proto DataStore, so you can name this file as YourRepositoryClassNameTest. We will use the name MyRepositoryTest.

Before we delve into testing the Proto DataStore itself, we need to instantiate it. If you go online to find any documentation on this, it is kind of sparse.

Instantiating a Proto DataStore is used with the global Context like so (when not used in a testing scenario):

private val Context.myDataStore: DataStore<MyItem> by dataStore(
                 fileName = DATA_STORE_FILE_NAME,
                 serializer = MyItemSerializer
 )

Well, you can't do this inside of a test class, because, while you can copy-paste the above code, you won’t be able to access the DataStore object. You can get the application context like this:

ApplicationProvider.getApplicationContext()

but our myDataStore object won’t be available through it.

So, what can we do?

In the article linked above, there is an example of how we can create a Preference DataStore using the PreferenceDataStoreFactory.create method.

fun create(    
            corruptionHandler: ReplaceFileCorruptionHandler<Preferences>? = null,    
            migrations: List<DataMigration<Preferences>> = listOf(),
            scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob()),    
            produceFile: () -> File): DataStore<Preferences>

But since we are not using a Preference DataStore, that won’t work for us. What will work is using the DataStoreFactory.create method like this:

fun <T : Any?> create(    
    serializer: Serializer<T>,   
    corruptionHandler: ReplaceFileCorruptionHandler<T>? = null,    
    migrations: List<DataMigration<T>> = listOf(),    
    scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob()),     produceFile: () -> File): DataStore<T>

There are several arguments for this method (and some have default values), but we don’t need to pass all of them in. We will be passing:

• Our serializer class
• A lambda method for creating the file for our Proto DataStore

dataStore = DataStoreFactory.create(   
        produceFile = {                    
            testContext.dataStoreFile(TEST_DATA_STORE_FILE_NAME)                    },            
        serializer = MyItemSerializer 
      )

We get the testContext by:

private val testContext: Context = ApplicationProvider.getApplicationContext()

How to Test the DataStore

Having created our Proto DataStore successfully, we can move on to writing some tests for it. Keep in mind that you have a repository class that receives the instance of the Proto DataStore as a dependency, so after creating the Proto DataStore, we need to create an instance of our repository class.

 private val repository = MyRepository(datastore)

First, let’s create a test to check our initial Proto DataStore state. The Proto DataStore itself exposes a flow which we can use.

@OptIn(ExperimentalCoroutinesApi::class)
    @Test
    fun repository_testFetchInitialState() {
        runTest {
            testScope.launch {
                val dataStoreObject = repository.myFlow.first()
                // Insert here whatever we want to assert from our
                // Proto DataStore. I.E. a flag whose initial value is false
                assert(dataStoreObject.myFlag == false)  
            }
        }
    }

☝️ You may have noticed this earlier, but we are using a OptIn annotation here. This is because (currently) the APIs which we are using are experimental and must be marked so when we use them.

Since we are accessing the flow of our DataStore, we need to wrap it in our testScope. TestScope is created by doing:

@OptIn(ExperimentalCoroutinesApi::class)
private val dispatcher = TestCoroutineDispatcher()
@OptIn(ExperimentalCoroutinesApi::class)
private val testScope = TestCoroutineScope(dispatcher)

Run it and enjoy your first Proto DataStore test.

That was fun for about two seconds.

Let’s do something more meaningful.

Imagine our Proto DataStore has a list of objects inside of it and we want to test the state of it when we add an item to it.

@OptIn(ExperimentalCoroutinesApi::class)
    @Test
    fun repository_testAdditionOfItem() {
        runTest {
            testScope.launch {
              //1
               val item: MyItem = MyItem.newBuilder().setItemId(UUID.randomUUID().toString())
                    .setItemDescription(TEST_ITEM_DESCRIPTION).build()
                //2
                repository.updateItem(item)

                //3
                val items = repository.myFlow.first().itemsList
                assert(items.size == 1)

                //4
                assert(items[0].itemDescription.equals(TEST_ITEM_DESCRIPTION))
            }
        }
    }

1. We create a test item using the exposed API from the protobuff
2. We add this item to the Proto DataStore using a method we exposed on the MyRepository class
3. We grab the list of items from the flow the Proto DataStore exposes
4. We make sure that the item found in the Proto DataStore matches the item we created earlier

Your DataStore Has a Leak in it

If you try to run the tests above in one go, you will soon receive an error during runtime:

There are multiple DataStores active for the same file: /data/user/0/com.example.app/files/datastore/dataStore_filename.pb. You should either maintain your DataStore as a singleton or confirm that there is no two DataStore’s active on the same file (by confirming that the scope is cancelled).

Well, that is problematic. We only created one DataStore instance in our test class.

What is going on here?

Because we are not using the property delegate to create our DataStore (meaning Context.datastore), it isn’t ensured that our DataStore object is a singleton whenever we access it.

To circumvent this scenario, I have found out that one approach is to delete and recreate the DataStore for each test case. To delete the DataStore, we can do this:

@After
fun cleanup() {
  File(testContext.filesDir, "datastore").deleteRecursively()
}

and before every test, we recreate it:

@Before
 fun setup() {
    dataStore = DataStoreFactory.create(
        produceFile = {
            testContext.dataStoreFile(TEST_DATA_STORE_FILE_NAME)
        },
        serializer = MyItemSerializer
    )
 }

To see a full example, you can go here.

In this article, I wanted to show the outline of a how a Proto DataStore can be tested.

While I went over two test cases, depending on your DataStore and the types you configured there, there could be more test cases and scenarios to write. The building blocks are there, you just have to adapt it to your needs.

Flutter's framework allows developers to build beautiful user interfaces, deliver native performance, and streamline development.

In this tutorial, I will walk you through building and releasing a Flutter app on the Android platform, from setting up your development environment to distributing your app on the Google Play Store.

Prerequisites:

1. Install Flutter and Dart: Make sure you have Flutter and Dart installed on your machine. Follow the official Flutter installation guide for your platform.
2. Android Studio: Download and install Android Studio, which comes with useful tools for Android app development.
3. Google Play Developer Account: Create an account on the Google Play Console to publish your app on the Play Store.

How to Develop your app

In this guide, I'll be building and releasing a simple todo app I built in one of my earlier blogs.

However, you can follow along with this tutorial and release your own app based on what you build.

As a learner, and if you want to experience the app releasing process, this will be good practice for you.

Run the following command to clone my repo:

git clone https://github.com/5minslearn/Flutter-Todo-App

Before proceeding with the app-building process, it's crucial to ensure that our app runs smoothly on a simulator or a physical device, without encountering any errors.

Open the repo in VS Code and press F5 to run the app on your phone / emulator.

How to Customize the Default Launcher Icon in Flutter

When a new Flutter app is created, it has a default launcher icon.

To customize this icon we need to follow the steps below:

1. You can create your own icon by following this guideline.
2. In the [project]/android/app/src/main/res/ directory, place your icon files in folders. The default mipmap- folders demonstrate the correct naming convention.
3. In AndroidManifest.xml, update the application tags android:icon attribute to reference icons from the previous step (for example, <application android:icon="@mipmap/custom_icon" ...).

I created an icon named custom_icon.xml with multiple resolutions (mdpi , hdpi, xhdpi, xxhdpi, xxxhdpi):

48 × 48 (mdpi)
72 × 72 (hdpi)
96 × 96 (xhdpi)
144 × 144 (xxhdpi)
192 × 192 (xxxhdpi)

I also placed each icon in the respective mipmap- folder. And finally, I mentioned them in the AndroidManifest.xml:

_Updating customicon in AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.todo" >
    <application
        android:label="todo"
        android:name="${applicationName}"
        android:icon="@mipmap/custom_icon">
        .....
        .....
    </application>
</manifest>

I am utilizing ColorControlNormal in my custom icon file (custom_icon.xml):

<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="48dp"
    android:height="48dp"
    android:viewportWidth="960"
    android:viewportHeight="960"
    android:tint="?attr/colorControlNormal">
  <path
      android:fillColor="@android:color/white"
      android:pathData="M380,....,453.5Q592,463 613,483Z"/>
</vector>

colorControlNormal is a value that refers to a color attribute that is resolved at runtime, allowing the drawable to match the color theme of the app.

As I'm using an older API version, this function isn't accessible within the older API.

As a solution, I've included the appcompat library in my app/build.gradle file:

...
dependencies {
    ....
    implementation 'androidx.appcompat:appcompat:1.3.1'
    ....
}
....

Implement appcombat library in build.gradle

That's it. Our configurations are done. Let's try to run the app and look at the icon in the device.

App Icon Changed for Todo App

The one with the rabbit's face is the one I created. It has been successfully applied to our app.

Without any delay, let's get into building our Android application.

What is a Keystore and Why DO You Need it in Flutter?

A keystore in Flutter, specifically for Android, is a secure container used to store cryptographic keys and certificates.

It's important to maintain the security of your app, especially when dealing with sensitive information such as API keys, authentication tokens, and encryption keys.

The keystore ensures that these sensitive assets are stored in a way that makes them difficult to extract from the device.

Security

Storing sensitive information in a Keystore ensures that it is protected from unauthorized access, even if the device is compromised.

Compliance

Many regulations require apps to protect sensitive data. A keystore helps you meet compliance standards.

Encryption

If your app uses encryption, the keystore provides a secure location for storing encryption keys.

Credentials

If your app communicates with APIs or services that require credentials, using a keystore can prevent those credentials from being easily extracted.

How to Create a Keystore in Flutter

To create a Keystore, you typically use the keytool utility that comes with the Java Development Kit (JDK):

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-key

Sample output for generate a keystore file

How to Generate APK or AAB in Flutter

APK (Android Package) and AAB (Android App Bundle) are distribution formats used to package and distribute Android applications.

It is recommended to build an app as AAB over APK due to the following benefits:

• Smaller downloads and faster installations due to optimized APKs
• Improved efficiency in resource usage and reduced storage consumption
• Dynamic feature delivery support for delivering features on-demand
• Enhanced optimization for specific device configurations

flutter build appbundle
or
flutter build apk

Sample output to build abb

We cannot directly install an Android App Bundle (AAB) file on a mobile device.

An AAB is not an executable package like an APK (Android Package) file that can be directly installed on a device.

Instead, the AAB is a publishing format designed for optimized delivery on the Google Play Store.

When you publish your app on the Google Play Store using an AAB, the Play Store uses it to generate APKs that are tailored to each user's device configuration.

This dynamic generation allows the Play Store to deliver only the necessary resources and code for a specific device, reducing the app's size and improving performance during installation.

How to Release a Flutter App on Google Play Store

To release our app on the Google Play Store, we'll require a Google Play developer account. We can create an account by visiting this link.

Please be aware that there is a registration fee of at least $25 associated with the process.

Google play dashboard to create a new App

Click on the Create app button in the All apps section. Enter the app details in the "Create app" form.

Creating an app in Google play for release

After creating the app, we have to go through multiple tasks to release the application.

Steps to testing the app in Goole Play Console

Steps to setting up the app in Goole Play Console

Steps to release the app in Goole Play Console

However, all these steps will be self-explanatory.

At each step, you'll be prompted for information about your application, advertisements, privacy policy, and more.

It's important to note that you can proceed to publish only after completing these steps.

Make sure to mention everything clearly. Especially the questions about data collection. Because, at any time if Google found that your prescribed information is wrong, your app will not be published or will be taken out, if it's published.

After completing these steps, we have to send the app for review. Our app will be published once the review is completed from Google Play team.

It's important to note that there's a higher chance of the app getting rejected if it has security or advertising-related issues.

Therefore, make sure to thoroughly review your app to ensure that it doesn't have any potential problems in data collection. This will contribute to a smoother and more successful app release experience.

Conclusion

Throughout this tutorial, we've covered the process of changing the app icon and building a Flutter app for Android.

While this example provides a foundational understanding of Flutter app development, it's important to note that real-world app complexities may require additional custom configurations in Android.

For further insights, I encourage you to explore the official documentation, which offers comprehensive guidance on more advanced aspects.

I hope this tutorial has provided you with valuable insights in your Flutter journey.

Thank you for investing your time, and best of luck in your app development endeavors!

If you wish to learn more about Flutter, subscribe to my article by visiting my site which has a consolidated list of all my blogs.

Cheers!

ANRs always seem to sneak up on you when you're not expecting them. And the problem is that there's nothing you can do about them.

You might see them pop up when seeing the overview of your application in Google Play Console. But there won’t be a lot of information there to understand how the ANR happened and what you could've done to fix the situation.

And beyond that, if a user happens to experience an ANR, you have to rely on their willingness to invest time and effort to tell you about it. We've all been on the other side, too. If you're using an application that gets stuck, the one thing you do is go straight to uninstalling it.

So, how can we as developers do everything in our power to protect our app's users from experiencing ANRs?

Let’s find out.

How to Prevent "Application Not Responding" Errors on Android

Be Proactive

Before we delve into solutions that can help us detect ANRs, let’s understand what we can do to avoid getting them in the first place (or minimizing the chance they can happen).

These points might sound obvious, but in a large enough application, it might be easy to overlook things:

First, check to see if you have places in your code that are doing extensive work on the UI thread. The work done on the UI thread should be short and relating to something with the UI of your application.

If you are doing any other logic there or perhaps even asynchronous work, delegate it to a background thread or a service

Second, if by any chance you have threads that hold locks or certain blocks of code that need to be synchronized, make sure you are not creating a deadlock or a certain state of your application reaches it

And third, if your application deals with broadcast receivers, you must verify that the execution of the onReceive method is short and ends in a timely fashion. If there is work there that can take some time, delegate it to a background thread

Another way that you can detect places that might cause ANRs is by using StrictMode. You can use it while developing your application as it catches accidental disk or network usage on the main thread.

Be Smart

You have gone over your application, and you think it isn’t at risk for any ANRs. So you release it for public consumption.

Lo and behold a couple months go by and then you start seeing reports of ANRs. What could you have done differently? As we discussed earlier, those crash reports hardly provide any information regarding the ANR.

To help your application to give you the highest level of detail that it can when an ANR occurs, I will detail two options:

1. Run a thread which polls the UI thread to see if it is stuck
2. On API level ≥ 30, you can use getHistoricalProcessExitReasons

Let's look at each one in detail now:

Run a thread that polls the UI thread

There is already a library called ANR-Watchdog which takes care of detecting ANRs and provides you with all the details. In case you don’t want to use it or want to have something of your own, here is a rough outline of what it does:

• Create a thread which runs on the main thread (it doesn’t have to do any actual work)
• See if the thread’s execution completes after a few seconds
• If it did, then no ANR took place and you run the thread again
• If it did not, some other thread is blocking the main thread and causing an ANR

Below is a rough outline of such a class:

package com.tomerpacific.anrdetection

import android.os.Handler
import android.os.Looper
import java.lang.Exception

class ANRHandler: Thread() {

    val TIMEOUT: Long = 5000L
    private val handler: Handler = Handler(Looper.getMainLooper())
    private val worker : Runnable = Runnable {  }

    override fun run() {
        while (!isInterrupted) {
            handler.postAtFrontOfQueue(worker)

            try {
                sleep(TIMEOUT)
            } catch (exception: Exception) {
                exception.printStackTrace()
            }

            if (handler.hasMessages(0)) {
                //worker has not finished running so the UI thread is being held
                val stackTrace: Array<StackTraceElement> = currentThread().stackTrace
                var output: String = ""
                for (element in stackTrace) {
                    output += element.className + " " + element.methodName + " " + element.lineNumber
                }

                print(output)
            }
        }
    }
}

⚠️ The execution of the runnable is always on the main thread, but since it doesn’t do any work, it is not supposed to impact your application’s performance. You could also decide to run it every desired time interval.

use getHistoricalProcessExitReasons

Option #2 can make your life simpler, as its API gives you a lot of information.

Introduced in Android 11 (API level 30), getHistoricalProcessExitReasons does exactly what you think it does. It returns a list of recorded objects that account for the most recent application terminations.

This method is called on the ActivityManager and accepts three arguments:

1. The package name – of String type (can be null)
2. The process’s id that belonged to the package – of int type
3. The maximum number of reasons you want to get back – of int type

It’s important to note that all of these arguments can be substituted with default values. That is, you can pass null as the package name and get the entire exit reasons for the caller’s UID

So what do these recorded objects contain? Well, these objects are of ApplicationExitInfo type and they can provide you with a lot of useful information.

For starters, you could call the getReason method to find out why the process terminated. This method returns an integer marking the code for the exit reason. If the value returned is 6, that means the application was terminated because it was unresponsive due to the fact that an ANR happened.

via GIPHY

That’s neat, but how can we see where the ANR happened? For that we can use getTraceInputStream. Like the name implies, the returned value is an InputStream of bytes which needs to be read like any other InputStream.

An example output looks like the following:

I/System.out: ----- pid 2738 at 2022-04-26 17:48:12 -----
    Cmd line: com.tomerpacific.anrdetection
    Build fingerprint: 'Android/sdk_phone_x86/generic_x86:11/RSR1.210210.001.A1/7193139:userdebug/dev-keys'
    ABI: 'x86'
    Build type: optimized
I/System.out: Zygote loaded classes=15746 post zygote classes=728
    Dumping registered class loaders
    #0 dalvik.system.PathClassLoader: [], parent #1
    #1 java.lang.BootClassLoader: [], no parent
I/System.out: #2 dalvik.system.PathClassLoader: [/data/app/~~C_0mqw-g_9cjPjIR_kpRIg==/com.tomerpacific.anrdetection-3-t-I6JR9Q3QA6UY7L8iPA==/base.apk], parent #1
    Done dumping class loaders
    Classes initialized: 302 in 19.361ms
    Intern table: 31490 strong; 543 weak
    JNI: CheckJNI is on; globals=637 (plus 31 weak)
I/System.out: Libraries: libandroid.so libaudioeffect_jni.so libcompiler_rt.so libicu_jni.so libjavacore.so libjavacrypto.so libjnigraphics.so libmedia_jni.so libopenjdk.so librs_jni.so libsfplugin_ccodec.so libsoundpool.so libstats_jni.so libwebviewchromium_loader.so (14)
    Heap: 91% free, 2330KB/26MB; 67022 objects
    Dumping cumulative Gc timings
I/System.out: Average major GC reclaim bytes ratio inf over 0 GC cycles
    Average major GC copied live bytes ratio 0.738176 over 4 major GCs
    Cumulative bytes moved 11482280
    Cumulative objects moved 217937
    Peak regions allocated 28 (7168KB) / 768 (192MB)
I/System.out: Start Dumping histograms for 1 iterations for young concurrent copying
    ProcessMarkStack:    Sum: 26.311ms 99% C.I. 26.311ms-26.311ms Avg: 26.311ms Max: 26.311ms
    ScanImmuneSpaces:    Sum: 5.625ms 99% C.I. 5.625ms-5.625ms Avg: 5.625ms Max: 5.625ms
    VisitConcurrentRoots:    Sum: 1.121ms 99% C.I. 1.121ms-1.121ms Avg: 1.121ms Max: 1.121ms
I/System.out: (Paused)ClearCards:    Sum: 375us 99% C.I. 7us-235us Avg: 28.846us Max: 235us
    GrayAllDirtyImmuneObjects:    Sum: 329us 99% C.I. 329us-329us Avg: 329us Max: 329us
    VisitNonThreadRoots:    Sum: 327us 99% C.I. 327us-327us Avg: 327us Max: 327us
I/System.out: InitializePhase:    Sum: 306us 99% C.I. 306us-306us Avg: 306us Max: 306us
    (Paused)GrayAllNewlyDirtyImmuneObjects:    Sum: 164us 99% C.I. 164us-164us Avg: 164us Max: 164us
    (Paused)FlipCallback:    Sum: 144us 99% C.I. 144us-144us Avg: 144us Max: 144us
    SweepSystemWeaks:    Sum: 142us 99% C.I. 142us-142us Avg: 142us Max: 142us
I/System.out: ScanCardsForSpace:    Sum: 125us 99% C.I. 125us-125us Avg: 125us Max: 125us
    ThreadListFlip:    Sum: 96us 99% C.I. 96us-96us Avg: 96us Max: 96us
    ClearFromSpace:    Sum: 78us 99% C.I. 78us-78us Avg: 78us Max: 78us
    CopyingPhase:    Sum: 76us 99% C.I. 76us-76us Avg: 76us Max: 76us
I/System.out: FlipOtherThreads:    Sum: 58us 99% C.I. 58us-58us Avg: 58us Max: 58us
    ProcessReferences:    Sum: 54us 99% C.I. 19us-35us Avg: 27us Max: 35us
    SweepArray:    Sum: 53us 99% C.I. 53us-53us Avg: 53us Max: 53us
I/System.out: EnqueueFinalizerReferences:    Sum: 38us 99% C.I. 38us-38us Avg: 38us Max: 38us
    RecordFree:    Sum: 37us 99% C.I. 14us-23us Avg: 18.500us Max: 23us
    ForwardSoftReferences:    Sum: 25us 99% C.I. 25us-25us Avg: 25us Max: 25us
    FlipThreadRoots:    Sum: 21us 99% C.I. 21us-21us Avg: 21us Max: 21us
I/System.out: (Paused)SetFromSpace:    Sum: 19us 99% C.I. 19us-19us Avg: 19us Max: 19us
    ResumeRunnableThreads:    Sum: 12us 99% C.I. 12us-12us Avg: 12us Max: 12us
    EmptyRBMarkBitStack:    Sum: 8us 99% C.I. 8us-8us Avg: 8us Max: 8us
    SwapBitmaps:    Sum: 7us 99% C.I. 7us-7us Avg: 7us Max: 7us
    Done Dumping histograms
    young concurrent copying paused:    Sum: 750us 99% C.I. 750us-750us Avg: 750us Max: 750us
I/System.out: young concurrent copying freed-bytes: Avg: 1052KB Max: 1052KB Min: 1052KB
    Freed-bytes histogram: 960:1
    young concurrent copying total time: 35.641ms mean time: 35.641ms
    young concurrent copying freed: 8956 objects with total size 1052KB
I/System.out: young concurrent copying throughput: 255886/s / 29MB/s  per cpu-time: 179578666/s / 171MB/s
    Average minor GC reclaim bytes ratio 0.742269 over 1 GC cycles
    Average minor GC copied live bytes ratio 0.276211 over 2 minor GCs
    Cumulative bytes moved 1410368
    Cumulative objects moved 26626
I/System.out: Peak regions allocated 28 (7168KB) / 768 (192MB)
    Total time spent in GC: 35.641ms
    Mean GC size throughput: 28MB/s per cpu-time: 169MB/s
    Mean GC object throughput: 251284 objects/s
    Total number of allocations 75978
    Total bytes allocated 3382KB
    Total bytes freed 1052KB
I/System.out: Free memory 23MB
    Free memory until GC 23MB
    Free memory until OOME 189MB
    Total memory 26MB
    Max memory 192MB
    Zygote space size 3040KB
    Total mutator paused time: 750us
I/System.out: Total time waiting for GC to complete: 80.600us
    Total GC count: 1
    Total GC time: 35.641ms
    Total blocking GC count: 0
    Total blocking GC time: 0
    Histogram of GC count per 10000 ms: 0:1
    Histogram of blocking GC count per 10000 ms: 0:1
    Native bytes total: 15621964 registered: 98204
I/System.out: Total native bytes at last GC: 15537168
    /system/framework/oat/x86/android.hidl.manager-V1.0-java.odex: quicken
    /system/framework/oat/x86/android.test.base.odex: quicken
    /system/framework/oat/x86/android.hidl.base-V1.0-java.odex: quicken
I/System.out: Current JIT code cache size (used / resident): 0KB / 32KB
    Current JIT data cache size (used / resident): 4KB / 32KB
    Zygote JIT code cache size (at point of fork): 45KB / 48KB
    Zygote JIT data cache size (at point of fork): 33KB / 36KB
    Current JIT mini-debug-info size: 26KB
I/System.out: Current JIT capacity: 64KB
    Current number of JIT JNI stub entries: 0
    Current number of JIT code cache entries: 48
    Total number of JIT compilations: 6
    Total number of JIT compilations for on stack replacement: 1
I/System.out: Total number of JIT code cache collections: 0
    Memory used for stack maps: Avg: 35B Max: 52B Min: 28B
    Memory used for compiled code: Avg: 125B Max: 257B Min: 69B
    Memory used for profiling info: Avg: 70B Max: 188B Min: 20B
    Start Dumping histograms for 48 iterations for JIT timings
    Compiling:    Sum: 385.780ms 99% C.I. 0.556ms-25.610ms Avg: 8.037ms Max: 25.610ms
I/System.out: TrimMaps:    Sum: 44.431ms 99% C.I. 2.400us-5148us Avg: 925.645us Max: 5643us
    Done Dumping histograms
    Memory used for compilation: Avg: 83KB Max: 322KB Min: 8560B
    ProfileSaver total_bytes_written=0
    ProfileSaver total_number_of_writes=0
    ProfileSaver total_number_of_code_cache_queries=0
I/System.out: ProfileSaver total_number_of_skipped_writes=0
    ProfileSaver total_number_of_failed_writes=0
    ProfileSaver total_ms_of_sleep=5000
    ProfileSaver total_ms_of_work=0
I/System.out: ProfileSaver total_number_of_hot_spikes=5
    ProfileSaver total_number_of_wake_ups=0
I/System.out: suspend all histogram:    Sum: 11.468ms 99% C.I. 0.018ms-10.658ms Avg: 1.042ms Max: 11.094ms
    DALVIK THREADS (15):
    "main" prio=5 tid=1 Runnable
      | group="main" sCount=0 dsCount=0 flags=0 obj=0x72107008 self=0xe7d05410
      | sysTid=2738 nice=-10 cgrp=top-app sched=0/0 handle=0xf6267478
I/System.out:   | state=R schedstat=( 5812106631 1041760011 2536 ) utm=535 stm=45 core=0 HZ=100
      | stack=0xff7cb000-0xff7cd000 stackSize=8192KB
      | held mutexes= "mutator lock"(shared held)
        at com.tomerpacific.anrdetection.MainActivity$onCreate$1$1.onClick(MainActivity.kt:18)
        at android.view.View.performClick(View.java:7448)
        at android.view.View.performClickInternal(View.java:7425)
I/System.out:     at android.view.View.access$3600(View.java:810)
        at android.view.View$PerformClick.run(View.java:28305)
I/System.out:     at android.os.Handler.handleCallback(Handler.java:938)
        at android.os.Handler.dispatchMessage(Handler.java:99)
        at android.os.Looper.loop(Looper.java:223)
        at android.app.ActivityThread.main(ActivityThread.java:7656)
I/System.out:     at java.lang.reflect.Method.invoke(Native method)
        at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:592)
        at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:947)

This is only a partial snippet of all the output, but you can see that it provides a ton of information, including:

• Free memory/Total memory/Max memory
• Heap diagnostic (percentage free, size and amount of objects allocated)
• The stacktrace of the main thread

Other useful methods include:

• getTimestamp – the timestamp of when the process terminated
• getDescription – a system description of why the process terminated

Be Resourceful

If your application does suffer from ANRs, solving them can be quite tricky. This can be because you're not getting a complete stacktrace (or not having one at all), you're not able to reproduce it, or it's happening on some esoteric device. Well, what can you do?

In Android Studio version ≥ 3.2, you have a utility called CPU Profiler. This tool lets you inspect your thread activity during the runtime of your application. With it, you might find out which threads are running, for how long, and where they are running.

To use it, inside Android Studio, go to View → Tool Window → Profiler:

A window will open at the bottom of the screen. Once you attach a process to it, you will see three timelines:

1. Event timeline
2. CPU timeline
3. Thread timeline

You want to focus on the Thread timeline to see if anything is out of the ordinary there. Each thread’s activity can be identified by three colors:

• Green – indicates that the thread is running or in a runnable state
• Yellow – indicates that the thread is waiting for the execution of some I/O operation
• Gray – indicates the thread is sleeping

Wrapping Up

Hopefully you have gained some confidence in making your applications as ANR-proof as you can. Using the tools and techniques listed above may help prevent your application’s next ANR.

You are welcome to check out some of my other articles on GitHub:

If you're building an Android app, you should consider adding animations. They can improve your app's user experience and increase retention.

These days, if you see an app that has no animation, it can feel odd and out-dated. And since interactive experiences are kind of the new norm, you'll want to figure out ways to set your app apart.

What We'll Build Here

Now, it might seem difficult to make your app stand out if you just have something basic like a quote sharing app (which is what we are going to work on here). It can be hard to hook the user and keep them interested.

Of course, you could just add two simple buttons to load the next/previous quote and call it a day. But that's pretty basic and any app could do that! Even if you're just building a simple side-project, there's no trade-off for good UX :)

So what we'll do in this tutorial is drop the buttons, and instead have logic where a user can swipe the card to the left. When they've swiped far enough, the app will load a new card with a new quote.

By the end of this post, you will learn how to make a really smooth animated card which a user can swipe that can perform whatever action you choose. Here's a demo of how it works:

Amazing, right? Let's get into it!

Prerequisites

For this tutorial, we will use Kotlin as the programming language for our app – but you can easily translate the code to Java and it would work the same.

For reference, this is the quote card that we wish to enable the swipe feature on.

It is an androidX CardView with a bunch of TextViews and an ImageView. There's also a ProgressBar that gets shown while loading a new quote.

We won't be making the XML code for the user interface. You can get the layout I used here from the GitHub repository, or build your own.

Here's the complete code for our Quotes app, if you wish to check it out. It uses the MVVM design pattern, but this article doesn't rely on what pattern you use for the business logic of your app, as we'll just be working on the UI part.

Now, we're ready to make that awesome swipe interface!

How to Handle Swipes in Our App

To handle swipes, we first need to set a touch listener on the card. Each time an action is performed on the card, the touch listener is called. Within the listener, we will add the logic to do the math and perform the animations.

Here is the blueprint of the touch listener we will be using:

quoteCard.setOnTouchListener(
    View.OnTouchListener { view, event ->
        when (event.action) {
            MotionEvent.ACTION_MOVE -> {
                // TODO: Handle ACTION_MOVE
            }
            MotionEvent.ACTION_UP -> {
                // TODO: Handle ACTION_UP
            }
        }

        // required to by-pass lint warning
        view.performClick()
        return@OnTouchListener true
    }
)

Here, we are specifically listening for 2 actions on the card – the ACTION_MOVE and the ACTION_UP.

• The ACTION_MOVE event is called when a user starts swiping the card, that is, moving it.
• The ACTION_UP is called when a user lifts their finger from the card, basically, when they release it.

There are many other action events that we can override, such as ACTION_DOWN that's called when a person gets hold of the view, but we don't need them for this feature.

The basic setup for the card is done, so let's figure out the swiping logic.

The math behind the swipe action

First, let's re-think what we want to achieve. Implementing functionality is easier when you know exactly what you wish to have. Your code will also make more sense when your requirements are clear.

Here, we have a quote card. We want users to be able to swipe it only to the left, and if the minimum threshold to load a new quote is reached, it should move back to its original position and load a new quote.

Now, to achieve this, let's think of it in terms of the card. Let's define the mean position as the center of the card.

Mean Position of the Card

We want the card to swipe if and only if the user swipes it to the left of the mean position.

Swipe only if moved towards the left of mean position

So how can we make this happen?

You guessed it – we will calculate the mean position and on the ACTION_MOVE event, we will check if the user swiped to the left and move the card accordingly.

How to implement the swipe logic

To implement the logic, we first need to have the starting position of the card, which is fairly easy to calculate. We will just make sure that it is calculated with respect to the full-screen width, not just the card's width.

Place these lines of code before the when(event.action) statement:

quoteCard.setOnTouchListener(
    View.OnTouchListener { view, event ->

        // variables to store current configuration of quote card.
        val displayMetrics = resources.displayMetrics
        val cardWidth = quoteCard.width
        val cardStart = (displayMetrics.widthPixels.toFloat() / 2) - (cardWidth / 2)

        when (event.action) {
            ...
        }
        ...
    }
)

First we get the displayMetrics from resources, which will give us the width of the screen using displayMetrics.widthPixels.toFloat().

Then we get the cardWidth using the width property of the quoteCard.

Finally, we calculate the starting position of the card using the formula (width of screen/2) - (cardWidth/2). Essentially, this gives us the x-coordinate of this position of the card:

Starting position of card.

Now, let's implement the code for the ACTION_MOVE event.

How to handle the ACTION_MOVE event

Inside the ACTION_MOVE block, we first initialise the newX variable that holds the new x-coordinate that the card has been swiped to.

val newX = event.rawX

event.rawX gives us the absolute value of the new coordinate with respect to the screen width.

newX will contain the x-coordinate where the user's finger is, at any given moment. The value 0.0 for newX means that the user swiped to the left-most part of the screen. And for my emulator, 1080.0 represents the right-most edge of the screen.

Since, we want the card to swipe only if newX is less than the mean position of the card, we will place an if-condition here to verify that this is the case.

Think of this with simple values. Let's suppose that the mean position of the card is at x-coordinate 540.0 (small x-coordinate) and the user swipes to 710.0 (bigger x-coordinate). But we don't want them to be able to swipe to the right. And if the user swipes to 320.0 (smaller x-coordinate), then we need to carry out the swipe and move the card to the new position.

Here's the code to implement the above logic:

if (newX - cardWidth < cardStart) { // or newX < cardStart + cardWidth
    quoteCard.animate().x(
        min(cardStart, newX - (cardWidth / 2))
    )
    .setDuration(0)
    .start()
}

We subtract cardWidth from newX because newX is an absolute value which is not relative to the card. It has a higher value because cardStart is towards the start of the screen, and newX is initially somewhere in the middle (a user would generally swipe from the middle).

We want to compare the value of shift in the x-coordinate and median to the value of cardStart, not the value of newX, so we take this into account by subtracting cardWidth.

Then, we carry out the animation using quoteCard.animate() and we change its x coordinate using the x() function.

Now, why do we do min(cardStart, newX - (cardWidth/2))?

This is very interesting and intuitive to understand. From the beginning, we are emphasizing that the card should move only to the left and not to the right.

newX - (cardWidth/2)) is nothing but the swiped distance towards the left (so subtraction is involved – for the right side, it should be added).

The min() function here returns the minimum of the two values provided. If the swiped distance is less than the cardStart, it is returned, otherwise cardStart is used. This is the condition we want to meet and min() makes it really easy to handle.

setDuration(0) ensures that the animation is carried instantaneously (which keeps swiping from feeling laggy). start() actually starts the animation with the given properties.

This animation will clear any doubt your have on how this works:

Visualisation of the aforementioned concept

(I don't have expertise on making animations, this was the best I could come up with.)

Here is the final code for the ACTION_MOVE event:

MotionEvent.ACTION_MOVE -> {
    // get the new coordinate of the event on X-axis
    val newX = event.rawX

    // carry out swipe only if newX - cardWidth < cardStart, that is
    // the card is swiped to the left side, not to the right
    if (newX - cardWidth < cardStart) {
        quoteCard.animate()
            .x(
                min(cardStart, newX - (cardWidth / 2))
            )
        .setDuration(0)
        .start()
    }
}

You can also include a TextView to the UI that reflects when the user should release the card. Place this code inside the above if statement too:

if (quoteCard.x < MIN_SWIPE_DISTANCE) textView.text = getString(R.string.releaseCard)
else textView.text = getString(R.string.infoText)

where MIN_SWIPE_DISTANCE is -250:

// -250 produces best result, feel free to change to your liking
const val MIN_SWIPE_DISTANCE = -250 // User should move alteast -250 from mean position to load new quote

Now, the ACTION_MOVE event is handled properly. Let's write the code to handle the ACTION_UP event, that is, when the card is released.

How to handle the ACTION_UP event

For the ACTION_UP event, we want the card to come back to its original position, wait for about 100 milliseconds, then load a new quote.

The logic to animate the card is similar, but this time we will make its animation duration about 150 millisecond to make it look smooth.

First, create a variable currentX that holds the current value of the x coordinate of the quote card. We'll use this variable later.

var currentX = quoteCard.x

Then, start the animation on the card. Pass the cardStart variable to the x() function to make it return to its original position and set the duration to 150.

quoteCard.animate()
    .x(cardStart)
    .setDuration(150)
// continued below

This time, we set a listener on the animation. A listener is something that keeps an eye on the animation. By using it, we can perform actions on various animation events such as start, end, resume, and more.

// continuation
.setListener(
    object : AnimatorListenerAdapter() {
        override fun onAnimationEnd(animation: Animator) {
            viewLifecycleOwner.lifecycleScope.launch(Dispatchers.Default) {
                delay(100)
                // check if the swipe distance was more than
                // minimum swipe required to load a new quote
                if (currentX < MIN_SWIPE_DISTANCE) {
                    // Add logic to load a new quote if swiped adequately
                    viewModel.getRandomQuote()
                    currentX = 0f
                }
            }
        }
    }
)
.start()

We set a listener to look for the ending of the animation by overriding the onAnimationEnd() function.

As soon as the animation ends, we launch a coroutine (similar to Threads in Java but much more efficient) with a delay of 100 milliseconds. It then checks if the user had swiped further than the MIN_SWIPE_DISTANCE needed to load a new quote. The variable currentX is used for the comparison here.

If the user actually swipes passing the minimum distance, the coroutine is delayed for 100 milliseconds. Then the view model loads a new random quote from the API, also resetting the currentX variable to 0f.

The final code for the ACTION_UP event looks like this:

MotionEvent.ACTION_UP -> {
    var currentX = quoteCard.x
    quoteCard.animate()
        .x(cardStart)
        .setDuration(150)
        .setListener(object : AnimatorListenerAdapter() {
            override fun onAnimationEnd(animation: Animator) {
                viewLifecycleOwner.lifecycleScope.launch(Dispatchers.Default) {
                    delay(100)
                    // check if the swipe distance was more than
                    // minimum swipe required to load a new quote
                    if (currentX < MIN_SWIPE_DISTANCE) {
                        // Add logic to load a new quote if swiped adequately
                        viewModel.getRandomQuote()
                        currentX = 0f
                    }
                }
            }
        })
        .start()
    textView.text = getString(R.string.infoText)
}

Final Code

This is the final code for the complete onTouchListener():

quoteCard.setOnTouchListener(
    View.OnTouchListener { v, event ->

        // variables to store current configuration of quote card.
        val displayMetrics = resources.displayMetrics
        val cardWidth = quoteCard.width
        val cardStart = (displayMetrics.widthPixels.toFloat() / 2) - (cardWidth / 2)

        when (event.action) {
            MotionEvent.ACTION_UP -> {
                var currentX = quoteCard.x
                quoteCard.animate()
                    .x(cardStart)
                    .setDuration(150)
                    .setListener(
                        object : AnimatorListenerAdapter() {
                            override fun onAnimationEnd(animation: Animator) {
                                viewLifecycleOwner.lifecycleScope.launch(Dispatchers.Default) {
                                    delay(100)

                                    // check if the swipe distance was more than
                                    // minimum swipe required to load a new quote
                                    if (currentX < MIN_SWIPE_DISTANCE) {
                                        // Add logic to load a new quote if swiped adequately
                                        viewModel.getRandomQuote()
                                        currentX = 0f
                                    }
                                }
                            }
                        }
                    )
                    .start()
                textView.text = getString(R.string.infoText)
            }
            MotionEvent.ACTION_MOVE -> {
                // get the new co-ordinate of X-axis
                val newX = event.rawX

                // carry out swipe only if newX < cardStart, that is,
                // the card is swiped to the left side, not to the right
                if (newX - cardWidth < cardStart) {
                    quoteCard.animate()
                        .x(
                            min(cardStart, newX - (cardWidth / 2))
                        )
                        .setDuration(0)
                        .start()
                    if (quoteCard.x < MIN_SWIPE_DISTANCE) 
                        textView.text = getString(R.string.releaseCard)
                    else textView.text = getString(R.string.infoText)
                }
            }
        }

        // required to by-pass lint warning
        v.performClick()
        return@OnTouchListener true
    }
}

Congrats! In this tutorial, we've implemented animation that lets a user swipe a card containing a quote to get a new quote.

Don't forget to download the app and test it out yourself. Stars and contributions on the GitHub repository are welcomed!

Conclusion

Now you have learned how to animate a card and handle animation listeners on it. This helps create better UX that makes your app stand out.

Using the knowledge you gained in this post, you can now create most of the following animations for views in Android:

• Programmatically create sliding animations for Android views.

Just as we did in this tutorial.

• Left to right animation

This is fairly simple, just turn the subtraction in the variables to addition and < signs in the if statements to > signs. With these few tweaks here and there, the right to left animations in card view can be turned into left to right ones!

• You can also show and hide views using animations.

For this, you have to keep track of the start position and end position then animate them with alpha() from 0 to 1. For an example, you can refer to my library Accolib to create animated FAQ accordions.

• Basic animated layout changes can be achieved with view animations.

Thanks a lot for reading so far, I hope this post added some value. Subscribe to my newsletter at Genics Blog to stay updated with my future articles!

Hey, how are you doing? In this article, I'm going to show you how you can install Laravel 8 on your phone.

To get the most out of this guide, you should have some knowledge of PHP and you should know what Laravel is. But if you don't, don't worry – I will explain the basics so you can get started.

What Is Laravel?

Laravel is a web application framework with expressive, elegant syntax. It's built on PHP, which means that Laravel is PHP but it makes things easier to work with.

It comes with lots of packages for various features, like authentication, so we don't need to write authentication ourselves. To learn more about what Laravel can do, you can visit the site at laravel.com.

Why I wrote this tutorial

I created this tutorial because I want people interested in programming who don't have a laptop or pc to be able to build things on their phones.

My last post on freeCodeCamp made me realize that people are interested in learning how the tech works, so that's why I'm making more guides like this.

So let's dive into it. In this tutorial I am going to show you how you can install composer.php and use it to set up Laravel 8 on your phone 🔥🔥.

I am Precious Oladele, and I'm almost 19 this month 🥴. I'm from Nigeria and I will be taking you through this process. And if you're wondering how I know so much about this, it's because I also don't have a laptop so I explore with my phone instead 😎.

Requirements

To go through this tutorial, you'll need an Android phone with V6.0+.

Set up

We need to head over to the Play Store and download Termux:

Termux is a Linux-based system which we can use on our phones. It's as simple as using your regular Linux – you can install anything, even Kali, Ubuntu, or whatever you want. But for this tutorial we will be using it to set up Laravel 8 on our mobile phone.

Download composer

Before we download composer, we need to open up our Termux app and type in this command:

termux-setup-storage

It'll ask you for storage permissions, so go ahead and click accept. Once you're done head over to https://getcomposer.org/download/.

We need to grab everything there. But before that we need to install PHP so we can use it in our app. To do that in your Termux, type in the following command:

apt install php

and click enter. You should see this:

Once that is done head over to the composer page and grab the code. We need to do this because Termux is Linux-based. If it was Windows there would be a simple button to download composer.exe there.

Copy the whole code and head over to Termux where you can paste it in. Then click enter.

When composer is installed you should see something like this:

How to Install Laravel 8

Before we install Laravel 8, let's check to see if we have a composer.phar file. In your Termux type this command:

ls

and hit enter. You will see the available files there.

You can see the composer.phar file and a storage folder. The storage folder grants access to your file manager. Remember the termux-setup-storage command you wrote first.

Now let's install Laravel 8. To do so we can either create a project or just install it globally. But it's a bit of a long process when installing it globally on your phone because you need to set a path and so on, and it can be pretty confusing. So in this guide we will create a project instead.

In your Termux go ahead and type this:

php composer.phar create-project laravel/laravel myapp

myapp is just the project name – you can change it to whatever you want. Then hit enter and wait for the magic to happen.

When you see the below, it means that Laravel has been installed:

Easy as pie. Now to test it, you can cd into myapp by typing cd myapp. Then you can run the Laravel server with php artisan serve.

Voilà – development has started 🔥

Now you can open http://127.0.0.1:8000 in your browser and see that Laravel is running:

Also make sure you do this so your Termux app won't force close when you are coding: 😎

That's it!

Thanks for reading. I hope you learned something from this tutorial. You should now be able to install Laravel on your Android phone and start using it to build apps.

If you want more content from me, you can subscribe to my YouTube channel 🙏😁
DevStack

But instead of laboring away at those daily tasks, you can delegate them so someone or something else does them for you. That way, you can have more time to do things you want to do. You can have time to relax.

If you've ever developed an Android application, you know how tedious some tasks can get:

• Running tests
• Making sure the application compiles when merging new code
• Building and publishing the application.

So to whom should we pass along these tasks? Another coworker? They can just pass it along to someone else and it won’t free up anyone’s time. Plus, we don’t want to bum out our colleagues. The solution?

Say hello to GitHub Actions. 👐

What Are GitHub Actions?

GitHub Actions are commands we can trigger when something happens in our repository. At its core, an action is a configuration file that has a list of commands that describe:

• What needs to happen
• When it should happen

This configuration file is in YAML format (.yml) and an example looks like this:

name: My GitHub Action

on: pull_request

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1

Let’s break down the example above:

1. We give a name to our action (My GitHub Action) [Optional]
2. We signify when this action should run (when a pull request is opened)
3. We start a list of tasks (jobs) that should happen once this action is triggered
4. The first one is a build action
5. The runs-on command tells GitHub which runner will execute this job (this is a virtual server and you can choose between Windows/Mac/Linux)
6. Each job can have many phases which are grouped together by the steps keyword
7. The uses keyword tells the script what action to enact

This is a very short example which does not showcase all of the features of GitHub Actions, but it provides a peek into the structure of the configuration file.

In the next sections, we will create actions that will help keep our development cycle efficient and effective.

Note that all GitHub Actions files need to reside under your project’s main folder in the path .github/workflows:

How to Create a GitHub Action For Pull Requests

Whether you are working on a project alone or part of a team, making sure that your application is stable is crucial. So it makes total sense to ensure that your application is compiling properly and all tests are passing whenever you consider merging a pull request.

We’ve already shown in our example how we can checkout the code in our repository. In this action, we will include the following steps:

1. Setting up the JDK version
2. Changing permissions for the virtual environment
3. Running tests (if we have any)
4. Building the application

name: Android Build

on: pull_request

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1

      - name: Set Up JDK              // 1
        uses: actions/setup-java@v1
        with:
          java-version: 1.8

      - name: Change wrapper permissions  // 2
        run: chmod +x ./gradlew

      - name: Run Tests                   // 3
        run: ./gradlew test

      - name: Build Project               // 4
        run: ./gradlew assemble

You can see that above, each step has its own properties and attributes that are specific to it.

I won’t go into each one of them, since you can do that on your own through the documentation. What is common for most of the steps is the run keyword. This attribute states what command to execute.

✋ We need the second step so that the virtual environment can run the gradle commands. Without it, it won’t be able to.

How to make a GitHub Action For Publishing an Application

Once you have published your application for the first time, republishing it becomes sort of like a chore.

You have to make sure the version is upgraded, build the APK, submit it via the Google Play Console and other tedious tasks.

We can automate this process with another GitHub action. This action is a little more complicated than the previous once since it requires the use of GitHub Secrets.

In a nutshell, GitHub Secrets are a way to store sensitive information as environment variables of your repository. We will be needing to use them because:

1. We will need to sign our application
2. We are going to give this action permission to submit our built application to the Google Play Store

Let’s find out how we can create GitHub Secrets first.

• Inside the main page of your repository, click on the Settings tab

• On the left hand side menu, there will be an option titled Secrets

• To create a secret, press the New repository secret button

Now that we got that out of the way, let’s look at the script for publishing an application:

name: Android Publish

on:
  workflow_dispatch:

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1

      - name: Set Up JDK
        uses: actions/setup-java@v1
        with:
          java-version: 1.8

      - name: Change wrapper permissions
        run: chmod +x ./gradlew

      - name: Run Tests
        run: ./gradlew test

      - name: Build Project
        run: ./gradlew build

      - name: Build Release AAB      // 1
        run: ./gradlew bundleRelease

      - name: Sign AAB               // 2
        uses: r0adkll/sign-android-release@v1
        with:
          releaseDirectory: app/build/outputs/bundle/release
          signingKeyBase64: ${{ secrets.SIGN_KEY }}
          alias: ${{ secrets.ALIAS }}
          keyStorePassword: ${{ secrets.STORE_KEY_PASSWORD }}
          keyPassword: ${{ secrets.KEY_PASSWORD }}

      - name: Deploy to Play Store   // 3
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{secrets.SERVICE_ACCOUNT}}
          packageName: com.tomerpacific.laundry
          releaseFiles: app/build/outputs/bundle/release/app-release.aab
          track: production

You may have noticed that this action will run on workflow_dispatch. What does that mean? Basically it allows this action to be triggered manually from GitHub itself.

You can of course decide you would rather run this action when a push happens on the main branch (for example).

The step marked with 1 in the snippet above triggers building an .aab of our application. Then, like we would do if we were building it inside Android Studio, we have to sign this .aab file.

This is the first time GitHub Secrets come into play. We need to create secrets for:

• The Signing Key (secrets.SIGN_KEY)
• The Key Alias (secrets.ALIAS)
• The Store Key Password (secrets.STORE_KEY_PASSWORD)
• The Key Password (secrets.KEY_PASSWORD)

Once we have signed the .aab file we can deploy it to the Google Play Store. At this step there is a little bit more work to do since we need to allow this GitHub Action the permission to deploy applications for us on Google Play. But, wait, how do we do that? We use a Service Account.

How to Create a Service Account

A service account is an entity that you create that tells services or applications it interacts with that it is operating on your behalf.

In our case, our GitHub Action is going to interact with the Google Play Store so it can upload a new version of our application.

To create a service account, go to the Google Cloud Console. If you have no account there, make sure to create one. Then, on the main page, in the left hand side menu, there will be a list item titled Service Accounts.

Once you've clicked it, on the right hand side of the window you will see any service accounts you already have.

We want to create a new one and in the top part of the window there is a button to do just that.

In the window that opens, you will have to enter in the service’s name and you can also enter a description.

The name given here will be the unique identifier of this service account.

In the second step you will be asked to give this service account a role. From the Select A Role dropdown, choose Basic → Editor.

Finally, in the third step, fill out your email in both places under the "Grant users access to this service account" section:

After pressing the done button, you will need to create a key for this service account. The action will use this key to be identified by Google Play.

To create the key, click the three horizontal dots under the Actions label in the main service account screen. In the menu that appears, select Manage keys.

In this window, we will create a key by selecting the New Key button and choosing "Create new key" from the menu that appears.

Now we have the option of choosing the format of our new key – the default is JSON and we will leave it selected. Click create.

Once you have done so, a file will be downloaded to your computer. Make sure to keep this file as it has all the data relevant for your service account and you won’t be able to download it again.

We will take the contents of this file and then create a GitHub secret with it (secrets.SERVICE_ACCOUNT).

Last but not least, we need to make Google Play aware of this service account. Doing so requires us to login to our Google Play Console account and heading over to Setup →API Access.

If you scroll down the page, you will see a section titled Service Accounts. You should be able to see the service account you created previously. Click the Grant Access link

In the settings that open, head over to App permissions. Here you will choose which application this service account interacts with.

Under Account permissions, everything under the releases section should be checked. I highly advise you to look at all the other settings and decide for yourself what you want to leave checked or what you want to check off.

Once you are done, click the Invite user button located in the bottom right corner.

After the invitation is sent, we can run the publishing to store action.

How to Monitor Our Actions in GitHub

To see what actions are defined for your repository, click on the Actions tab. This tab showcases all workflows defined and those that have already run.

On the left hand side you can see all the actions that have been defined and on the right hand side you can see all the actions that have been run. If you want to look at a specific action, you can click on it.

If the action is defined to run on workflow_dispatch, you will see a button enabling you to run it (like in the picture above).

If you want to see a specific run of a workflow, you can also do that from the main Workflows page by clicking on one of the runs. If one of the actions fails to run, this would be the place to investigate and see what went wrong.

Our first action is supposed to be triggered when a pull request is opened. If it works correctly, you should be seeing this:

And there you have it!

Wrapping Up

It’s been a long read up to this point, but we have gone through everything that you need to get started creating a Continuous Integration and Continuous Deployment pipeline for your applications.

If you are interested in seeing how GitHub Actions are set up, you can check them out in one of my repositories here:

To read more about GitHub Actions, head over here:

In this article, I'm going to explain how to automatically upload an Android App Bundle (.aab file) to the Play Store's beta track. We'll use Android Studio and AWS as a cloud infrastructure provider.

Once we've uploaded the app bundle, we'll trigger a Slack notification.

This is a valuable use of your time for a number of reasons, like creating observability and prioritizing processes.

Tech We'll Use

Here are the resources we are going to be using for this tutorial:

1. Android Studio
2. AWS CodeBuild
3. AWS Lambda
4. S3
5. Slack

High Level Overview of the Project

The above image shows you a general overview of how we'll structure the whole thing.

Essentially, there needs to be a Code Pipeline set up on AWS for your Android repository. This Code Pipeline will have Code Build as one of its stages.

Pushing to the master branch of your Android app repository is going to trigger Code Build. The Code Build project will sign the Android app from the command line and upload the artifact to an S3 bucket.

Uploading the bundle to S3 will trigger a Lambda, which will download the bundle and upload it to the Play Store using the Google Publishing API. Once it gets a 200 response, the Lambda will then trigger a Slack notification.

How to Get Your Google Play Service Account Key

To be able to use the Google Play Publisher API, you will need a Google Play Service Account key.

A service account is an account that can act on your behalf when servers are communicating with each other. You can read more about how Google uses OAuth2.0 for server to server communication here.

To see how to create a service account and give it access to the Google Play Publisher API, look here.

Once you've created your service account and given it the appropriate permissions, make sure to download the service account key and keep it safe. You'll be uploading this to an S3 bucket soon.

How to Sign the Android Bundle

The main thing to figure out is how to sign the Android App Bundle. Google has fairly decent documentation on it that you can find here.

I'll summarize the links below.

Generate a private key using keytool like this:

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias

You can call your key whatever you want. Here, I called it my-release-key.jks. You can also choose whatever alias you want. Throughout this tutorial make sure to use the correct name and alias for your key.

Open build.gradle within your app directory in Android Studio and add the following code block to it:

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        release {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile file("my-release-key.jks")
            storePassword "password"
            keyAlias "my-alias"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            ...
        }
    }
}

If you changed the name of your release key to something other than the default, make sure to specify the new name. Same thing for the alias.

Your store password will be whatever password you generated when you first uploaded your app to the Play Store.

Now, when you run the command ./gradlew :app:bundleRelease from the command line in Android Studio, you'll notice that it generates a signed App Bundle.

How to Scrub Signing Information

Committing code with the signing information available as plain text in the build.gradle file is a security risk and could be an attack vector.

Google has documentation around this that you can find here.

First, create a keystore.properties file in the root of your project directory.

The contents of the file should be as below:

storePassword=myStorePassword
keyPassword=myKeyPassword
keyAlias=myKeyAlias
storeFile=myStoreFileLocation

Your store password and key password will be the password you used when you uploaded your app bundle to the App Store the first time.

Your keyAlias and storeFile will be the alias you assigned when creating your private key and the location of the private key you created, respectively.

Now, we need to load this file into build.gradle. This came as a surprise to me initially, but Gradle actually works as a DSL. So, it makes it easier to write configuration using Gradle.

//  Load properties from keystore.properties
def keystorePropertiesFile = rootProject.file("keystore.properties")

//  Creating a new Properties() object
def keystoreProperties = new Properties()

//  If keystorePropertiesFile exists, read from that, else set from build environment
if (keystorePropertiesFile.exists()) {
    //  Loading the keystoreProperties file
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
} else {
    //  Read all environment variables from the build environment
    keystoreProperties.setProperty("storeFile", "${System.getenv('STORE_FILE')}")
    keystoreProperties.setProperty("keyAlias", "${System.getenv('KEY_ALIAS')}")
    keystoreProperties.setProperty("keyPassword", "${System.getenv('KEY_PASSWORD')}")
    keystoreProperties.setProperty("storePassword", "${System.getenv('STORE_PASSWORD')}")
}

You'll notice the if condition in there – don't worry about it for now. It's there specifically to account for Code Build later.

Once you do this, change your signingConfigs section in build.gradle to look like this:

signingConfigs {
        release {
            storeFile file(keystoreProperties['storeFile'])
            keyAlias keystoreProperties['keyAlias']
            keyPassword keystoreProperties['keyPassword']
            storePassword keystoreProperties['storePassword']
        }
    }

How to Set Up AWS Code Pipeline

I'm not going to go into too much detail on this one since its relatively straightforward.

Set up an AWS Code Pipeline with the following three stages:

1. Source stage connected to your GitHub repository's master branch
2. Build stage connected to AWS Code Build
3. Deploy stage which will deploy to an S3 bucket.

You can find more documentation about setting up a Code Pipeline here.

How to Set Up AWS S3

First, make sure you have a Code Pipeline set up with Code Build as one of the stages. Next, set up two S3 buckets:

1. A bucket to store your release key in. I'm calling this bucket release-key.jks
2. A bucket in which you will store your Google Play Service Account private key. (You should have downloaded this key while creating your service account.)

You will need to allow access to these buckets from your Code Build service role. Your Code Build service role should have been created when you set up your Code Pipeline.

Head over to the IAM console and find your Code Build service role and grab the ARN.

Next, use the console to get to the Permissions tab for the bucket release-key.jks and add the following policy there:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::123456789:role/service-role/codebuild-service-role-dummy",
                ]
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::release-key-bucket/*"
        }
    ]
}

This policy will allow access to the S3 bucket from the machine where your CodeBuild project will execute.

You will need to replace the ARNs mentioned above with the ARNs for your account. Make sure to specify the correct ARN for the Code Build service role when you're updating the policy.

You don't need to change the permissions policy for the second bucket. We'll add the relevant permissions to the AWS Lambda role to allow it to access the bucket.

How to Set Up AWS CodeBuild

Next, create a buildspec.yml file in your project root folder.

version: 0.2

phases:
  build:
    commands:
      - aws s3api get-object --bucket release-key.jks --key release-key.jks ./releaseKey.jks
      - cp ./releaseKey.jks ${CODEBUILD_SRC_DIR}/app/releaseKey.jks
      - export STORE_FILE=releaseKey.jks
      - export KEY_ALIAS=$keyAlias
      - export KEY_PASSWORD=$keyPassword
      - export STORE_PASSWORD=$storePassword
      - ./gradlew :app:bundleRelease

artifacts:
  files:
    - app/build/outputs/bundle/release/app-release.aab

This file is pretty simple. It fetches the release key from the bucket specified and saves it into a local file on the Code Build server into the location specified.

Next, export all the variables required for the build.gradle configuration to work correctly. Finally, run Gradle's release command from the command line.

Before you can run this script in Code Build, you'll need to add the variables to the Code Build environment. To do this, first go to the AWS Code Build console and pick your build project for your Android app.

Next, select Edit > Environment like in the screenshot below:

On the screen that pops up once you do this, select the Additional Configuration dropdown. There you'll see an option to add environment variables through key value pairs.

Now when Code Build runs the buildspec.yml file, it will be able to export the specified variables.

As things stand right now, when your pipeline runs, Code Build will be able to download the private key to sign and build your Android app and upload the signed bundle to an S3 bucket.

How to Set Up the Slack App

Observability is a hallmark of automation. You want to know when your automation runs, whether it succeeds or fails, and if it fails, the reason for failure.

The way AWS typically handles observability is through CloudWatch. But I think a Slack integration serves the purpose just as well.

The easiest way to integrate Slack into your automation workflows is to set up a Slack app and send a notification to that app from your automation workflow.

To learn how to set up a Slack app, view the documentation here. The process is super easy and you should have an app up and running in a few minutes.

Once you've created the app, you will get a WebHook URL you can use to call the app to post into the relevant channel. Keep track of this WebHook URL because we'll be using this with the AWS Lambda function.

How to Set Up AWS Lambda

So far, we have an Android App Bundle being signed, built, and uploaded to an S3 bucket. Next, we need to figure out how to upload the bundle to the beta track on the Play Store.

The way to do this is to set up an AWS Lambda which will be triggered when the bundle is uploaded to the S3 bucket. When this trigger occurs, the Lambda will run, download the bundle, grab the service account key, and upload the bundle to the Play Store beta track.

Once you've created a Lambda and added a trigger to run it when a file is uploaded to the bucket, look at the code below:

"""This Python3 script is used to upload a new .aab bundle to the play store. The execution of this Python script
    occurs through an AWS Lambda which is invoked when a new file is uploaded to the relevant S3 buckets"""

import json
import boto3
import os
from urllib import request, parse
from google.oauth2 import service_account
import googleapiclient.discovery

#   Defining the scope of the authorization request
SCOPES = ['https://www.googleapis.com/auth/androidpublisher']

#   Package name for app
package_name = 'com.app.name'

#   Define the slack webhook url
slack_webhook_url = os.environ['SLACK_WEBHOOK_URL']

def send_slack_message(message):
    data = json.dumps({ 'text': message })
    post_data = data.encode('utf-8')
    req = request.Request(slack_webhook_url, data=post_data, headers={ 'Content-Type': 'application/json' })
    request.urlopen(req)

#   This is the main handler function
def lambda_handler(event, context):
    #   Create a new client S3 client and download the correct file from the bucket
    s3 = boto3.client('s3')
    s3.download_file('service-account-bucket-key', 'service-account-bucket-key.json', '/tmp/service-account-key.json')
    SERVICE_ACCOUNT_FILE = '/tmp/service-account-key.json'

    #   Download the app-release.aab file that triggered the Lambda
    bucket_name = event['Records'][0]['s3']['bucket']['name']
    file_key = event['Records'][0]['s3']['object']['key']
    s3.download_file(bucket_name, file_key, '/tmp/app-release.aab')
    APP_BUNDLE = '/tmp/app-release.aab'

    print(f"A bundle uploaded to {bucket_name} has triggered the Lambda")

    #   Create a credentials object and create a service object using the credentials object
    credentials = service_account.Credentials.from_service_account_file(
        SERVICE_ACCOUNT_FILE, scopes=SCOPES
    )
    service = googleapiclient.discovery.build('androidpublisher', 'v3', credentials=credentials, cache_discovery=False)

    #   Create an edit request using the service object and get the editId
    edit_request = service.edits().insert(body={}, packageName=package_name)
    result = edit_request.execute()
    edit_id = result['id']

    #   Create a request to upload the app bundle
    try:
        bundle_response = service.edits().bundles().upload(
            editId=edit_id,
            packageName=package_name,
            media_body=APP_BUNDLE,
            media_mime_type="application/octet-stream"
        ).execute()
    except Exception as err:
        message = f"There was an error while uploading a new version of {package_name}"
        send_slack_message(message)
        raise err

    print(f"Version code {bundle_response['versionCode']} has been uploaded")

    #   Create a track request to upload the bundle to the beta track
    track_response = service.edits().tracks().update(
        editId=edit_id,
        track='beta',
        packageName=package_name,
        body={u'releases': [{
            u'versionCodes': [str(bundle_response['versionCode'])],
            u'status': u'completed',
        }]}
    ).execute()

    print("The bundle has been committed to the beta track")

    #   Create a commit request to commit the edit to BETA track
    commit_request = service.edits().commit(
        editId=edit_id,
        packageName=package_name
    ).execute()

    print(f"Edit {commit_request['id']} has been committed")

    message = f"Version code {bundle_response['versionCode']} has been uploaded from the bucket {bucket_name}.\nEdit {commit_request['id']} has been committed"
    send_slack_message(message)

    return {
        'statusCode': 200,
        'body': json.dumps('Successfully executed the app bundle release to beta')
    }

The Lambda above will use the googleapiclient library and its discovery module to build the URL for Google Play's Publishing API.

Next, the Lambda will download the service account key from the bucket you set up earlier. You'll have to make sure you specify the correct bucket names.

Depending on whether the upload succeeds or fails, we want a Slack message to go out. Add the Slack WebHook URL from the previous section into the environment variables for the Lambda. The function above uses Python's os module to get access to the environment variable and post the message to Slack.

If your Lambda fails, it might be because your Lambda does not have permissions to access the S3 bucket where the key for your Google Play service account is stored. In that case, you will see an error message indicating this.

To fix this, you simply need to add the relevant permissions to your Lambda role.

Here is the policy you will need to add:

{
    "Version": "2012-10-07",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObjectVersion",
                "s3:GetBucketVersioning",
                "s3:GetBucketAcl",
                "s3:GetObject",
                "s3:GetBucketTagging",
                "s3:GetBucketLocation",
                "s3:GetObjectVersionAcl"
            ],
            "Resource": [
                "arn:aws:s3:::arn:aws:s3:::your-bucket-name-with-service-account-key"
            ]
        }
    ]
}

Replace the ARN for the bucket with the relevant one for your account and you should be good to go.

Conclusion

So, there you have it. It definitely wasn't easy and there's a lot of moving parts, but this is an automation that will save you a lot of time and effort.

If you're part of a team that is frequently releasing new app updates, you don't want to be hindered by the absence of one person whose job it is to release the update.

Building this sort of automation makes your CI/CD workflow a lot smoother and more robust.

If you're interested in blogs like this, you can read more at https://redixhumayun.github.io or follow me on Twitter.

If you've been following the news lately, you may have noticed a worrisome tech trend. The frequency and severity of cybersecurity attacks are exploding.

We've seen news of a sprawling hack involving the SolarWinds management platform. That attack may have compromised the systems of over 18,000 SolarWinds customers.

Then, we found out that a zero-day flaw in Microsoft's ubiquitous Exchange email server caused affected systems to get hacked faster than experts could count.

For the average software developer (like me), that's downright scary. After all, if big multibillion-dollar companies like those aren't immune to disastrous hacks, what chance does my code have to stay safe?

Well, it turns out that there's some good news and bad news on that front.

The good news is that the types of large-scale attacks we've seen lately are just that – large scale. In other words, the kinds of groups (or nation-states) that can carry out attacks like those don't care all that much about the kinds of small software projects I work on.

But the bad news is this: there are plenty of small-scale hackers who are more than happy to make your life as a developer miserable. And they will do it if you let them.

But you can do something about it. You can make it your mission to put as many roadblocks in their way as possible. By covering the most likely angles of attack on your software, you can increase the odds that a would-be attacker will pass your code by and look for an easier target.

Now, I've already written extensively about a variety of software security topics. But because I happen to be working on an Android application at the moment – and because Android is a favorite target of hackers – I've decided to share four of the most important Android app security principles you can include in your apps on the platform. I make them a focus of my security efforts, and you should too.

1. Protect Your App's Transport Layer

One of the first things an attacker will look for when targeting an Android app is to see if they can intercept any of the data passing between it and your server's backend.

By eavesdropping on those communications, they can tell an awful lot about your app. And if you're really unlucky, they might even be able to use the data to figure out how to impersonate your app and gain inappropriate access to server-side data.

So, step one in your effort to secure an Android app is simple: protect its data transfer layer by employing strong encryption.

You can do this by making use of protocols like SSL and TLS, which are simple to add to your code and are very difficult to compromise. And once you have a solution in place, take the time to do some threat modeling to decide if you've done enough to protect your app's traffic.

If you are dealing with particularly sensitive data, you may even want to go a little further and build a VPN-type solution right into your app. If you've never implemented a VPN in an Android app before, you can read up on the basics of adding one here in the Android developer guide.

If you go this route, you can even advertise the feature to your customer (or end-users if you're building something public). Android VPN apps are so commonplace these days that the mere mention of the feature will let users know that you're serious about their data's security – and that's always a nice PR bonus.

2. Make Authentication Bulletproof

Image: thodonal / Adobe Stock

Besides your app's data streams, the next most common attack vector to eliminate is any weakness in its authentication methods.

The trouble with doing that is your users. By that, I mean that you need to make your app's authentication process as secure as you can without making it so onerous that your users will revolt (and if I had a dollar for every time a client asked me if 2FA was really necessary, I'd be retired by now).

Regardless of how many times you have to answer the question, though, 2FA is both necessary and worth implementing.

On top of that, you also need to pay attention to how you handle things like key exchanges. At a minimum, you should be using AES encryption to keep those transactions secure.

And last but not least, you should make certain to use token-based security to authenticate legitimate requests from your app to its backend. That makes making such requests difficult enough that even if an attacker finds a way to view a live data stream, they'll have no way to use that information to launch an attack.

3. Guard Against Code Injection

The next thing you should worry about is the public-facing parts of your app. Because most apps are interactive, they will provide users the ability to input data in one form or another. This can be through text-input fields like forms, or through direct data uploads for exchanging things like documents and pictures.

And every time you add a user input feature, you should take great pains to make sure that nobody can use them against you.

The first way to address this is to use proper input validation. If your app expects specific text in a field, make sure it won't accept anything else. You can do this by adding a pre-built text validation module or by building your own (if you have the time and inclination).

If you plan to let a user upload pictures or other specific files, you must include an ability for the app to scan the uploaded file to make sure it is what it claims to be.

Again, this is possible using any number of pre-built modules. I tend to favor JMimeMagic because it can handle a variety of MIME types, but you can use whatever solution works best in the context of your project.

4. Minimize and Secure Client-Side Storage

Last but not least, you should strive to build your app with the smallest local data footprint that's feasible to get the job done.

That's because any data you store on a client device is outside of your control and is therefore vulnerable to external threats.

If a user's device gets compromised by any attack that yields access to the data stored on it, you may inadvertently give the attacker a roadmap to steal information from your app.

Now, storing no client-side data is near-impossible – especially if you need your app to retain some or all of its functionality offline. So, at the very least, make sure any and all client-side data you store remains encrypted at all times.

And, try to eliminate storage of any data that could pose a problem if an attacker got their hands on it. Things like contact lists, message longs, or any kind of usage history come to mind.

And beyond storage, you'll want to test your app to see that it isn't vulnerable to memory leaks that might expose critical data.

To do that, you should get familiar with tools like the OWASP Zed Attack Proxy (ZAP). It will help you to find any vulnerabilities in your app's memory usage before attackers can use them against you.

It can be a bit complex to get the hang of, but there's plenty of good documentation and a fantastic user community that will help you along.

Locked Up Tight

I wish I could tell you that any app built using these four principles will be invulnerable to every threat. But attackers work to find new flaws every minute of every day, and unless you make countering them your job too, you're unlikely to find a perfect solution.

But by covering these major attack vectors, you will at least make their work hard enough that it won't be worth it to try (unless your app contains something of immense value locked up inside).

And at the end of the day, that's all anyone can ask of you as a developer unless they're willing to pay you handsomely to guard against every possible threat – and hey, wouldn't that be nice?

Featured image: Arthur Shevtsov / Adobe Stock

Compose is a new UI framework for Android (though Desktop and Web support is being developed), which replaces the old XML-based View system.

While still in beta release as of writing this article, I do not expect this particular part of the library to change drastically for the stable release.

Topics include:

• A brief recap of the XML approach

• How to migrate from the XML-based colors, themes, and typography (font) system

• How to set up light and dark themes for your apps in only a few lines of code

• How to use your new Kotlin-based style information in your composables

• How to style Text Composables specifically

Before proceeding, it is important that you understand what a composable is. I will not be stopping to explain that concept here, as I already have in this article.

How We Used to Style Android Apps Using XML Resources

As usual, I like to share with you the motivations behind, and a bit of history on, these topics. In case you do not care, feel free to skip to the next section where we get into the practical stuff.

Android Resources

The Android app resources system is something which the Android team deserves a high five for, at least in my opinion. But like every design decision, a feature in one situation becomes a flaw in another situation.

To be specific, one of the greatest challenges for both platform and application developers alike is to create what I will call localized resources. I am referring to the challenge of building apps which:

• Display text and graphics in a variety of different languages and alphabets

• Look and feel proportionate to a wide variety of form factors (dimensions, densities, and so on.)

Those are just two common examples – there are plenty more. The resource system gives us a place where app developers can provide localized resources which the platform can select for at compile time. This saves us having to write that boilerplate code ourselves.

Feature or Flaw?

While I would never want to manage the boilerplate code necessary for localized string resources myself, that does not mean I enjoy writing XML.

In fact, there are very few things I would prefer to do in XML over a modern, idiomatic, and elegant language such as Kotlin or Swift. Personal preference aside, there is a more technical reason why XML resources are not always ideal.

Please note that this is not meant as a criticism of the platform developers/engineers. It is merely an observation of how design decisions always have benefits and costs.

In order to integrate our XML-based resources into our JVM-based application code, we must necessarily have layers of translation (compilation) and platform bridges (APIs). This can present difficulties for both platform and application developers.

Two common problems I ran into were:

• I want access to a resource in a place where I do not want tight coupling to the platform APIs which provide the resource

• I have to write some ridiculous boilerplate code just to change the look of a View (that is, override something defined within resource styles and themes)

The root problem for everyone involved is tight coupling to the View system and the Android resource system (which are themselves tightly coupled together).

For the platform developers, this means they have to build on top of, or work around gigantic and old codebases. Add that they must also try to have new features work on older Android OS versions, and that becomes a very thankless job.

The result for us application developers is most often a lot of boilerplate code, some hacky workarounds for things which intuitively seem like they should be one-liners. Not to mention the main API for getting these resources is Context, which is a class you really do not want to leak in memory.

Enter Jetpack Compose.

How to Set Up Themes, Colors, and Fonts with Jetpack Compose

With our review of the old system out of the way, let's explore a much prettier and simpler way to style and theme an Android application. I said I would keep this practical, but allow one point.

Since we will be doing that work in Kotlin, it means one very important thing: Both we and the platform developers are much less bound by translation (compilation) and API bridges (Android's R class and Context) between XML and the JVM.

In simple terms, this means much less boilerplate code, and much more control at runtime.

For the practical part of this article, my suggestion to you is to follow this process in the order I explain it. I have structured it in the order I follow when writing this code in a new App.

How to Replace Colors.xml Resources with Kotlin Compose

If you have not already decided upon a color scheme for your application, I suggest that you use the various resources available on the official Material Design website. Try out:

• The color palettes

• The color tool

If you plan to support light and dark app themes (explained shortly), try to select a color scheme which supports white text and a color scheme which supports black text.

Example of light and dark color schemes.

Create a file called something like Color.kt (the name does not matter) and fill it with immutable values:

import androidx.compose.ui.graphics.Color

val primaryGreen = Color(0XFF00bc00)
val primaryCharcoal = Color(0xFF2b2b2b)
val accentAmber = Color(0xFFffe400)

val textColorLight = Color(0xDCFFFFFF)
val textColorDark = Color(0xFFf3f3f3)
val gridLineColorLight = Color.Black
//...

You can either use a predefined value like Color.Black or supply your own ARGB Hex value.

Since ARGB Hex is just a bunch of jargon to describe what the heck "0XFF00bc00" means, let me translate:

• First two characters 0x tell the compiler that this is a hexadecimal number

• Second two characters , "FF" or "DC", represent Transparency/Opaqueness/Alpha in Hex

• The remaining six character pairs represent Red, Green, and Blue

How to Add Fonts and Replace the fontFamily Attribute

Typography (fonts) is also very easy to manage. This is the kind of thing where Kotlin's default arguments are very useful.

Create a file called something like Type.kt (the name still does not matter) and create Typography class...:

val typography = Typography(
    body1 = TextStyle(
        fontFamily = FontFamily.Default,
        fontWeight = FontWeight.Normal,
        fontSize = 16.sp
    ),

    button = TextStyle(
        fontFamily = FontFamily.Default,
        fontWeight = FontWeight.Bold,
        fontSize = 32.sp
    ),

    caption = TextStyle(
        fontFamily = FontFamily.Default,
        fontWeight = FontWeight.Normal,
        fontSize = 12.sp
    )
)
//...

...and some TextStyle classes:

//...
val mainTitle = TextStyle(
    fontFamily = FontFamily.Default,
    fontWeight = FontWeight.Light,
    fontSize = 48.sp,
    textAlign = TextAlign.Center
)

fun dropdownText(color: Color) = TextStyle(
    fontFamily = FontFamily.Default,
    fontWeight = FontWeight.Normal,
    fontSize = 32.sp,
    textAlign = TextAlign.Center,
    color = color
)
//...

Whether you provide public functions or values (I advise against using **var** here) is up to your individual preference and current requirements.

How to Create an App Theme in Jetpack Compose

The last thing you need to configure before using your theme in your composables is a MaterialTheme @Composable. I have mine, and along with my light and dark color palettes in a file called GraphSudokuTheme:

import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.material.MaterialTheme
import androidx.compose.material.darkColors
import androidx.compose.material.lightColors
import androidx.compose.runtime.Composable
import androidx.compose.ui.graphics.Color

private val LightColorPalette = lightColors(
    primary = primaryGreen,
    secondary = textColorLight,
    surface = lightGrey,
    primaryVariant = gridLineColorLight,
    onPrimary = accentAmber,
    onSurface = accentAmber
)

private val DarkColorPalette = darkColors(
    //main background color
    primary = primaryCharcoal,
    //used for text color
    secondary = textColorDark,
    //background of sudoku board
    surface = lightGreyAlpha,
    //grid lines of sudoku board
    primaryVariant = gridLineColorLight,
    onPrimary = accentAmber,

    onSurface = accentAmber

)

@Composable
fun GraphSudokuTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {

    MaterialTheme(
        colors = if (darkTheme) DarkColorPalette else LightColorPalette,
        typography = typography,
        shapes = shapes,
        content = content
    )
}

Since you should already be familiar with what a composable is (I gave you fair warning), the only new thing here is darkTheme: Boolean = isSystemInDarkTheme().

To give a simplified explanation, isSystemInDarkTheme() is a call which asks any compatible Android device for the user's preference of a light or dark theme.

It returns a boolean value which we can use in a Ternary (Conditional) Assignment expression such as colors = if (darkTheme) DarkColorPalette else LightColorPalette.

That is actually it. Colors, Fonts, and two Themes defined in a few minutes.

How to Use a Theme in Compose

It is now time to use this Theme in your app. In this app, which only has two primary screens, I just use an Activity as a container for my composables:

class NewGameActivity : AppCompatActivity(), NewGameContainer {
    //...
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        //...

        setContent {
            GraphSudokuTheme {
                NewGameScreen(
                    onEventHandler = logic::onEvent,
                    viewModel
                )
            }
        }
        //...
    }

Wherever you find yourself calling setContent {}, my suggestion for beginners is to immediately place your Theme composable inside of it. Doing so will cause the style information to cascade/inherit to each nested composable.

You are done! Almost.

How to Override Styles and Themes

If you can help it, try to include any colors you will want in your light and dark palettes. This way, when you call MaterialTheme.colors.<Color>, the system will handle the conditional logic necessary to pick the appropriate palette:

@Composable
fun NewGameContent(
    onEventHandler: (NewGameEvent) -> Unit,
    viewModel: NewGameViewModel
) {
    Surface(
        Modifier
            .wrapContentHeight()
            .fillMaxWidth()
    ) {
        ConstraintLayout(Modifier.background(MaterialTheme.colors.primary)) { 
            //...
        }
        //...
      }
}

However, sometimes it is more suitable to write your own conditional logic...or I just got lazy. Fortunately Compose makes many such configurations available as properties:

@Composable
fun DoneIcon(onEventHandler: (NewGameEvent) -> Unit) {
    Icon(
        imageVector = Icons.Filled.Done,
        tint = if (MaterialTheme.colors.isLight) textColorLight 
        else textColorDark,
        contentDescription = null,
        modifier = Modifier
            .clickable(
            //...
            )
    )
}

MaterialTheme.Colors.isLight returns a boolean indicating what mode they are in, then we can use another Ternary Assignment from there.

How to Style a Text Composable

Just set the style argument equal to one of your text styles (whether it comes from MaterialTheme or one of the styles within Type.kt):

Text(
    text = stat.toTime(),
    style = statsLabel.copy(
        color = if (isZero) Color.White
        else MaterialTheme.colors.onPrimary,
    fontWeight = FontWeight.Normal
    ),
    modifier = Modifier
        .wrapContentSize()
        .padding(end = 2.dp, bottom = 4.dp),
        textAlign = TextAlign.End
)

TextStyle has its own copy function ready to go should you need to overwrite anything.

And that's it! You now know how to style and theme an application using Jetpack Compose. Thanks for reading :)

Social

You can find me on Instagram here and on Twitter here.

Here are some of my tutorials & courses

https://youtube.com/wiseass https://www.freecodecamp.org/news/author/ryan-michael-kay/ https://skl.sh/35IdKsj (introduction to Android with Android Studio)

Hey there, how are you? I'm an 18 year old a backend developer and an aspiring Machine Learning Engineer. And in this article, I'm going to be writing about how to build a web app on your phone using Python 😁. Let's dive into it.

Requirements

The first thing we need here is an Android phone, at least version 6.0 and upward. But what if I told you that's all we need? Seems too good to be true.

Now the next thing we need to do is install a mobile application on our phone called pydroid3.

As you can see, pydroid3 is a mobile application that lets you write Python on your mobile phone, so go ahead and install it.

The next thing we need to do is install Django. If you're not familiar with Django, please check out the Django docs here.

To install Django we need to open up the side navigation in our pydroid3 and select Terminal:

Then click on it and we should see this:

Once that is done all you need to do is type the following command:

pip install django

And you should get the below. I am getting a "requirements satisfied" message because I already have it installed.

It has installed successfully, but let's confirm that. In the terminal type django-admin and hit enter.

You should get this:

This means that it's actually installed already.

How to Build our Project

So let's get started with building our project. Open up your terminal and type in the following command:

django-admin startproject myapp

This creates a Django application called myapp in your root folder.

Change directory to it by typing cd myapp and type in python manage.py runserver. Then you should get this:

Now the server has started. Next, to test it in the browser visit 127.0.0.1:8000.

And boom! You should see that Django has been setup successfully.

The next thing we need to do is create our Django app. In Django, the project folder serves as the root while the app serves as the application itself.

To create a Django app, make sure you are still in the directory, then type python manage.py startapp todo. This creates a To-do app in our myapp project like this:

Then inside the todo folder we should see something like this:

We will take a further look at the files when we begin working with them.

How to Configure our Application

Now let's make it possible for the app to be served by the Django project. First of all, open up your settings.py file in the myapp folder and add 'todo' to the installed apps like this:

Next we need to open up our urls.py and add the following to your code:

from django.urls import path, include

path('', include('todo.urls'))

What actually happened was that I added include to the from the django.urls import path. And below the path (admin) , we created an empty path that points to or includes the urls.py file in the todo app directory. I hope that's clear.

Next we need to create a new file in the todo file directory named urls.py and add the following code in it:

from django.urls import path
from . import views

urlpatterns = [
    path('', views.index, name='home')
 ]

We imported path from Django.urls and also imported views from the root directory. Then we created our urlpatterns with the first part as the root link. As you can see, the views.index just means that we're pointing this views to the index function in on views.py file. You will see how that works in a jiffy.

Let's go ahead to our views.py file and add some code.

At the top, import HttpResponse like this:

from django.http import HttpResponse

And add this below it:

def index(request):
    return HttpResponse('Hello')

As you can see, we created the index function we called in our urls.py and we passed in a request parameter into it. Then we returned an HttpResponse.

But before the HttpResponse can work, we have to import it from django.http import HttpResponse – as simple as ABC. Let's try this: open up your terminal and cd into myapp and type python manage.py runserver to test it.

As you can see, it returned the response. So next we will load our template HTML files.

To load our HTML files we need to create a folder like this in the todo directory in this order:

todo/templates/todo

In the todo directory, create a folder called templates. Inside that folder, create a folder called todo, as simple as that.

Then go ahead and create a simple HTML file called index.html and write this in it:

<h1>Hello world</h1>

To load it, make your views.py code look like this:

def index(request):
    return render(request, 'todo/index.html')

Now instead of returning response we returned a render view that allows us to render our HTML template now, save this open up your terminal cd into myapp and run it. We should have this

As you can see it works well - on to the next step.

How to Set Up the Static Files

Now to set up the static files, create a new folder in your todo directory and name it static. Inside that folder, create a folder and name it todo.

So it should be like this: /static/todo/.

In the todo directory, create a file and name it main.css. Then let's write a little styling in it:

body {
background-color: red;
}

And save it.

Now let's re-edit our index.html file by writing this code:

{% load static %}
<!Doctype html>
<html>
<head>
<title>My page</title>
<link rel="stylesheet" href="{% static 'todo/main.css' %}" >
</head>
<body>
Hello
</body>
</html>

And now let's run it:

If you've followed along with me, then you should have the above.

How to Load the Models and Admin Panel

Now to load up our admin panel, we need to create a superuser. This is simple to do – just open up your terminal and cd into the myapp folder then type python manage.py createsuperuser and hit enter. You should see this:

We get an error because we haven't run python manage.py migrate yet. So type that and hit enter, and you should have something like this:

Now type in python manage.py createsuperuser and hit enter:

Just fill in the credentials. The next thing we need to do is to run our server and point to 127.0.0.1:8000/admin.

Login and you will be directed to the dashboard:

Now that we have done the admin panel, let's work with the model (database). We'll create a model that collects contents. So open your models.py file and type in this code:

class Post(models.Model):
    content = models.CharField(max_length=255, null=False)

    def __str__(self):
        return self.content

We create a class that has the parameter models.Model and gives a variable content that holds a CharField(), more like a text field. Lastly we create a magic str that returns the name of the model instead of an object.

So next we need to run the migration. Open your terminal, cd into myapp, and type python manage.py makemigrations. You should see this:

That means it has created the Post table in our database. Then also run python manage.py migrate which will result in the following:

This means that all is clear. Now to add it to the admin page, open up admin.py and type in this code:

from .models import *

admin.site.register(Post)

We imported all model classes from the model and registered the post model in the admin panel. Now if we open the admin panel we should see the post and save some data.

Notice that it's now in the todo app list:

After clicking on it you should see this:

Then you can create a post if you like.

How to Render Data from DB to View

Lastly we will fetch our data from the DB. To do so we need to update our views.py as follows:

from .models import *

def index(request):
    content = Post.objects.all()
    context = {'content': content}
    return render(request, 'todo/index.html', context)

It's as simple as that: we imported all from models.py, created a variable called content, and retrieved all the data from the table Post. Then we passed it as a dictionary to our view. So in our index.html to make it work just add this:

{% for contents in content %}
{{content.content}}
{% endfor %}

Here, we wrote a loop using the templates tag and fetched all the data content. Now open your terminal, cd into myapp, and run the server to see the magic happen:

It works, but let's confirm that it does:

And the result should be the following:

Violà – it works fine. Lastly you can just add a line break so you can read it more clearly. And we're done!

Thank you for reading. If you want to go through an in-depth Django tutorial please visit my YouTube channel Devstack and subscribe.

For my first few years as a software developer, primarily working with the Android SDK, I had no idea of what the Android Debug Bridge (ADB/adb) was, what it did, or when to use it.

Amusingly, it was not some professional goal which motivated me to learn about it initially. Rather it was my boot looping Nexus 6 which I desperately wanted to resurrect. For a problem like that, Android Studio and Gradle are about as useful as a waterproof tea bag.

I would also like to mention that this article has been written with two kinds of individuals in mind:

• Those who are familiar with CLI, Shell, Processes, and the Client-Server Model

• Those who are not familiar with CLI, Shell, Processes, and the Client-Server Model

For those in the first category, you may wish to skip the section titled: "How to Work With The ADB."

For those in the second category, I will assume you were like me as a Junior developer and know very little about CLIs, Shells, and the ADB. The first section is a soft introduction and glossary for some basic terms and ideas, explained in the simplest way I can manage.

Preliminaries

Here, we will learn about some topics which are important if you want to understand how the ADB works and is used.

Some of you may have been scared away from learning command line tools in the past by sneering Vim enthusiasts or judgmental Unix System Administrators. As you will see, I freely admit that CLI is not ideal for how my brain works, so I think you might enjoy my take on the subject.

Command Line

Simply put, a command line is an interface (way of sending/receiving information) to a computer which only uses lines of text.

It is important to understand that a command line interface (CLI) is not itself a program, but rather some programs will provide a CLI (and perhaps other interfaces such as a GUI as well).

At some point, you may have typed something into Windows Command Prompt (or MS-DOS if you are a 90s kid like me), Mac Terminal, or something like GNOME Terminal common on many Linux distributions. All of these are primarily used via a CLI.

The benefits and deficits of using a CLI depend largely on the individual using it, and what kind of problem they are trying to solve. I personally do not like using a CLI unless it is for something that I do almost every day.

My brain is simply not suited for memorizing obscure shorthand text commands (I had trouble learning to read as a kid for the same reason), so I must rely on a great deal of repetition-based implicit memory (muscle memory) and cheat sheets.

For those who are willing to put the time in even if it is a struggle (like I do), or those who are really quite good at remembering such things, you will likely learn to appreciate how much more efficient you can be within a CLI versus a GUI.

Many operations can be carried out in a fraction of the time it takes to point and click your way through various menus and screens. It is also possible to write scripts, which are files containing a series of text commands, that can increase your efficiency even further.

How to use the ABD Shell

I will have to assume that you are familiar with the term Operating System (OS), which includes Android, iOS, Windows, Mac, Linux, and any other Unix-like system.

Why is this term relevant to the ADB? To give an explanation which prioritizes clarity over precision, the Android OS is based on Linux, and Linux is based on Unix.

As a result of this, we can use the ADB to get a hold of the Unix Shell for the device or emulator we are working with. This allows us a great deal of flexibility, capabilities, and control over the device or emulator by directly interacting with its shell.

A shell is a general term for the program which you use to interact with an OS. Just as a turtle shell provides protection and access to a turtle (and is the outermost layer), the shell of an OS both protects and provides access to the inner workings of the OS. Personally, I was quite surprised to learn that "Shell" was not some esoteric acronym.

Do not feel the need to overthink this term. If you are reading this on a computer of some kind, you used a shell to help you get here.

A shell can provide either or both a CLI or GUI. In either case you will use it to create/update/delete/move files, start other programs, and access the various services of the OS which are made available through the shell.

How to use the ABD Client and ABD Server

Again, let us start with a slightly imprecise explanation which is hopefully easier to understand. I will correct this definition shortly, though.

Clients and Servers are both computers. The reason why we differentiate them in this way is based on their role. For example, your computer (whether it is a desktop, laptop, phone, or whatever else) is a Client of a freeCodeCamp Server, which serves you this HTML page.

In general, a client is something which uses something else, whereas a server is that which is being used. Do not overthink this term, as a Client-Server Model can describe a very large number of things both inside and outside of computing.

Now, when I said that Clients and Servers are both “computers”, that is not really true in the context that we will use these terms later on.

As programmers and engineers, we typically ought to think of Clients and Servers as being processes (a process is simply a running program).

This means that while a Client process and a Server process often do run on separate computers, it is also fine if they run on the same computer.

They will occupy distinct locations in the memory space of said computer, so effectively the only difference is that they will communicate using IPC (inter-process communication) as opposed to sending messages to each other through a network connection.

As we will see shortly, the ADB makes use of a Server process, which allows multiple developers (multiple clients) to manage multiple Android devices and/or emulators.

In an enterprise setting, this Server process would likely sit on a remote (communicated to through a network connection) computer, but we will set up a Server which is local to our Client. Doing that will be much simpler than you probably think it will be.

What is an ABD Daemon?

In case you skipped ahead, I already explained that a process is simply a running program. A Daemon is a process which runs in the background, which is to say that the user does not directly interact with it.

For example, if you open a web browser, then chances are that the actual work of managing the network connections required to connect to the Internet will be carried out by something like a NetworkManager Daemon (as opposed to the browser process itself).

Each Android device (physical or emulated), assuming it is configured properly, will have an ADB Daemon (adbd) which executes commands given to it by a Server process.

In short, when our Client issues a command to the Server, the Server will forward that command to the ADBD, which will execute it on the device.

How to Use ADB for Android Development

For the remainder of this article, we will explore the following topics:

• Drivers and configuration necessary to use the ADB on your system

• Using the ADB with physical devices and emulators

• Basic commands using the ADB’s CLI

• A glance at more complicated usage using an Android device’s Shell via the ADB

Before proceeding, you will want to establish what CLI tool you will be using to interact with the ADB. On Windows, I prefer using PowerShell, but Command Prompt would work too. For Linux and Mac, the default Terminal should work.

Feel free to use whatever gets the job done.

This article contains a very detailed explanation of the whole process, but I have prepared a video tutorial which covers it succintly here:

How To Understand The CLI Examples

This article contains many commands to be inputted to your preferred CLI tool. Any part of a given command which changes situationally will be written within angle brackets.

Do not include the angle brackets in the CLI command you write.

For example, if I wrote...:

adb pair <ip-address>:<port>

...you would substitute the angle brackets and name for the actual value, such as:

adb pair 192.168.0.1:5554

ABD Drivers & Configuration

Firstly, ensure that you have the latest (or at least a recent) version of the Android SDK Platform-Tools. If for some reason you do not use Android Studio (AS), click that link and download the standalone package for your respective OS.

If you have Android Studio, you can download or update this package using the SDK Manager.

There is typically a toolbar icon in AS to open the SDK Manager, but they like to change what it looks like practically every hotfix.

If you do not have luck finding it, go to File -> Settings and in the search bar, type “SDK”, and search for the “Android SDK” menu item.

Systems setting showing that Android SDK Platform Tools are installed

The next step changes depending on a number of variables. As discussed in the Preliminaries section, the ADB uses a Client-Server Model which allows a lot of flexibility in how you use the tool.

To be more specific, you may have:

• Multiple Clients interacting with a remote Server

• A Server which is local (same computer) to one Client

• A variety of physical devices and emulators hooked up to the same server

Advanced configuration with multiple Clients and an exceedingly large number of devices is possible with the ADB, but outside of the scope of this article.

One Server can manage up to 16 emulators and as many physical devices as you would like (within reason), without requiring advanced configuration.

For the remainder of this article, the most we will work with is one physical device and one emulator for a single ADB server process.

How to Configure An ABD Emulator

Most likely you do not need to make any further configurations, but it is possible you may need to enable Developer Options on your emulator. You will know very shortly if it is working properly when we get to our first few ADB commands.

If you do wish to enable this feature on your emulator, you will need to research how to do that for your particular version of Android.

USB Debugging – How to Configure a Physical Device

If you are not planning to use a physical Android device, you can skip this section. However, it is worth noting that you may still need to enable Developer Options

In order to proceed, you will need to configure either USB Debugging or WiFi Debugging on your Android device and development machine.

In either case, start by enabling Developer Options on your device. You will need to research how to do that for your particular version of Android.

USB Debugging

Ensure that you have enabled USB Debugging on the Android device via Developer Options. The link I shared above will describe that process, which tends to change somewhat across different versions of the Android OS.

Before proceeding, Windows users will need to download a USB Driver. Ubuntu users also require some extra steps. For Mac and Chrome OS, you should be good to go.

Once USB Debugging is enabled via Developer Options, connect your Android device via a USB cable.

WiFi Debugging

If you happen to have multiple physical devices or a shortage of USB cables, then you may want to opt for WiFi Debugging.

Again, visit Developer Options on your Android device and enable Wireless debugging. It should prompt you about Allowing debugging on the network which the device is currently connected to, which you should allow (assuming that is the appropriate network).

Time to start working with your CLI. First, you will need to locate the platform-tools directory (or folder – same thing) within your Android SDK installation directory.

Assuming you have Android Studio installed, a quick way to locate it via the app is to again go to File -> Settings, then type “SDK” in the search bar. The “Android SDK” menu will show you where your SDK is installed, which will be the directory that should contain platform-tools.

In the example below, I copied the path to my Android SDK directory, and then opened an instance of Windows PowerShell. I then typed the following commands:

Change Directory:

cd <path-to-SDK-directory>

List Files and Directories:

ls

Next, I typed cd platform-tools to navigate to that directory. Note that the following steps assume you are using a device which is running Android OS 11 or higher.

If you are working with a device running Android 10 or lower, detailed instructions for that situation can be found here.

Once you are within the platform-tools directory, you are ready to pair an Android device to a development machine using the following steps:

1. Within the Wireless debugging submenu in Settings -> System -> Developer options, select Pair device with pairing code.

2. Within your CLI tool which should be set to the platform-tools directory, enter the following command:

adb pair <IP address>:<Port>

where both the IP address and the Port come from the dialogue on your Android device which popped up after selecting Pair device with pairing code (do not include the angle brackets).

Note: You may need to prepend your call to adb with some other symbols or commands depending on which CLI tool you are using, your OS, and your access controls. For example, I had to type .\adb pair : using PowerShell on Windows.

3. Assuming things went well with your CLI, you will be prompted to enter the pairing code which was made visible in the same dialog on the Android device which gave you the IP address and Port number.

4. After entering the pairing code, you will know this operation was successful if you receive a message stating:

Successfully paired to <IP Address>:<Port> [guid=<Some GUID>]

5. If you are using Windows or Linux, you will also need to run the following command using the IP Address & Port which is visible from within the Wireless debugging preferences menu (not the dialogue which pops up after selecting Pair device with pairing code):

adb connect <IP Address>:<Port>

after which you should receive a notification on the phone to indicate that you are connected.

How to Use The ADB: Commands

Assuming you managed to properly configure your Android device and your development machine, you can now use the ADB tool.

Before proceeding, navigate to the directory which contains adb using a CLI tool (unless you just followed the steps in the previous section for setting up WiFi debugging).

Otherwise do so now, or check out that section for instructions on how to locate that folder.

How to See Which Devices Are Currently Connected To The Server

You can now start up an adb server by calling just about any command on the ADB except adb kill-server. Whether or not your server process is running, type in the following command:

adb devices

In the above screenshot, I first called adb devices when my Android phone was connected to the server. After killing the server via the adb kill-server command, I once again called devices which restarted the server.

Again, if an ADB server is not currently running, calling more or less any ADB command will start the server back up (except adb kill-server, of course). There is an explicit adb start-server command, but in practice I have never needed to use it.

Since the server was reset, devices did not return any items. Therefore, before moving to the next example I had to once again use the adb pair and adb connect (if on Windows or Linux) commands described in the previous section.

I have now fired up an emulator using PowerShell and the emulator program which is also located in a subdirectory of platform-tools called "emulator."

You may of course use the AVD Manager or Android Studio to start up an emulator to follow along with the example if you would like to.

If you have many connected devices, a useful option for the adb devices command is -l, which gives you more information about the devices.

Below you will see several entries which refer to my physical Android device, as well as an emulator which has been attached to a specific port:

How to Send Commands To A Specific Device

To avoid accidentally bricking my phone, I want to send commands to the emulator instead. To do this, I must prepend the -s option, followed by the serial number of the target device, before typing the command.

The serial number is the first set of characters which describes a connected device after using the devices command.

For example, the emulator’s serial number in this case is just the word emulator followed by the port which the emulator is currently attached to.

The other red arrow points to the serial number for my phone (blocked out for obvious reasons).

Naturally, if you only have one device connected (whatever kind it is), you do not need to use the -s option.

Install An APK (App) On A Device

I am now going to install a test APK on the running emulator using the adb install command.

This is basically equivalent to having Android Studio and Gradle install a debug APK. As you will see, test APKs require the -t option after the install command:

adb -s <device-serial-number> install -t <path-to-APK>

Note: The Android OS requires that any APK must be signed before it can be installed (even if it is just a test/debug APK).

One solution is to build and run the app to be installed in Android Studio, which will sign it with a generated debug certificate. There are several other ways to sign such an APK which you can explore by visiting this link.

What Else Can ADB Do?

Before we take a look at some more advanced usage of the ADB, I strongly encourage you to try the adb --help command. As is customary for most CLI based programs, the help command will print out documentation which describes the various commands and options of the tool.

I am happy to say that the documentation for the ADB is quite legible and useful, which is not always the case in CLI programs.

Advanced ADB Usage Tips

It would be a waste of time for both of us to cover every usage and command of the ADB in this article.

In case there is any confusion, using the ADB to install APKs and do many of the things which Android Studio and Gradle do for you is not something that I would recommend (unless you have a good reason to do so).

With that being said, there are plenty of things that the ADB can do which are either difficult or impossible to do without it.

In the preliminaries section, I mentioned that the ADB can be used to get a hook to the shell of the device. To finish this article off, we will look at how to use shell commands and where to find more information about them.

If you do not know what a shell is, you probably skipped the section above where I explained that.

How to Use the ABD Shell

Sending a command to the device’s shell using the ADB is fairly simple. Remember that if you have multiple devices connected, follow it with -s <device-serial-number> to direct the command to a specific device.

To make a single shell command, we must use the adb shell command (big surprise, eh?), followed by the actual command we want to make on the device's shell:

adb shell ls

Output:

As mentioned previously, the ls command displays a list of files and directories at the CLI's current directory. This happens to be the Android device's root directory until we move to a different one.

If you plan to be making many commands via the Shell, you can also start an interactive Shell session. This can be done via the simple command:

adb shell

While in an interactive Shell session, you can type Shell commands directly without further use of adb shell <command>.

Note that when you want to quit the interactive Shell session, you can do so by typing exit or hitting Ctrl + D.

There are a variety of different commands and utilities you can work with via the Shell. The ActivityManager (am) of an Android device can be particularly useful for testing different components (Activities, Services, BroadcastReceivers, to name a few) of an Android app under different circumstances.

Suppose we want to launch straight into a particular Activity, but this Activity is not designated as the launcher Activity in the manifest.

You will still need to add the android:exported=”true” attribute to each <activity/> entry in the manifest which you want to launch (assuming it is not already the launcher Activity).

After that you can use the following command to go straight to it:

am start -n <app-package-id>/<activity-name>

Note that the <activity-name> must include whichever packages, relative to the package-id, within which it is located. See the output below for an example of launching an Activity which sits within several packages.

Further Reading

My goal in this article was to do my best to introduce, explain, and guide you through the usage of the ABD in my own words (insofar as that is possible).

At this point I would need to start making some very contrived examples or to simply carbon copy the documentation, neither of which are things that I am interested in doing.

Instead, I would like to encourage you to visit the documentation, and to have a brief look at some of the cool things you can do using tools like the Activity Manager, Package Manager, Policy Manager, and others.

You can get in touch with me on social media here:

https://www.instagram.com/rkay301/
https://www.facebook.com/wiseassblog/
https://twitter.com/wiseass301
http://wiseassblog.com/