If you’ve built a UI with Coil and AsyncImage, you’re probably used to large blank areas in your previews. This doesn’t matter much if you have placeholders set, but this isn’t always the case. Luckily, LocalAsyncImagePreviewHandler allows arbitrary drawables to be used in previews.

Kotlin code

First, here’s the entire utility function, in PreviewAsyncImage.kt:

@OptIn(ExperimentalCoilApi::class)
@Composable
fun PreviewAsyncImage(
    drawableResId: Int,
    content: @Composable () -> Unit
) {
    if (!LocalInspectionMode.current) {
        error("PreviewAsyncImage should only be used in @Preview functions")
    }

    val context = LocalContext.current
    val previewHandler = remember(drawableResId) {
        AsyncImagePreviewHandler {
            val drawable = ContextCompat.getDrawable(context, drawableResId)
            val bitmap = if (drawable is BitmapDrawable) {
                drawable.bitmap
            } else {
                // Convert vector/other drawables to bitmap
                val width = drawable?.intrinsicWidth?.takeIf { it > 0 } ?: 1
                val height = drawable?.intrinsicHeight?.takeIf { it > 0 } ?: 1
                val bitmap = createBitmap(width, height)
                val canvas = android.graphics.Canvas(bitmap)
                drawable?.setBounds(0, 0, canvas.width, canvas.height)
                drawable?.draw(canvas)
                bitmap
            }
            bitmap.asImage()
        }
    }

    CompositionLocalProvider(LocalAsyncImagePreviewHandler provides previewHandler) {
        content()
    }
}

And here’s how to use it as a wrapper, where every AsyncImage will display preview_image:

@Preview
@Composable
fun ComposableWithAsyncImagePreview() {
    PreviewAsyncImage(R.drawable.preview_image) {
        ComposableWithAsyncImage()
    }
}

Explanation

Coil does all the hard work for us in terms of overriding the preview, however we still need to actually obtain a bitmap. Since the drawable reference could be a bitmap (e.g. a .png) or vector (e.g. a .xml), we may need to place the drawable onto a canvas first.

We also have a guard at the start to ensure this is never run outside a @Preview context, since it’s conceivable a preview function’s contents could be copied without noticing the override.

The simple wrapper makes implementation easy across an entire codebase, helping improve preview accuracy and avoid accidental UI issues. Whilst it is also possible to directly map remote image calls to specific resources, that was not necessary for my use case.

Finally, here’s the wrapper in action, as per the PR implementing it!

Scenario

I use my laptop for mostly media watching / listening during the day whilst working on my MacBook, with a bit of programming and gaming (mostly Forza Horizon or Fallout). It stays closed 24/7, mounted under my desk, with 1x 1440p & 1x 4K monitor connected.

As such, I need a “bit of everything” laptop. Decent CPU for code compiling, decent GPU for gaming, but also looks like a regular laptop and isn’t absurdly heavy or covered in RGBs. The ThinkBook 16p Gen 2 did a pretty good job at this, but the gaming performance was somewhat limited (not helped by me buying a 2-year old model!). Time to upgrade to a 2025 Gen 6!

Disclaimer

Whilst the technical specifications and benchmarks are presented as unbiased as possible, a laptop used daily for over 2 years is always going to have reduced performance. Despite closing any additional programs (e.g. Steam, WhatsApp), various things are probably running in the background and using up system resources, in additional to the typical hardware wear and tear.

The new laptop was fully set up before I used it, meaning it’s totally possible that a single misbehaving program (e.g. Lenovo Vantage, or Logi Options+) might be skewing the results. However, the entire point is a real-world comparison, so I don’t mind at all, hopefully you don’t either!

Specifications

Since I was intending to buy the mid-high spec ThinkBook 16p Gen 6 at full price, a 20% Black Friday discount meant I could purchase the max spec ThinkBook 16p Gen 6 instead!

Benchmarks

Benchmarking tools

Obviously these are just benchmarks, so aren’t necessarily reflective of actual improvements. Regardless, the numbers are impressive, and reflect 4 years of technological progress. The SSD improvement across reads and writes is startling, as I didn’t know PCIe 3.0 -> PCIe 4.0 would make such a difference! I was mainly just looking forward to 1TB, since 500GB was getting a little cramped. Sequential writes apparently benefited most from the upgrade, with an absurd +1820%.

More realistic however are the 3DMark benchmark improvements, which should be fairly close to real world performance. Both widely used tests agree on a 70-80% improvement in performance, which is enough to go from an unstable FPS playing games at high quality settings at 4K resolution, to an actually enjoyable experience.

Real world comparisons

In addition to the benchmarks, here’s a time comparison for a few things I actually do day-to-day. Startup time, a programming-y task, and a gaming-y task. My anecdotal experience from the very start was a clearly snappier and more responsive system, although a lot of this is of course due to just being a clean system.

The results are about as expected, with the key difference for me being doubled performance on high graphics at 4K resolution. Whilst time saving during tasks is good, the ability to actually play games in high quality is a far more immediate benefit!

Photos

Overall, the Gen 6 distinctly feels both more modern and more premium. Edges tend to be sharper, there are far fewer curves, and it gives off a bit of a “Cybertruck” vibe. The position of the “ThinkBook” and “Lenovo” branding also seems to have swapped around, who knows why.

Additionally, the ports are better placed, ventilation seems significantly better, and there seems to be a heavy MacBook inspiration on the keyboard. It’s clearly the same family of products as the Gen 2, but reflects a few years of design improvements.

Edges

In these photos, the Gen 2 is on the bottom, therefore the Gen 6 is on the top.

Side	Photo	Notes
Front		The Gen 6 is notably “chunkier” here, along with the “Magic Bay”11 connector.
Back		The Gen 6 is very different here, with absolutely massive air vents, and the very sensible decision to have an HDMI connector here instead of 2x USB, and move it further away from the proprietary power port since it was extremely easy to confuse them (they look identical at a glance!).
Left		The Gen 6 has kind of “swapped” left and right, with the 3x USB-C & 2x USB-C ports now being entirely on the sides. Interestingly, the side vents have disappeared, presumably because of the giant rear vents.
Right		No additional comments.
Front 2		Side by side, the chunky Gen 6 clearly has far more space for hardware inside! It is slightly elevated due to the “Magic Bay”11 keeping it off the table, but there’s still a distinct difference.

Top-down

In these photos, the Gen 2 is on the left, therefore the Gen 6 is on the right.

Scenario	Photo	Notes
Top		A fairly similar design (besides the branding swap), although as a running theme the Gen 6 looks more modern.
Top (Partially open)		The keyboard is mostly the same, but the clutter above the backspace has been replaced with a sensible Home / End / Delete / brackets, and additional Page Up / Down buttons have appeared next to the arrow keys. I don’t use the keyboard much, but I approve of the utility keys replacing gimmicky shortcuts (except the Copilot key!).
Top (Fully open)		No additional comments, note that the pattern in the speaker is just a reflection.
Normal view		The Gen 6 screen is noticeably higher (a bit better for posture), otherwise about the same.
Bottom12		The Gen 6 footpads are noticeably larger, and the vent shape has changed. I would guess this is to avoid dust blocking the vents.

Not noticeable in these images is a small improvement to the webcam privacy shutter: It now “sticks” to either side via magnets! Previously it would freely slide, meaning it often ended up pointlessly half-covered.

Mounted

This is only relevant to my under-desk mounting setup (documented here), the Gen 6 is a far better fit.

ThinkBook 16p Gen 2	ThinkBook 16p Gen 6

With the new laptop mounted the other way round (back facing outwards) purely for USB-C port access, I gained multiple other benefits!

• The laptop no longer pokes out a bit (very annoying!), although the power cable is still technically sticking out.
• The heat ventilation is drastically improved. Previously it vented out the bottom (fine), and the back / sides where only a small amount of space was available before the desk infrastructure, so overheating was common. Now, it vents entirely into the room uninterrupted.
• There is now a very accessible USB-A port next to where the USB-C monitors are connected, plus a couple more fairly accessible USB-A ports on the other side.

Summary

Overall, I’m very happy with the purchase! As with the occasional phone upgrade, I just wanted “the same, but better”, and that’s definitely what I got. After a few hours of setup, the new laptop feels almost identical¹³, with the only difference being essentially everything being speedier and more reliable. Yippee!

Hopefully this laptop lasts at least 2 more years, and is up to the task of playing Forza Horizon 6 when it releases in 2026 🤞.

Tech specs

• Gen 2 tech spec: https://psref.lenovo.com/syspool/Sys/PDF/ThinkBook/ThinkBook_16p_G2_ACH/ThinkBook_16p_G2_ACH_Spec.pdf
• Gen 6 tech spec: https://psref.lenovo.com/syspool/Sys/PDF/ThinkBook/ThinkBook_16p_G6_IAX/ThinkBook_16p_G6_IAX_Spec.pdf

Notes

What are cards?

In case you haven’t used them much, Steam Trading Cards (launched in 2011) are Steam inventory items earned by having eligible games open (e.g. paid games that have opted in). The cards have a few possible uses:

1. Sold on the Steam Market (what we’ll be doing).
2. Crafted into cosmetic badges for your profile (this is why people will be buying your cards).
3. Turned into gems for card booster packs (not worth it).

Ultimately though, all that matters is that they only require time to earn and can be sold for Steam Wallet currency. This is directly spendable on games or other inventory items, so is pretty close to just earning cash.

Farming cards

First, it’s worth checking that you have unearned cards. If you only play free games, or own very few games, you may not. Since I’ve purchased a few game bundles over the years, I had almost 1000 unearned cards!

Eligibility

You can check your eligibility by visiting the “Badges” page of your Steam Community profile whilst logged in, and searching for the word “PLAY” that is shown next to eligible games:

Automation overview

So, assuming you are eligible for card drops, let’s automate earning them. Whilst you could install every eligible game and run them until the cards are earned, this is a complete waste of both your time and your machine’s processing power!

By using automation software, we can instead report to Steam that the appropriate game is running. This allows you to just press start and leave your machine, using almost no system resources (12MB RAM for me) and skipping the arduous game downloading process.

Additionally, the automated process is optimised to factor in the variable per-game minimum time, utilising a somewhat complicated process of cycling between single and multi game idling called “Fast Mode” that would be very hard to perform manually.

Idle Master Extended

There are a few automation tools available, I personally chose Idle Master Extended. Installing any software, especially one gaming-related, is always a risk. However, here’s why I decided this was safe:

1. The repository has 3k stars, plus an appropriate number of forks, watchers, issues, and pull requests for a project of this size. Malware will typically just have stars.
2. The project is stable, with no releases in 2.5 years. Considering Steam hasn’t changed much in that time, this is actually a good thing!
3. The project is mentioned often on Reddit and other places, with all the natural tech support questions and comparison between similar tools you would expect from real software.
4. It looks like a developer’s tool. Completely showing my bias here, the simple nature of the UI (screenshot below) clearly indicates a utility tool, exactly what we need. It’s also only 1MB big!

Note: ArchiSteamFarm is far more popular (12k stars), however the regular releases, more complex setup process, request for your username and password(!) and serious complexity / feature set made it unappealing. We just need a simple tool!

Setup

Idle Master Extended has a nice and simple guide to getting started, but I’ll summarise here:

1. Download the latest idle_master_extended_vX.XX.X.zip file from the GitHub Releases, it’ll be just over 1MB.
2. Extract the zip somewhere.
3. Run the .exe, it’ll check Steam is running, then ask you to login.

Logging in

Since Idle Master Extended needs to join games and monitor card drops on your behalf, it needs to use your login token. This is obviously a risk, consider your own risk tolerance before proceeding. For me, it’s worth it, due to the reasons listed previously.

To find these details:

1. Go to https://steamcommunity.com (not the store!).
2. Open the developer console (F12, or “More tools” -> “Developer tools” in Chrome).
3. Select the “Application” tab at the top.
4. Select “Cookies” under the “Storage” categories on the left, and click https://steamcommunity.com.
5. Look for your sessionId and steamLoginSecure.
6. Double click each in turn, and copy then paste into Idle Master Extended.

Once submitted, Idle Master Extended will log in, show “Idle Master is connected to Steam”, look up your card eligibility, and start farming cards.

Note: Your session will expire every 2-3 days for security, indicated by Idle Master Extended showing an “X” next to logged in status, so you’ll memorise these steps pretty quickly!

Running

Idle Master Extended’s default settings are typically exactly what you want, and it will try to automatically begin optimised idling on program startup. However, you can also configure features like shutting down Windows when done, or dark theme, in the “File” -> “Settings” menu.

Whilst running, your friends will receive lots of game open and close notifications, so you may want to turn these off! This can be done by setting your “Game details” to “Private” in your privacy settings.

And now… you wait!

Cards drop at random intervals, so it’s hard to gain detailed estimates for the number of cards per hour. For me personally, I’ve used the tool for 6 days at around 12-16 hours a day (autorunning whenever my laptop is on), and have gone from 867 cards remaining to 488. If we estimate running for 14 hours a day, so 84 hours total, we get an average 4.2 cards earned per hour!

4th October	10th October

Selling cards

Okay, so we’ve got some free cards, what do we do with them? Sell them!

Whilst you can do this step automatically, it’s fairly slow to manually set an appropriate price for a few hundred items. Instead, we’re again going to rely on a “userscript” to do the heavy lifting for us.

Preparing to sell

Unfortunately, the tool we want to use can’t be run on Chrome. Instead, you’ll need to use Firefox, Brave, or whatever other browser you want to use. I used Firefox.

1. Install a userscript manager, I used Tampermonkey since it’s been widely used for a very long time. “Violentmonkey” is an alternative.
2. Install Steam Economy Enhancer by tapping “Install Steam Economy Enhancer”, then “Install” (next to Cancel).
3. Open up your Steam inventory, and you should see a new “Sell All Cards” button among others!
4. Additionally, market prices for your cards will start loading and being displayed:

Note: There is also an extension “Steam Inventory Helper” with more advanced functionality, however it is full of shady adverts, wants quite extensive permissions, and has overgathered data before. I don’t recommend it!

Selling

Tap “Sell All Cards” and… it’ll start! There’s also a “Sell All Items” option, but obviously don’t tap this if you have things you don’t want to sell (backgrounds, emotes, etc).

Once tapped, it’ll run through every marketable item you own, and tell you the sale price and your earnings after Valve & the game’s commission (typically 1-2 pennies / cents per item). These cards won’t sell immediately, as most already have thousands listed. Instead, a few sales will trickle through every day as older sales are processed and your listings move closer to the front.

Note: Sometimes this process gets “stuck” due to a failed request. Refreshing the page and tapping “Sell All Cards” again continues from where it paused.

Note 2: Some cards (e.g. from delisted games) are not marketable. These can be converted into gems, but are almost worthless.

Confirming

However, there might be another reason the cards don’t sell: You haven’t confirmed them yet! Depending on your Steam Guard settings, you may need to approve every marketplace listing on your phone, a feature implemented to protect expensive items but a bit silly for hundreds of cheap ones.

Open up Steam on your phone, go to your notifications, tap “X pending confirmations”, and tap every single confirmation one at a time. Whilst there are ways to automate this (setting up your browser as a 2-factor device), for me personally this risked account security too much. As such, I just did it manually.

Note: The app lags quite significantly when accepting lots of confirmations at once. Be patient, it’ll get there!

Note 2: The selling process will begin failing with a “too many pending confirmations” error after 100-200 items listed, so you might want to regularly approve them as it autosells.

Profitability

So how much will you actually earn from this?

Each game will drop you half the cards needed for a badge (typically between 5 and 10), so 3-5 cards per game is a reasonable estimate. Cards for popular games will usually sell for between £0.04 and £0.07 depending on the game and number of cards in a set, resulting in a post-commission amount of £0.02 to £0.05. So, around £0.05-£0.15 per eligible game, which sounds pretty bad until you consider…

1. Foil cards: In addition to regular cards, you will sometimes find foil cards. These are usually worth 3-10x as much, with some obscure games having zero listed so you can name your own price in case someone is desperate to complete a collection!
2. Obscure games: For games with few players, the card price will be much higher (although liquidity will be lower). For example, in “Arcade Spirits”, my regular card is worth £0.12, whilst my foil card has no accepted price.
3. Booster packs: Once you have collected all the cards for a game, you are eligible for a booster pack. These are essentially blind boxes with 3 cards in, however they can be sold directly too (and this is usually slightly better profit than opening).

The random nature of foil cards and booster packs makes getting an average profit essentially impossible. For example, one of my obscure foil cards sold for £10, twice as much as the game itself!

However, I would personally estimate around £0.16 per game once all lucky drops are factored in. So, for my 250 eligible games, I’d expect to receive around £40. Not bad for running some automated tools!

Note: This doesn’t include the increased chance of future booster pack drops.

Is it allowed?

I guess technically not? However, is it enforced? Definitely not.

Valve have historically been very, very lenient with automation around the Steam platform (hence Team Fortress 2 trading bots, Steam Achievement Manager operating since 2008, and many more examples!), only stepping in when automation is disadvantaging other users (or Valve). In this case, we’re adding more cards into the economy, helping supply cards for rarely played games, and of course making Valve & the game companies at least £0.01 per sale!

Additionally, the card drops are part of the perks of purchasing on Steam, so you’ve already paid for them. The automation just makes the farming much easier.

Whilst it’s obviously impossible to say the tools recommended in this post are safe, it’s worth observing how their subreddits / discussions / GitHub issues don’t include any mentions of bans whatsoever despite tens of thousands of users.

Conclusion

With both the farming and selling stages requiring ~2 minutes setup work each, then just letting them run, getting the most out of your purchased games seems like a win-win for everyone (you, badge hunters, Valve, game publishers). I’d highly recommend this process to anyone with a substantial library, however obviously assess the risks yourself before starting.

Happy farming! 🧑‍🌾🎴

Before we get started, this will require setting up a company and a forwarding address. Whilst there is a cost, in the UK neither of them are too tricky. I’d recommend Rapid Formations which offer this for around £67/yr, more on that later in “Solution”.

Tl;dr

Don’t want to read the full post? No worries! Here’s the entire thing:

1. You’ll need to form a company in your country using a forwarding address.
2. You’ll then make a new “Organisation” Google Play profile, and verify it with your company’s info.
3. Finally, you’ll transfer your apps and all associated services, and delete your old profile.

That’s it! If any of it seems at all unclear, time to get into lots of detail as I document this process I never want to go through again! There’s also lots of tips around verification in this r/androiddev post.

Scenario

In July 2023, Google announced a controversial policy requiring all developers to verify this information. This sounded fairly innocent and easy, until looking at the detailed requirements for personal accounts. Specifically, if you’re earning money the following will be public:

1. Your legal name
2. Your phone number
3. Your legal address

Whilst I’m happy sharing my legal name (it’s Jake Lee, could you tell?), my phone number and address are extremely private information! My phone number is both a way to contact me 24/7 and used for 2FA SMS in services that don’t support app-based, whilst my address is… literally where my family and I live. This should not be public, ever.

If you want to earn money, the only official options are:

1. Reveal all your information publicly.
2. Let Google close your account and remove all your apps.

Luckily, there is a way to solve this in a Google- and privacy-friendly way by creating a new Google Play Console account. More details in “Solution” after information on / ranting about my personal scenario!

Personal scenario

I’ve been earning money on Google Play since 2016, and once upon a time it earned more than my (low!) salary, encouraging me to become an Android developer, a job I love.

Whilst my apps (e.g. Pixel Blacksmith) no longer earn significant amounts (typically £10-50/month), it’s still a nice bit of bonus money to fund other projects. Similarly, players are clearly still enjoying the apps, so the apps should stay available as long as possible!

I did some work last year to get my old games running, conforming to Google Play’s latest requirements, and sorting out any policy paperwork that needed solving. There was still the developer verification, but that wasn’t required until 2025 so I left it. Now it’s time to solve it!

Failed attempts

Before solving the issue, I failed multiple times. I’ll condense these multi-week stressful struggles into 2 summaries, and spare too many details.

Attempt 1, Apr ‘24

Since I already had a registered company with a forwarding address, I assumed I could use this as my personal address. However, proof of me as an individual at this address was required, such as a utility bill. This was impossible (I don’t live in an office!), and I went through multiple rounds of my company documents & personal documents being rejected.

Throughout this, I was sent various intimidating emails about Google Services being suspended, and when combined with unhelpful slow & vague answers from Google Support, this was a pretty stressful experience.

For example, my Google One (extra storage) subscription was expiring. My Google Pay had been suspended, so it was impossible to renew (with any payment method whatsoever, including Google Play credit). If I hadn’t managed to resolve it in time, I would have had to deleted tens of GBs of photos / data to ensure my storage was within the free limit, otherwise I would have lost the ability to receive emails.

Luckily, I managed to verify my personal address, and delay verification, allowing my payment profile to be unsuspended and pay for Google Pay. Problem not solved, but delayed.

Failed payment	Consequences

Attempt 2, Dec ‘24

I had some time over Christmas, so time to try again!

Since verifying as an individual failed, using the lessons learned from hours of Reddit thread reading, I decided to create a Google Play Console account with a new Google account (the one used for my company) as an organisation. I started the process, entered my company details, and was immediately suspended due to the details not being verified.

Specifically, I was told:

Because we’ve been unable to verify information for one or more users on your Google payments profile, your Google payments account has been suspended. Your Google services will continue temporarily, but some transactions may be suspended.

If action is not taken on this issue within 10 days, your Google services will be suspended.

No problem, it asks for a “Certificate of Incorporation” and I have that. I immediately submitted the files requested, a review time of 24-48 hours was mentioned, easily within the 10-day warning.

And then I waited. And waited.

Whilst waiting, I tried registering again, stating I didn’t want to earn money, to see if this made a difference. It did not.

A week later, I received a 3-day warning, and nothing had changed. Well, it has been Christmas day, lots of holidays, so don’t need to panic quite yet.

Then I received my 1-day warning. I don’t know what “Google services will be suspended” means, but it doesn’t sound good. In fact, since this email address is paying for Google Workspace and controls all my @jakelee.co.uk emails, this sounds very bad indeed.

Contacting support was, yet again, not particularly helpful. The agent couldn’t directly review documents, but did at least confirm my emails would not stop working due to the suspension. Hopefully there’s some sort of manual review required before a suspension, or they’re paused when there’s a large review backlog.

Either way, the final 24 hours expired and… I didn’t receive any updates, but my email still worked. Okay, panic slightly over. Later on I received a casual email that my documents had been verified and all was now OK. Right. What a lot of pointless stress.

Emails received	1 day left	Pending cases

Solution

So, how can this be solved properly, and we can continue earning money whilst keeping private information private?

Part 1: Preparing your details

Setting up a company

To earn money, you will need to share a legal address, this is absolutely required. However, if you’re an organisation this can be your office address, which can be done with a virtual office address, since the government (at least in the UK) accepts them.

So, to set up a company without revealing your home address:

1. Set up a company (I already have Jake Lee Ltd).
2. Set up a forwarding address for your company (I pay £39/yr).
3. Set up a forwarding address for your personal correspondence (I pay £26/yr).
4. Request your D-U-N-S number (this is free).

Rapid Formations offer an all-in-one package that seems to do pretty much everything (including business bank account, domain name, and more). I only began using a virtual office after establishing my company, so cannot personally vouch for this service, only confirm that the virtual office service has been perfect.

Okay, so you now have a legal company with a legal address. That’s the biggest hurdle overcome!

Setting up contact details

Next, you need to give Google some other information to list publicly:

Email: Google requires a public-facing & Google-only email address. These can be the same, and don’t have any specific requirements besides being able to verify them. I’ve had a Google Play specific email address for years and only receive spam (usually about buying apps) once every few months.

Phone: Similarly, Google will want a phone number to contact you, and a number for users to contact you. This is trickier, since you likely don’t want to give away your phone number. Whilst there are various ways to pay for a virtual number, the easiest way is just to request a free SIM card (e.g. from giffgaff), pop it in your phone to verify, then take it out or put in a spare phone.

This is a privacy trade-off (since a phone network now has your address), but I’m only concerned about public sharing of this information so it’s fine. I’ve changed networks enough that most of them know where I live!

Website: You’ll need some sort of public website, verified via Google Search Console. There aren’t any specific requirements here.

Finally, you’ll have an email address, phone number, and website you can use.

Part 2: Creating a Google Play Console profile

Now, you need to use your business’ information to form a Google Play Console profile, and a payments profile.

Setting up an organisation

Next up, you need to create a Google Play Console organisation. Organisations have a simpler verification process (presumably since they rely on existing company verification), which we can use.

This process is straightforward if you have all the prerequisites, specifically:

1. D-U-N-S number.
2. Certificate of incorporation for your company (available on Companies House under Filing History).
3. Contact information (phone, email, address).
4. $25 to pay the registration fee.

During this process, you will be asked to set up a payments profile.

Setting up a payment profile

Whilst setting up an organisation will appear to succeed, it will actually fail, causing the fee payment at the very end to be rejected. At this point you will need to submit your Certificate of Incorporation.

Once you’ve submitted this, and it’s been reviewed (this can take a while, see “Attempt #2”), the “Settings” tab of your payment profile will finally show as verified:

Putting it all together

Once your payment profile has been verified, and you have no outstanding alerts, you will need to register for a Google Play Console account again, select this payment profile, and attempt the fee payment again.

This time, it should succeed, and you’ll finally have a Google Play Console organisation account!

Of course, as soon as you open it you’ll be told you need to verify it. Well, that’s easy now, we have our Certificate of Incorporation and other information from the payments profile. This only took a day or so for me, and didn’t require any new information.

Tidying up

There are various settings here you’ll likely want to fix. For example:

1. You’ll need to verify and link a bank account (Settings -> Payments profile).
2. You’ll need to check your public information (email, description etc) are correct.
3. You’ll need to add a developer profile picture, and banner.
4. You’ll need to verify tax information for the USA and other countries. My payments got temporarily suspended (again) whilst doing this!

Once these changes and verifications have all gone through, you’ll have a verified Google Play Console organisation account! Phew, we’re getting closer.

Part 3: Transferring apps

Great, now you’ve got a new, verified account, you need to transfer your apps! Luckily, this step actually has some official documentation containing the required steps.

Account group

First, you’ll need to invite your new account to an “Account Group” (more info), accept the invite on the new account, and then make it the primary developer account.

This just lets Google knows your 2 profiles are related, and I suspect it makes the app transfer process a bit easier. Since the current profile is owned by you, and the new profile is owned by a company where you are the only shareholder… they’re linked pretty closely!

Sharing access

Next, you need to make sure any Google-related services you’re using in your apps keep working once the apps have transferred.

For me this required giving my new account access to my apps’ Google Analytics, Google Cloud (for Google Play Games, and Maps API), and Firebase (for crash logs). You might also need to do the same for AdMob. The instructions vary by service, however this should be a simple process since it’s just adding a new user.

Firebase	Google Cloud

Requesting transfer

Okay, it’s time to finally transfer your apps! This is surprisingly easy, with official documentation walking you through the process.

One complexity is you’ll need a “registration transaction ID” for your old and new developer account. This is the payment reference for your Google Play registration fee, created when you opened your account. For my old account I had to scroll through all my Google Play transactions back to 2016, for my new account it was in a recent email.

Pay close attention to Google’s (vague) advice here about the transaction ID. You need to remove placeholder-y prefixes from the ID, or the transfer will be rejected:

Important: When providing your transaction ID during the app transfer request process, remove the first part of the Order ID (for example, discard ‘0.G.’ or the digits before the words ‘token’ or ‘Registration’):

Old account	New account

Transferring

Once you’ve got your ID ready, and entered all the new account’s details, you can submit a request. I transferred an unused app first to check it worked, and then did the rest in one big go. You’ll receive a quite helpful email before the transfer, and one confirming the transfer has been successful.

This part was surprisingly easy after all the headaches of payment profiles and addresses. Both my transfers went smoothly, and it seemed like a well-oiled process!

Transfer confirmation	Pre-transfer email	Post-transfer email

You’re done! A few hours / days / weeks of paperwork, and you’re finally done!

Well, there’s a tiny bit of tidyup of course…

Part 4: Tidying up

Whilst your old Google Play profile now has no apps, it still has a verification deadline. To avoid any action being taken against your account (and to get $25 back!), you can submit a request to close your Google Play profile and get a registration refund.

For me this was 8 years after registering, and was done by submitting a request to their cancellation form. I received an email asking me to confirm the deletion, and which added card the money should be refunded to. Again, this went through smoothly, and the $25 was a nice surprise.

I had a few extra payment profiles made during my various earlier attempts to resolve my verification issues, so these had to be closed too. They can only be closed if there’s no linked payments or accounts, including Google Play Console:

If your info was previously listed on the store, you may want to request its removal from Archive.org. Finally, you might want to remove access to Firebase / Google Cloud etc from your old account. I didn’t bother since it makes accessing the data a bit easier.

Conclusion

This was probably the most painful yet stressful experience I’ve gone through since buying my house, made significantly worse due to vague wording everywhere, nobody to talk to, and unknown consequences.

Whilst it all ended well, and my apps are now listed with my business name & address, the solution wasn’t obvious. Instead, on my personal account, I essentially just got threats and impossible requests. It took lots and lots of Googling to find the “create new account and transfer” solution, since it isn’t at all intuitive.

I’d also like to give a massive shoutout to u/yiotro on r/androiddev for compiling a list of extremely helpful bits of advice about verification. The most helpful ones for me were:

• Individual accounts are not allowed to use anything other than a home address
• Google doesn’t say this directly anywhere, but it is believed that account types must match, otherwise there will be problems.
• If the payment profile is linked to a developer account, it is impossible to unlink it. You can only create new account from scratch and transfer your apps there.

This process likely wouldn’t have had such a positive outcome if I hadn’t:

1. Had a career as an Android Developer, and therefore having any action taken against my account being a worst case scenario.
2. Had spare time and money to pay for the various services required to protect my privacy.

For a new Android engineer, or one with limited resources (e.g. a student), it seems impossible to actually publish apps earning any revenue without revealing all of their information to the world, forever. I understand the Google Play Store is primarily made for businesses (the verification process was painless when I did it for my employer), but you know how you get good Android engineers? By letting them experiment and try building their own apps, and maybe even making money from it.

If these rules had been in place back in 2016 when I published my first Android game, I’m not sure whether it would have ever been published. Without it, my career & life would have taken a different, likely much less fulfilling and enjoyable, path.

It’s worth mentioning if you don’t make any money from your apps only your country and name is revealed, but for some people even this can be too much. For me personally, I have no idea why a customer in another continent considering playing my free game needs the ability to visit my home address! I guarantee they’re not going to get any technical support on the doorstep…

All code in this article is available as a GitHub Gist.

Play Store Rating

Like a lot of people, I rely on an app’s Play Store rating as a rough indicator of quality / trustworthiness. Typically, anything below 4 stars needs a closer look, but above is probably fine. Despite this, the app I spend most of my time on was rated around 2.0! Time to fix that.

Why was the rating so low?

Historically, the app previously had a number of pretty severe problems. This included features not working, instability, unresponsive UI, etc. All of this resulted in an abysmal rating of 1.4 in February 2024.

Since the app typically received just 2 - 5 reviews a week, almost all were from unhappy customers!

By steadily working through hundreds of raised bugs, aggressively improving stability by fixing every identified crash (currently 99.97% crash-free users!), and constantly improving overall quality, this slowly started improving. 9 months later, the app had steadily increased to a rating of 2.0 in November 2024, primarily by reducing the quantity of 1-star reviews.

On Google Play Console, under Monitor and Improve -> Ratings and Reviews -> Ratings, the number of ratings and rating distribution can be seen.

Whilst this was a big improvement (the minimum is 1 star, so the number of non-1-star reviews was actually 4x higher!), it was nowhere near my acceptable level: 4.0+.

What happened to the rating?

Reducing the number of 1-star reviews helped, but you know what would help even more? A flood of 5-star reviews! Continuing to receive feedback from unhappy customers is expected, and appreciated, so long as the thousands of satisfied customers are heard too.

Looking at a chart of number of ratings over the past 3 months explains what happened. Instead of an occasional rating, literally hundreds of 4 and 5-star reviews flooded in, solving the problem within a couple of weeks:

With a regular release schedule, the per-version average rating can also be used to check which is responsible for the flood of reviews. It might be the version with at least 40x as many reviews as any other!

How was the rating improved?

With Google’s In-App Review Prompt library!

By prompting happy users with a very low-friction way to express their satisfaction, gathering high volumes of positive reviews was surprisingly painless. Google’s diagram describes the flow well:

The app itself has no direct control or observability of this rating prompt. Instead, it asks Google’s library to show the prompt if possible, and receives a callback when the prompt is finished. There are many, many, many reasons the callback might be called, all intentionally hidden from the app:

1. Rating prompt not shown because app was not installed from the store.
2. Rating prompt not shown because the user has already rated the app.
3. Rating prompt shown, user dismissed.
4. Rating prompt shown, user rated and submitted.

All of this is to ensure apps can’t reward (or punish!) the user based on their rating, or whether they rated at all. This is a good thing, and also means the app doesn’t need to worry about all the various outcomes!

Instead, the app just needs to ask to show the prompt, and receive the callback when it’s finished. This isn’t too complicated, but I created a ReviewPromptHandler wrapper to drastically simplify usage.

I defined a few specific triggers where the prompt would be shown if possible, specifically at moments where customers are engaged and have positive sentiment (e.g. clicking “Look at upgrade” after winning an auction).

Review Prompt Handler

So, why add complexity to a fairly simple to use library? Well, there are a few requirements in my use case to keep customers, Google, and other developers in the codebase happy!

Requirements

1. Simple to use: Any ViewModel that wants to display a review prompt shouldn’t need to keep track of the request status, handle errors etc. It should just be able to request the prompt’s appearance, and optionally pre-load.
2. Remotely configurable triggers: I want to be able to remotely control where this prompt appears. For example, I may want to disable it appearing after a successful bid due to some unrelated technical issue.
3. Triggered on button click or without specific interaction: The review prompt should be triggerable by a variety of trigger types^.
4. Able to remotely disable: In case there’s some catastrophic issue in Google’s library, I want the ability to ensure it isn’t relied upon at all if there’s no enabled triggers.
5. Requests aren’t spammed: Whilst Google doesn’t explicitly state quotas, they do say:
   1. “To provide a great user experience, Google Play enforces a time-bound quota on how often a user can be shown the review dialog.”
   2. “Because the quota is subject to change, it’s important to apply your own logic and target the best possible moment to request a review.”

^: Note that Google advises “you should not have a call-to-action option (such as a button) to trigger the API, as a user might have already hit their quota and the flow won’t be shown”, this is not applicable here since we’re using a callback to still perform the button’s usual function, not a dedicated CTA button!

Okay, pretty sensible requirements. How can they be all be implemented?

Handler flow

This is a quite technical diagram (it’s taken from my PR for the feature!), however it does show the main paths through the handler and prompt.

To clarify the 3 coloured sections:

• Yellow: The rest of the app, usually the calling ViewModel. It knows almost nothing, and just calls functions.
• Green: The ReviewPromptHandler.kt described in the next section. This abstracts all of the complexity away, and is the only class that interfaces with the in-app review prompt library.
• Blue: Google’s in-app review prompt library, where all decision-making is intentionally obfuscated from the calling codebase.

As shown, the review prompt handler is going to have 2 callable functions (ignoring any initialisation), where ReviewPromptTrigger is a simple enum:

fun prepareReviewPrompt(trigger: ReviewPromptTrigger)
fun showReviewPrompt(trigger: ReviewPromptTrigger, callback: () -> Unit = {})

Handler code

The full code is available as a GitHub Gist, read on for an explanation.

Initialisation

Unfortunately, the library requires a Context to initialise (I used Application), and an Activity to display the prompt (I used my MainActivity).

This means a bit of non-ideal boilerplate and references to Activity:

@Singleton
class ReviewPromptHandler @Inject constructor(
    application: Application,
    private val remoteConfigManager: RemoteConfigManager
) {
    private val reviewManager = ReviewManagerFactory.create(application)
    private var activity: Activity? = null
    ...
    fun setActivity(activity: Activity) {
      this.activity = activity
    }

Remote triggers

As mentioned, I want to be able to remotely configure my triggers. To implement this, I have a local enum of possible trigger points:

enum class ReviewPromptTrigger(val remoteName: String) {
    BID_MADE("BID_MADE"),
    BUN_PURCHASED("BUN_PURCHASED"),
    TICKET_PURCHASED("TICKET_PURCHASED")
}

Then, I’m using Firebase Remote Config (any other remote value fetcher is fine) with a comma-separated review_prompt_triggers (e.g. BID_MADE,TICKET_PURCHASED). By checking the passed ReviewPromptTrigger is in the list of enabled triggers, remote control over the prompt is supported.

Additionally, I only want to prompt for the same trigger once per session, so I have a list of triggers that have fired.

private val triggersThisSession = mutableListOf<ReviewPromptTrigger>()

private fun shouldShow(trigger: ReviewPromptTrigger): Boolean {
    if (triggersThisSession.contains(trigger)) {
        return false
    }
    return remoteConfigManager.getString(review_prompt_triggers)
        .split(",")
        .map { it.trim() }
        .contains(trigger.remoteName)
}

Pre-caching review prompt

Google’s advice on when to prepare a review prompt object is a little vague. Essentially you should request it before you ask the user, but it expires eventually:

Note: The ReviewInfo object is only valid for a limited amount of time. Your app should request a ReviewInfo object ahead of time (pre-cache) but only once you are certain that your app will launch the in-app review flow.

In my scenario, I pre-cache when the checkout flow starts, since this will typically result in a successful checkout (where the prompt will be used).

Using our shouldShow function from earlier, we request a review flow object and store the result in memory:

fun prepareReviewPrompt(trigger: ReviewPromptTrigger) {
    preparedReviewPrompt = null
    if (!shouldShow(trigger)) {
        return
    }

    reviewManager.requestReviewFlow().addOnCompleteListener { request ->
        if (request.isSuccessful) {
            preparedReviewPrompt = request.result
        }
    }
}

Displaying review prompt

Finally, we can put this all together and actually show a prompt! I also decided to support the scenario where the caller didn’t have an opportunity to call prepareReviewPrompt.

This means there’s 2 flows (one with pre-caching (launchReviewPrompt), one without (prepareAndLaunchReviewPrompt)). If there’s no pre-caching, we fetch the review prompt object now instead, then display it once fetched. The trigger should also be added to the in-memory blacklist to avoid excessive requests.

We also must call the passed in callback no matter what happens, otherwise the user will get stuck on their current screen!

fun showReviewPrompt(trigger: ReviewPromptTrigger, callback: () -> Unit = {}) {
    val activity = activity
    if (!shouldShow(trigger) || activity == null) {
        callback()
        return
    }

    triggersThisSession.add(trigger)
    preparedReviewPrompt?.let {
        launchReviewPrompt(activity, it, callback)
    } ?: prepareAndLaunchReviewPrompt(activity, callback)
}

private fun prepareAndLaunchReviewPrompt(activity: Activity, callback: () -> Unit) {
    reviewManager.requestReviewFlow().addOnCompleteListener { request ->
        if (request.isSuccessful) {
            launchReviewPrompt(activity, request.result, callback)
        } else {
            Log.i("ReviewPromptHandler", "Failed to prepareAndLaunchReviewPrompt")
            callback()
        }
    }
}

private fun launchReviewPrompt(activity: Activity, reviewInfo: ReviewInfo, callback: () -> Unit) {
    reviewManager.launchReviewFlow(activity, reviewInfo).addOnCompleteListener {
        if (!it.isSuccessful) {
            Log.i("ReviewPromptHandler", "Failed to launchReviewPrompt")
        }
        callback()
    }
}

Calling the handler

Finally, our handler is ready to use!

Assuming ReviewPromptHandler has been injected or initialised, the TicketPurchaseViewModel prepares the prompt when checkout flow starts:

reviewPromptHandler.prepareReviewPrompt(ReviewPromptTrigger.TICKET_PURCHASED)

Then, when a prompt should be shown if possible (e.g. on button click), the Fragment passes in the normal post-button press action into the ViewModel:

val navToBookings: () -> Unit = {
    findNavController().navigate(TicketFragmentDirections.toBookings())
}
...
when (event) {
    is TicketConfirmationEvents.OnLookAtMyTicket -> {
        viewModel.onLookAtMyTicket(navToBookings)
    }

Where the ViewModel’s onLookAtMyTicket just calls ReviewPromptHandler with the correct ReviewPromptTrigger:

fun onLookAtMyTicket(navigation: () -> Unit) {
    reviewPromptHandler.showReviewPrompt(ReviewPromptTrigger.TICKET_PURCHASED, navigation)
}

How to test

Similar to testing whilst implementing Google’s force upgrade library, this can’t be tested easily on your local machine, and the app must be installed via the Google Play Store.

Thankfully, it’s far easier to test than force upgrade! Note that due to the “black box” of the library, you might not see the prompt despite following all the steps. Additionally, once you’ve seen one prompt, you might not see any others for a few weeks.

1. Prepare a build, and upload it to Google Play Console internal app sharing.
2. Uninstall your app from your device.
3. Add your device’s primary email address to the “In-app review testing” list on Google Play Console.
4. Open Google Play Console’s internal app sharing link on your device.
5. Install the app from this link.
6. Click your triggers, and make sure your callback actually happens (far more important than the review prompt appearing).

You’ll see slightly different messages when testing via internal app sharing vs a production app:

Internal app sharing	Production

Note: The oddly zoomed-in app icon happens on my device for all prod apps, presumably it’s a Google / Samsung issue!

Extra notes

Monitoring store rating

To keep an eye on my app’s rating throughout this process, I checked the Google Play Console once or twice a day.

Whilst there is a Google Play Console app (which is rated 2.8!), and it has attractive data visualisations, the data updates are painfully slow. The data was typically 12 hours behind Google Play Console web, which is itself 12-24 hours behind!

The main number is the “Default Google Play rating” on the “Ratings” screen. This will show your overall Google Play rating, and should be treated as your source of truth. However, each individual device will see a slightly different score (due to OS, device type, etc), so there’ll be a slight spread around this value.

Currently, the Google Play Console app is the only way to see charts of Google Play rating and many other KPIs (Key Performance Indicators) over time:

Overview	Specific metric	KPI list

Speed of increase

Whilst Google Play Console does have an “Average rating over time” chart, this won’t match up with your displayed store rating due to how Google weights reviews based on time.

As such, I had to manually keep a note each day of the rating! Once the version with review prompting was rolled out to 100% (12th December), the rating improved by 0.1 to 0.5 per day(!):

• 19/11/24: 2.088
• 09/12/24: 2.187
• 11/12/24: 2.249
• 12/12/24: 2.327
• 13/12/24: 2.719
• 14/12/24: 2.819
• 15/12/24: 3.335
• 16/12/24: 3.796
• 17/12/24: 3.922
• 18/12/24: 4.082
• 19/12/24: 4.145
• 20/12/24: 4.317
• 21/12/24: 4.390
• 22/12/24: 4.498
• 23/12/24: 4.589
• 24/12/24: 4.638
• 25/12/24: 4.667 🎄

An increase from 2.2 to 4.7 in exactly 2 weeks is absolutely amazing (and an excellent Christmas present), and far exceeded my expectations for this project!

Cached rating

A rapid rise in rating for a well-established app is pretty unusual, so other services will take multiple weeks or months to notice this rating has changed.

For example, whilst the store itself currently shows a rating of 4.7 for Seatfrog, Google Search results show a far lower rating from around July!

Conclusion

Adding an in-app review rating prompt had an unbelievably rapid improvement to my app’s rating.

I’d absolutely recommend adding a prompt to pretty much any app, with the resulting rating score essentially depending on how well you pick your triggers. If you prompt whilst the user is frustrated, putting a pop-up in their face is going to make things even worse!

I see in-app review prompts pretty regularly for other apps, however they are usually implemented in a seemingly untargeted way. For example, 2 I saw recently were obviously triggered by the number of times the app has been opened, when I didn’t have a particularly positive sentiment and was just trying to complete a task. As such, I dismissed instead of rating.

Whilst I did begin working on an “after X days” prompt, I eventually decided a smarter implementation was prompting less often but in a more targeted way. It seems to have been the correct call, with almost every review being 5-star.

As I write the first draft of this article, the app is sitting around 4.3, and still rising by 0.1 - 0.2 per day, expected to end up at 4.8 (average rating is 4.825). The next rating goal? 4.9!

One last time, all code used is available on GitHub: https://gist.github.com/JakeSteam/c09c7bd980095a8a26649419d49d393e

All code in this article is available in a WordNetToSQLite repo, as is the final words.db database (license).

Objective

For an upcoming word game app, I needed a dictionary of words. I wanted to know the type of word (noun / verb / adjective / adverb), and a definition for each. Plus, it should only include sensible words (e.g. no proper nouns, acronyms, or profanity).

I decided to prefill a SQLite database and ship it with my app, since I can easily update it by just shipping a new database (or even remotely with SQL!). Android also has good support for retrieving the data from SQLite.

However, finding a suitable list of words was tricky! I found plenty of sources containing just words, or with no information on source or licensing. Eventually, I discovered Princeton University’s WordNet exists, and luckily it’s free to use and has a very liberal license. There’s also a more up to date fork (2024 instead of 2006).

However, it contains a lot of unneeded information and complexity, and is 33MB+ uncompressed. Time to get filtering…

Running script

If you wish to recreate words.db from scratch, or customise the results, you can:

1. Obtain a WordNet format database.
   • I used a regularly updated fork (2024 edition, WNDB format)
   • You can also use the original WordNet files from 2006 (WNdb-3.0.tar.gz from WordNet)
2. Extract your download, and place the data.x files in /wordnet-data/.
3. Run py wordnet-to-sqlite.py.
4. In a minute, you’ll have a word database!

Out of the box, the script takes ~60 seconds to run. This slightly slow speed is an intentional trade-off in exchange for having full control over the language filter (see profanity removal).

Notes on results

The database contains over 71k word & word type combinations, each with a definition. I use the open source DB Browser for SQLite to browse the results, looking something like this:

Schema definition

Only one definition per word for the same type is used (e.g. with the noun article, but not the verb):

• word:
  • Any words with uppercase letters (e.g. proper nouns) are removed.
  • Any 1 character words are removed.
  • Any words with numbers are removed.
  • Any words with other characters (apostrophes, spaces) are removed.
  • Most profane words (626) are removed.
  • Roman numerals are removed (e.g. XVII).
• type:
  • Always adjective / adverb / noun / verb.
• definition:
  • Definition of the word, uses the first definition found.
  • Most profane definitions (1124) are replaced with empty space.
  • May contain bracketed usage information, e.g. (dated).
  • May contain special characters like ', $, !, <, [, etc.

Notes on code

Whilst wordnet-to-sqlite.py is under 100 lines of not-very-good Python and doesn’t do anything too crazy, I’ll briefly walk through how it works.

Raw data

The raw data in WordNet databases looks like this (unknown is the only valid noun to extract, with a single definition):

08632096 15 n 03 unknown 0 unknown_region 0 terra_incognita 0 001 @ 08630985 n 0000 | an unknown and unexplored region; "they came like angels out the unknown"

Further notes on WordNet’s data files are here, this Python script just does a “dumb” parse then filters out numerical data and invalid words (spaces, capitalised letters, Roman numerals etc).

Process

1. For each word type file (data.noun, data.adj, etc), pass it to parse_file.
2. Loop through every line in this file, primarily using split / range to fetch as many words as are defined, without taking the 0 and other non-word data.
3. Check each of these words is “valid”, specifically that it’s lowercase letters only (no symbols / spaces), isn’t a Roman numeral (by matching the word & description), and isn’t a profane word.
4. If the word is valid, add it to the dictionary so long as it isn’t already defined for the current word type. For example, a word might be used as a noun and an adjective.
5. Finally, output all these word, type, and definition rows into a SQLite database we prepared earlier.

Luckily, as Python is a very readable language, function definitions almost read like sentences:

def is_valid_word(word, definition):
    return (
        word.islower() and
        word.isalpha() and
        len(word) > 1 and
        not is_roman_numeral(word, definition) and
        not is_profanity(word)
    )

Profanity removal

Since this dictionary is for a child-friendly game, profane words should be removed if possible. Players are spelling the words themselves, so I don’t need to filter too aggressively, but slurs should never be possible.

The eventual solution is in /profanity/, where wordlist.json is the words to remove, manually-removed.txt & manually-added.txt are the words I’ve manually removed from / added to the wordlist, and log.txt is every removed word & definition.

Choice of package

I tried out quite a few Python packages for filtering out the profane words, with pretty poor results overall. They were generally far too simple, required building a whole AI model, were intended for machine learning tasks, or seemed entirely abandoned / non-functional.

Eventually, I used better_profanity 0.6.1 for filtering (0.7.0 has performance issues), and whilst it was fast, it missed very obvious explicit words, whilst triggering hundreds of false positives. However, this was the best package so far despite being semi-abandoned, so I used it for most of the project (before rolling my own).

Word list

With a 4 year old wordlist, missing quite common slurs wasn’t too surprising. As such, I tried using a much more comprehensive wordlist (2823 words vs better profanity’s 835). At this point, the library’s “fuzzy” matching was far too fuzzy, and half the words had their definitions removed!

After logging all the removed words and definitions, I also noticed this list was quite over-zealous. I ended up manually removing 123 words (see whitelisted.txt), since words like “illegal”, “kicking”, “commie” are absolutely fine to all but the most prudish people. Removing false positives took the total number of profane removals from 3,368 to 1,750, all of which seem sensible.

Whilst I now had a good word list, at this point I gave up using libraries, and decided to just solve it myself. It’s fine if the solution is slow and inefficient, so long as the output is correct.

Using regexes

I implemented a solution that just checks every word (& word of definition) against a combined regex of every profane word. Yes, this is a bit slow and naive, but it finally gives correct results!

with open(wordlist_path, 'r', encoding='utf-8') as f:
    profane_words = set(json.load(f))
combined_profanity_regex = re.compile(r'\b(?:' + '|'.join(re.escape(word) for word in profane_words) + r')\b', re.IGNORECASE)

The script takes about a minute to parse the 161,705 word candidates, pull out 71,361 acceptable words, and store them in the database. Fast enough for a rarely run task.

Optimisation

A few steps are taken to improve performance:

• executemany is used to insert all the database rows at once.
• A combined (very long) regex is used since it’s far faster than checking a word against 2700 regexes.
• A set is used for the word list, so words can be quickly checked against it.
• Only one definition for each word & type is included, as this reduces the database size from 7.2MB to 5.1MB.

Conclusion

The approach taken to generate the database had quite a lot of trial and error. Multiple times I thought I was “done”, then I’d check the database or raw data and discover I was incorrectly including or excluding data!

SQLite Browser was extremely useful during this process, as the near-instant filtering helped me check profane words weren’t slipping through. It also helped me catch a few times when technical data would leak into the definitions.

I’ll absolutely tweak this script a bit as I go forward (I’ve implemented all my initial ideas since starting the article!) and my requirements change, but it’s good enough for a starting point. Specifically, next steps are probably:

• Try the WordNet 3.1 database instead of 3.0, and see if there’s any noticeable differences (there’s no release notes!) Tried, not much change
• Use an open source fork, since it has yearly updates so should be higher quality than WordNet’s 2006 data. Done!
• Replace the current profanity library, since it takes far longer than the rest of the process, and pointlessly checks letter replacements (e.g. h3ll0) despite knowing my words are all lowercase letters. Done!
• Use the word + type combo as a composite primary key on the database, and ensure querying it is as efficient as possible. Done! Increased database size by ~20%, so will see if it’s necessary.

The (mostly) full list of octocats is available in GitHub’s “Octodex”, and they can to be used to refer to GitHub or as a personal avatar picture, but (unsurprisingly) not for commercial purposes or physical products. They’re very, very cute, and they definitely deserve more visibility. Maybe this article will help!

Who is Mona the Octocat?

Mona (Lisa) the Octocat’s story has been described in absorbing, first-hand detail by Cameron McEfee, the man who has created more octocats than anyone, including the first 13 adaptations! There’s also an entire art book and stickers.

To summarise, in 2011 illustrator Cameron McEfee was tasked with adapting GitHub’s existing stock image mascot “Octopuss” (picked as a reference to git’s “octopus merge”) for use in GitHub’s error pages, and he gave it costumes and personality.

These were so popular that “50% of GitHub’s lifetime Twitter traffic was generated by my first week’s work” (source), very impressive for an error page illustration! This then led to many, many, many more adaptations, and the creation of the Octodex.

Since then, many artists have created octocats in evolving styles, and it continues to feature prominently in most of GitHub’s communications. Some Octocat descriptions are only possible due to information from former employees, thanks!

Standard Octocats

Classic Octocats

First up, the earlier Octocat variants. They are still very clearly variants on the original Octocat, and typically have a 2D, face-on appearance, with limited details and a recognisable stance. Whilst some have a modified position or other characters, they’re all easily identifiable as Octocat.

The majority of Pop Culture Octocats and around half of the Real People Octocats are from this fruitful period.

This era lasted from early 2011 to late 2012.

#1: Original Simon Oxley (2011-03-23) The Octocat that started it all, originally named "Octopuss"!	#2: Class Act Cameron McEfee (2011-03-28) Used as promotional material for a party. Was also used to highlight PSD diffing.	#4: Puppeteer Cameron McEfee (2011-03-30) Most likely used for something related to the Puppeteer web automation tool.
#5: Scottocat Cameron McEfee (2011-03-30) This is most likely Scott Chacon, a GitHub co-founder with a similar profile picture.	#6: Benevocats Cameron McEfee (2011-03-31) Presumably a play on "benevolent", used for GitHub's Global Indigenous CoB.	#7: Forktocat Cameron McEfee (2011-03-31) Included in early onboarding docs, a reference to "Fork"ing a repository. Reused for Neurocats Employee Resource Group.
#8: Repo Cameron McEfee (2011-03-31) Included in early onboarding docs, a reference to repositories.	#9: Setuptocat Cameron McEfee (2011-03-31) Included in early onboarding docs.	#10: Socialite Cameron McEfee (2011-03-31) Included in early onboarding docs, specifically around social features.
#11: Drupalcat Cameron McEfee (2011-04-01) A reference to the Drupal CMS.	#12: Pythocat Cameron McEfee (2011-04-01) A reference to the Python language, used for Python related posts.	#14: Bouncer Cameron McEfee (2011-04-03) Most likely used for real life merchandise for (real world!) office security.
#15: Octonaut Cameron McEfee (2011-04-04) A play on "Astronaut".	#19: Swagtocat Cameron McEfee (2011-04-09) A reference to free items from the CodeConf 2011 event.	#23: Inspectocat Jason Costello (2011-04-13) Likely a reference to a browser's "Inspect Element" feature. This was the first octocat not by Cameron McEfee!
#25: Agendacat Jason Costello (2011-04-15) An agenda, presumably also used in relation to CodeConf 2011.	#29: Total Eclipse of the Octocat Cameron McEfee (2011-04-19) Created for an Eclipse IDE related article, with a pun on the 1983 song "Total Eclipse of the Heart".	#30: Constructocat Jason Costello (2011-05-01) Probably used for "Under Construction" screen(s).
#31: Collabocats Jason Costello (2011-05-02) A play on the word "collaboration".	#32: Supportcat Jason Costello (2011-05-03) Presumably used in relation to help / support.	#33: Cherryontop-o-cat Jason Costello (2011-05-04) Unknown
#36: Jenktocat Cameron McEfee (2011-05-12) A reference to the Jenkins CI system.	#37: Poptocat Cameron McEfee (2011-05-13) Likely a play on "Pop", since there is also a "Momtocat". Used for Father's Day in June.	#38: Scarletteocat Jordan McCullough (2011-05-14) Created by a former employee for his daughter Scarlette.
#40: Dodge, Duck, Dip, Dive, Dodgetocat Cameron McEfee (2011-05-16) A reference to The Five D's of Dodgeball from the film Dodgeball. Used for inter-company dodgeball tournaments.	#41: Not Octocat Cameron McEfee (2011-06-10) Translates from French into "this is not an octopus cat".	#43: Bear Cavalry Cameron McEfee (2011-07-02) A reference to the "Bear Cavalry" meme popular at the time.
#44: Spectrocat Cameron McEfee (2011-07-02) Unknown, possibly just a play on "Spectre".	#47: Shoptocat Cameron McEfee (2011-07-05) Themed after an employee who handled merchandise.	#48: Oktobercat Cameron McEfee (2011-07-06) A reference to Oktoberfest.
#51: Hipster Partycat Jina Anne (2011-07-09) Likely used for "a company party invitation" as mentioned on the creator's CV.	#53: Father Timeout Jason Costello (2011-10-02) Used to "soften errors with cuteness". A play on "Father Time".	#54: Grim Repo Cameron McEfee (2011-10-27) A play on "Grim Reaper", created purely for the excellent pun.
#55: Octocat De Los Muertos Cameron McEfee (2011-10-28) A reference to the Mexican holiday Dia de los Muertos (Day of the Dead).	#61: Thanktocat Cameron McEfee (2011-11-23) A reference to the holiday Thanksgiving.	#62: Ordered Listocat Cameron McEfee (2011-12-05) Used to announce GitHub's acquisition of "Ordered List".
#63: Saint Nicktocat Cameron McEfee (2011-12-05) A play on Saint Nick / Santa Claus.	#66: Dojocat Cameron McEfee (2012-01-18) Made for stickers at GitHub's "CoderDojo" sessions.	#70: Codercat Cameron McEfee (2012-02-15) Represents a generic user, in the likeness of an employee at the time.
#71: Electrocat Cameron McEfee (2012-02-29) Used for GitHub's "Security and IT" jobs, possibly something to do with making connections.	#72: Snow Octocat Cameron McEfee (2012-03-05) A reference to Mac OS X Snow Leopard.	#73: Momtocat Tony Jaramillo (2012-05-13) A reference to Mom / Mum, used for Mother's day around this time.
#75: Red Polo Cameron McEfee (2012-06-21) A reference to Scott Guthrie, a senior leader at Microsoft who often wears a red polo. Unknown purpose.	#78: Droidtocat Tony Jaramillo (2012-07-09) Used for the first GitHub Android app release in July 2012.	#82: Deckfailcat Matt Graham (2012-08-02) Something related to the Speaker Deck software, possibly used as their 404 page.
#119: Private Investocat James Kang (2015-01-27) Presumably a reference to private investigators, often used for security related articles. Also used on the original GitHub Security Bounty page.

Modern Octocats

After the “Classic” octocats and their relatively static appearances came the “Modern” octocats, with each clearly being a distinct piece of art, often with a unique position. Although Tony Jaramillo created the first of this era (Dodgetocat v2), it’s James Kang who really churned out creations!

This era lasted from late 2012 to late 2014.

#85: Dodgetocat v2 Tony Jaramillo (2012-10-25) Another dodgeball cat, for another dodgeball event.	#90: Skitchtocat Jon Rohan (2012-12-15) Presumably a reference to the screen annotating software Skitch (now owned by Evernote, previously used often by GitHub), as evidenced by the octocat being made up of arrow annotations.	#91: Motherhubbertocat James Kang (2013-01-27) Possibly a reference to an internal piece of software.
#92: Robotocat James Kang (2013-01-28) A robotic octocat, unknown purpose.	#94: Professortocat v2 James Kang (2013-02-11) A stereotypical professor with an apple and cane, used for GitHub Education originally, and other training related posts.	#95: Kimonotocat James Kang (2013-02-27) A reference to the Japanese clothing Kimono, possibly used for a Heroku-related event.
#96: Mardigrastocat James Kang (2013-02-27) A reference to Mardi Gras, occurring a few days after this released.	#97: Poptocat v2 Tony Jaramillo (2013-04-19) An iteration on the earlier "Pop" octocat, possibly for Father's Day in a couple of months.	#101: Femalecodertocat James Kang (2013-07-01) A female version of "Codercat".
#102: Octoliberty James Kang (2013-07-05) A reference to the Statue of Liberty.	#104: Labtocat Joao Ribeiro (2013-08-18) Possibly a reference to some sort of "feature lab", unknown.	#106: Steroidtocat James Kang (2013-12-13) A reference to steroids, possibly a replacement for "Bouncer".
#107: Yaktocat James Kang (2013-12-13) Created for a Thai conference sponsorship, probably the Thai traditional "Khon", especially this image.	#112: Saritocat Joao Ribeiro (2014-04-30) Created for an Indian conference sponsorship, and often used for India-related posts.	#113: Luchadortocat James Kang & Joao Ribeiro (2014-09-26) Created for a conference sponsership (presumably Mexican), a reference to Mexican wrestlers (Luchadors).
#114: Saketocat James Kang (2014-09-27) Created for a Japanese conference sponsorship, a reference to Japanese rice wine sake.	#115: Minertocat James Kang (2014-09-29) An octocat panning for gold, unknown usage.

Extra Modern Octocats

Towards the end of 2014, something unusual happened to Octocat! It gained more detailed features, distinctive expressions, eyes, and other facial features, and it is clearly not a human. The limbs seem much “stretchier”, and the character is in much more active poses.

Many of these images were used for temporary landing pages, promotional material, and other short-lived content. As such, finding the actual source or reason behind their creation can be tricky!

This era started in late 2014 (primarily due to Joao Ribeiro’s work, his many years of Octocat-related work are here) and is still dominant, with minor changes along the way. Internally this is called “Octocat 2.0” style.

#116: Jetpacktocat Tony Jaramillo (2014-11-11) Created for the launch for GitHub Enterprise, now used for GitHub's integrations organisation.	#120: Filmtocat James Kang (2015-04-29) Created as a reference to GitHub's internal video team, now used for GitHub's "Marketing and Communications" jobs.	#121: Welcometocat Tony Jaramillo & Joao Ribeiro & Joel Glovier (2015-11-16) Used for welcome emails, and similar introductory / congulatory material. There are multiple designs.
#122: Inflatocat Ruby Jazz (2016-09-21) A reference to inflatable pool toys, for unknown use.	#124: Skatetocat Suzie Jurado (2016-11-16) Unknown use, reference to skateboarding	#128: Dinotocat Haley Carroll & Kim Estoesta (2017-05-15) Created for National Dinosaur Day.
#130: Saint Nictocat (v2) Haley Carroll (2017-12-18) A reference to Saint Nicholas, for Christmas a week later!	#132: Justicetocat Haley Carroll (2018-03-01) Used for GitHub's "Corporate, External, and Legal Affairs" jobs, originally created for Women's History Month.	#133: Snowtocat Haley Carroll (2018-03-20) Reference to skiing, used for social media post.
#134: Tentocat Haley Carroll & Joao Ribeiro & Cameron Foxly (2018-04-10) Used to celebrate 10 years since GitHub's official launch.	#135: Vinyltocat Joao Ribeiro & Suzie Jurado (2018-04-21) Unknown use, reference to vinyl records.	#136: Scubatocat Cameron Foxly (2018-06-05) Reference to National Scuba Month.
#138: Surftocat James Kang (2018-06-14) Reference to surfing, unknown purpose.	#140: Umbrellatocat Ruby Jazz (2018-09-13) Used for a GitHub Field Day event.	#141: Sentrytocat Cameron McEfee (2018-10-09) Used for a GitHub / Sentry partnership post.
#144: Fintechtocat Cecilio Ruiz (2019-06-18) A reference to fintech (Financial technology), used to announce partnership with Fintech Open Source Foundation.	#150: Manufacturetocat Haley Carroll (2021-03-04) Unknown use, reference to manufacturing.	#152: Yogitocat Joao Ribeiro (2021-04-06) Used to celebrate the launch for GitHub India.
#154: Godotocat Joao Ribeiro & Lee Reilly (2023-03-21) Used to announce a Godot 4.0 Release Party.	#156: Sponsortocat Cameron Foxly (2024-12-12) Presumably used in relation to the GitHub Sponsors program.	#157: Universetocat Cameron Foxly (2024-12-12) Used for GitHub Universe 2024, with Mona the Octocat accompanied by Copilot (AI). The wings are code brackets, and the icon on her head is a commit, as discussed in an accompanying video.
#158: Securityknightocat Cameron Foxly (2024-12-17) Unknown, presumably used in relation to some sort of GitHub verification / security, perhaps Advanced Security due to similar "checkmark shield" designs (also note Copilot on the belt, and commit / fork icons on armour).	#159: Securitocat Cameron Foxly (2025-01-17) Used for the "EkoParty 2024" event.	#162: Bombacat kuuchen (2026-01-14) An octocat performing a "Bomba" dance, unknown usage.

Animated Octocats

#46: Nyantocat Cameron McEfee (2011-07-04) A recreation of the Nyan Cat meme.	#99: Daftpunktocat-Guy James Kang (2013-06-10) A reference to Guy in Daft Punk.	#100: Daftpunktocat-Thomas James Kang (2013-06-10) A reference to Thomas in Daft Punk.
#105: Mummytocat Tony Jaramillo (2013-10-31) A mummy, used in a gaming post but originally created for halloween.	#108: Maxtocat James Kang (2013-12-25) A reference to Christmas (released on Christmas day!), unknown purpose.	#109: Grinchtocat Tony Jaramillo (2013-12-26) A reference to the Grinch character & Christmas (released on Boxing day!), unknown purpose.
#110: Carlostocat James Kang (2014-01-01) A reference to the baby Carlos from The Hangover film, possibly due to partying on New Year's Eve the day before!	#117: Gobble-o-tron Tony Jaramillo & Joao Ribeiro (2014-11-27) A reference to Thanksgiving (a Turkey's noise is often described as "gobble gobble").	#137: Hulatocat Haley Carroll (2018-06-11) A reference to the Hawaiian dance Hula, for unknown purpose. Possibly just social media post.
#153: NUXtocat Cameron Foxly (2021-07-19) A reference to "New User Experience" (NUX), hence the capitalisation, not the framework "nuxt"! Used for sign-up flow.

Pop Culture Octocats

A surprising number of the octocats are drawn in the style of a TV show or other pop culture characters!

#3: Octobi Wan Catnobi Cameron McEfee (2011-03-29) A reference to Obi-Wan Kenobi from Star Wars, used on 404 page. The first public variation (along with this Wile E. Coyote reference)!	#16: Trekkie Cameron McEfee (2011-04-05) A reference to Geordi La Forge from Star Trek.	#21: Spocktocat Cameron McEfee (2011-04-11) A reference to Spock from Star Trek.
#22: Jean-Luc Picat Cameron McEfee (2011-04-12) A reference to Jean-Luc Picard from Star Trek.	#24: Ironcat Cameron McEfee (2011-04-14) A reference to Iron Man.	#26: Octoclark Kentocat Cameron McEfee (2011-04-16) A reference to Superman AKA Clark Kent.
#27: Okal-Eltocat Cameron McEfee (2011-04-17) A reference to Superman AKA Kal-El.	#28: Blinktocat, Pinktocat, Inktocat, and Clyde Cameron McEfee (2011-04-18) A reference to the 4 ghosts (Blinky, Pinky, Inky, Clyde) in Pac Man.	#34: Chellocat Cameron McEfee (2011-05-10) A reference to Chell from Portal.
#35: X-tocat Cameron McEfee (2011-05-11) A reference to Wolverine from X-Men.	#42: Andycat Jordan McCullough (2011-07-01) A reference to the "Shot Marilyns" series of paintings by Andy Warhol.	#50: Riddlocat Cameron McEfee (2011-07-08) A reference to Riddler from Batman.
#52: Where's Waldocat Jason Costello (2011-10-01) A reference to the Where's Wally / Waldo series.	#56: Baracktocat Cameron McEfee (2011-10-29) A reference to Barack Obama's "Yes We Can" slogan.	#57: Octotron Diana Mounter (2011-10-29) A reference to the Tron series of films.
#58: Plumber Cameron McEfee (2011-11-04) A reference to Mario.	#59: Linktocat Cameron McEfee (2011-11-14) A reference to Link.	#60: Megacat Jason Costello (2011-11-18) A reference to Mega Man.
#67: Doctocat Brown Jon Rohan (2012-01-19) A reference to Doc Brown from Back to the Future.	#68: Adventure Cat Jon Rohan (2012-01-22) A reference to Finn from Adventure Time.	#69: Strongbadtocat Cameron McEfee (2012-02-13) A reference to Strong Bad from Homestar Runner.
#74: 20% Cooler Octocat Cameron McEfee (2012-06-13) A reference to Rainbow Dash from My Little Pony.	#76: Heisencat Jon Rohan (2012-07-03) A reference to Heisenberg (aka Walter White) from Breaking Bad.	#79: Minion Nick Hengeveld (2012-07-11) A reference to Minions from Despicable Me.
#80: Homercat Nick Hengeveld (2012-07-13) A reference to Homer Simpson from The Simpsons.	#81: Murakamicat Billy Roh (2012-07-31) A reference to Mr. DOB by Takashi Murakami.	#83: Pusheencat Billy Roh (2012-08-13) A reference to Pusheen.
#84: Stormtroopocat James Kang (2012-10-15) Based on Star Wars' Stormtrooper, created when "[GitHub] asked James to design the Octocat he thought the Octodex was missing most and he completely dazzled [GitHub] with his Stormtroopocat"	#86: Megacat v2 James Kang (2012-10-25) A reference to Mega Man.	#87: Spidertocat James Kang (2012-10-25) A reference to Spider-Man.
#88: Dr. Octocat James Kang (2012-10-26) A reference to Doctor Octopus from Spider-Man	#89: Gangnamtocat James Kang (2012-10-31) A reference to Gangnam Style by Psy.	#103: Dunetocat Joao Ribeiro (2013-08-18) A reference to Dune.
#111: Topguntocat Lee Reilly & Tony Jaramillo (2014-04-11) Created as the logo for an internal app, possibly related to video streaming. A reference to Top Gun.	#123: Bewitchedtocat Haley Carroll (2016-10-31) A reference to the sitcom Bewitched, used for Halloween themed posts.	#139: Boxertocat Ruby Jazz (2018-07-08) Used for GitHub's 2017 GDC afterparty, likely a reference to Street Fighter's Ryu.
#142: Filmtocats Haley Carroll (2018-12-20) A reference to GitHub's internal video team.	#151: Mona the Rivetertocat Joao Ribeiro (2021-03-08) A reference to Rosie the Riveter.

Real People Octocats

Some are based on real people, a mixture of historical figures, current celebrities, and even GitHub employees.

#13: Founding Father Cameron McEfee (2011-04-02) A reference to the USA Founding Father George Washington.	#17: Monroe Cameron McEfee (2011-04-06) A reference to Marilyn Monroe, see also "Andycat".	#20: Wilson Cameron McEfee (2011-04-10) A reference to Brian Wilson, a baseball player.
#45: Octdrey Catburn Cameron McEfee (2011-07-03) A reference to Audrey Hepburn, an actress. A similar image was used for a charity OctoGala.	#49: Visionary Cameron McEfee (2011-07-07) A reference to Steve Jobs, former Apple CEO.	#65: Defunktocat Jason Costello (2012-01-13) Styled after GitHub Co-founder Chris Wanstrath (aka defunkt).
#93: Goretocat James Kang (2013-02-03) A reference to Frank Gore, american football player.	#98: Founding Father v2 James Kang (2013-05-24) A reference to the USA Founding Father George Washington.	#118: Gracehoppertocat James Kang (2014-12-03) A reference to Grace Hopper, an early computer scientist. Also previously used for Octovets CoB.
#125: McEfeeline Tony Jaramillo (2017-01-27) A reference to Cameron McEfee who made an overwhelmingly number of early Octocats, and "had the foresight to dress up our feline cephlapod for the first time".	#127: Benjamin Bannekat Haley Carroll & Tony Jaramillo & Joao Ribeiro (2017-02-28) A reference to Benjamin Banneker, a mathematician, created for unknown purposes.	#129: Mona Lovelace Haley Carroll (2017-12-12) A reference to Ada Lovelace (Mona is Octocat's nickname), created for her 202nd birthday.
#126: Catstello Tony Jaramillo (2017-01-28) A reference to "Jason Costello", who created a few Octocats! Apparently "Originally bred in the hills of New Jersey, it has migrated west spreading good vibes, stunning design, and an unapologetic bias towards proper typography".	#143: Brennatocat Joao Ribeiro (2019-03-29) Styled after a former GitHub employee.

Non-Standard Octocats

Not Octocats

Some of the octocats… are not octocats! They’re robots, clouds, crabs, and dogs.

#18: Hubot Cameron McEfee (2011-04-07) Hubot is GitHub's mostly internal chatbot platform that enables automations like translating texts. Used for all bot-related content, and in animations.	#39: Cloud Cameron McEfee (2011-05-15) A reference to GitHub being a "cloud" service.	#64: Nemesis Cameron McEfee (2012-01-09) A reference to BitBucket ("Herme T. Crab, codes not socially, but alone"), only ever used in a minigame mockup.
#77: Octofez Nick Hengeveld (2012-07-04) A portrait of the artist's dog.

Series Octocats

Finally, a few octocats are part of a series. These are used for internal Employee Resource Groups.

#131: Blacktocats by Cameron Foxly (2018-02-21)

Created for GitHub’s Black Employee Resource Group.

#145: Adacats by Cameron Foxly (2020-01-08)

Created for GitHub’s Gender Minorities Employee Resource Group.

#146: Octogatos by Cameron Foxly (2020-02-24)

Created for GitHub’s Latinx Employee Resource Group.

#147: Terracottocat by Chubbmo (2020-03-05)

Created for the Chinese GitHub community.

#148: Octoqueer by Cameron Foxly & Tony Jaramillo & Joao Ribeiro (2020-03-13)

Created for GitHub’s LGBTQ Employee Resource Group.

#149: OctoAsians by Cameron Foxly (2020-09-28)

Created for GitHub’s Asian Employee Resource Group.

#155: Parentocats by Joao Ribeiro (2023-07-14)

Likely created for GitHub’s parents Employee Resource Group.

#160: Neurocats by kuuchen (2025-04-15)

Created for Neurocats Employee Resource Group.

#161: Octovets by kuuchen (2025-07-22)

Created for Octovets Employee Resource Group.

Undocumented Octocats

In addition to the 150+ documented octocats in the Octodex, there are tons of other ones hidden all over the place if you keep an eye out!

For example, GitHub’s blog posts often have unique octocats (many many many examples on each word), as do third party sites working with GitHub (e.g. AppCanary). Many early blog posts now have broken images, so it’s likely many octocats were used there.

Some of these undocumented octocats are mentioned on GitHub’s Dribbble, or individual designers’ sites, and almost all end up eventually used in GitHub’s social media posts (LinkedIn, GitHub, Facebook).

Cameron McEfee in particular (the artist behind the first “batch” & many more) often shares unpublished examples on Mastodon (examples one, two, three, four, five).

Finally, don’t forget you can create your own Octocat too!

Statistics

Note: Tables in this section count series as 1 each, and uses this Python code to parse the XML data.

Octocats By Artist

With all the excellent artwork in this post, credit absolutely has to be given to the talented artists who created them. These are typically designers creating promotional octocats, but in the early days some designers clearly created them as a hobby hence all the pop culture references (Cameron McEfee, James Kang)!

Later on, many octocats were created in formats not suitable for the Octodex (e.g. these amazing pieces featuring 30+ in one!), so the totals here only cover those explicitly added to the Octodex. It’s likely that the creators of the “Extra Modern” style have probably created far more, they’re just not documented.

I’ve also heard rumours of an upcoming increased focus on Mona the Octocat, so there’ll presumably be more names and numbers coming soon!

I really like how many employees have only ever created one, with some perhaps only being a temporary intern yet still getting a chance to make permanent mark on the culture.

Octocats By Year

Somewhat less positively, looking at the octocats added to the Octodex over time shows how drastically this has decreased over time. Part of this is presumably GitHub growing and becoming less willing to release impulsive octocats (like Walter White!), but I suspect an even bigger part is a lack of interest in updating the Octodex. New octocats are being created (see Undocumented Octocats), they’re unfortunately just not being recorded.

The creator of the first Octocat adaptation (Cameron McEfee) maintained the Octodex in the early days, so it’s perhaps unsurprising that it does not include all octocats 13 years after the first batch!

Conclusion

In conclusion… I love Mona the Octocat. It’s quite unusual that a stock image used initially for a tech startup survives nearly 15 years later, let alone with enough popularity to have an art book, figurine, and sculpture of them!

It’s a great way to give a bit of personality to what could be a bland, megacorp-owned, code management website (looking at you BitBucket…), and obviously instantly earns goodwill amongst cat fans. No, it doesn’t quite make sense (what does a cat really have to do with code!?), but that’s half the appeal, a little bit of quirk.

It’s a shame the Octodex is not as updated as it used to be, and GitHub’s recent focus on AI (and the not-quite-as-cute Copilot icon) has made Mona a little less visible than she used to be. However, I suspect she’ll come back, perhaps with yet another evolution!

“Walk cycles” animations by Tony Jaramillo, from “The Octocat - a nerdy household name“.

I recently updated my site template to support automatic WebP conversion for the banners of every post. This requires both generating the files, and serving them correctly, with no extra manual effort.

A full Gist of this post is available.

Generating WebP files

There’s a library that can do this all for us, unsurprisingly called jekyll-webp!

Setting it up is straight-forward:

1. Add jekyll-webp to your Gemfile.
2. Add jekyll-webp to your _config.yml’s plugins section.
3. Finally, add a webp config object into your _config.yml. Below are the settings I use, a description of each is available on the repo:

webp:
  enabled: true
  quality: 95
  img_dir: ["/assets/images/banners"]
  nested: true
  regenerate: false # Set to true if settings have been changed
  formats: [".jpeg", ".jpg", ".png"]

Once the configuration is set up, run bundle install then bundle exec jekyll serve, and any images in /assets/images/banners will have a WebP version generated!

Displaying webp files

Now the post’s banners are in WebP format, they need to be displayed safely and only to browsers that can support them.

Prep work

First, we need to create a webp.html somewhere. I used _includes/custom/webp.html.

Next, we need to include it wherever we want our WebP / other image formats to appear. For me, this is my home.html & post.html files, where I want to display the image inside an a tag:

<a class="post-link" href="{{ post.url | relative_url }}">
  {% include custom/webp.html path=post.image alt=post.title %}
</a>

Make sure the path and alt parameters map to something useful in your template!

Note: If you don’t already have a post.html / home.html page because you’re using a template’s defaults, GitHub has guidance on how to create them.

Checking WebP file exists

Next, we need to build our webp.html to show these WebP banners if the user’s browser supports them, and they’ve been successfully generated.

Jekyll templates use the quite limited language Liquid, so we have to do some quite tedious string manipulation to:

1. Remove the extension from the file’s path (e.g. .png, .jpg).
2. Add .webp onto the end.
3. Check this new path actually exists.

This can definitely be done more concisely, but I prioritised ease of reading / maintaining:

{% assign path = include.path %}
{% assign alt = include.alt | default: "article" %}

{% assign image_parts = path | split: '.' %}
{% assign extension_length = image_parts | last | size | plus: 1 %}
{% assign base_path_length = path | size | minus: extension_length %}
{% assign base_path = path | slice: 0, base_path_length %}

{% assign webp_path = base_path | append: '.webp' %}
{% assign webp_exists = site.static_files | where: "path", webp_path | first %}

Displaying WebP files

Finally, we’re going to use Picture and source sets to let the browser determine if it can actually use the WebP we’re providing it. If not, it’ll use our original image instead:

<picture class="bg-img">
  {% if webp_exists %}
  <source type="image/webp" srcset="{{ webp_path }}" />
  {% endif %}
  <img src="{{ path }}" alt="Preview image of {{ alt | escape }}" />
</picture>

You’ll notice we’re also using our alt parameter to set a somewhat useful alternative text for accessibility, although this could of course be made more specific if the banner image is important.

Extra details

CSS

Whilst your template will likely differ, for my site this is the CSS that sets the size & scaling of the image:

.bg-img {
  height: 180px;
  border-radius: 0.17rem;
  display: block;
  overflow: hidden;
}

.bg-img img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

WebP limitations

I found some colours (especially dark orange) just wouldn’t render properly in WebP, regardless of quality settings. I strongly suspect this is an issue with the converter I’m using (since it has other long-standing broken functionality). It’s good enough for now, but may need replacing!

Conclusion

Using WebP drastically reduced the size of my site, and now it’s all automatic I won’t need to “fix” it again in the future. It’s long overdue, and I won’t be retroactively fixing past posts, but at least further posts will receive the benefits!

In terms of next steps, I’d like to add automatic banner image resizing, and be able to provide an alternate image for social media sharing. Neither of these is essential, and is arguably bloat, so perhaps not any time soon.

Everything in this post is available as a Gist.

Want to skip directly to my study notes or the conclusion?

Overview

The Foundations Certification came out earlier this year, and later on was made free for students with access to the GitHub Student Developer Pack. To quote GitHub’s docs, this certification covers “your understanding of the foundational topics and concepts of collaborating, contributing, and working on GitHub”, specifically:

• Collaboration
• GitHub products
• Git basics
• Working within GitHub repositories

Completion of the program rewards a Credly badge, as is typical of other online training courses.

This can be added to your LinkedIn:

Studying

As a certification aimed at covering a wide area, some studying is required!

Somewhat bizarrely, GitHub recommends multiple study guides on various platforms, namely:

1. DataCamp’s 4-course “Skill Track”
2. A LinkedIn 7-course “Learning Path”
3. A question-based study guide by a GitHub Developer Advocate. This is just a list of questions (e.g. “Describe branching”) with no answers or information provided.
4. Finally, a 16-module Microsoft “Learning Path”, which is what I used to study since Microsoft owns GitHub, this is recommended, and is text & activity based, not video tutorials.

Throughout my studying I made various notes along the way of bits from Microsoft’s training I might forget, feel free to fork the repo if you find it helpful.

Training contents

I really, really enjoyed Microsoft’s Learning Path for this exam!

The typical format for a module is a few pages of text / diagrams to read, a 10-15 minute exercise performed on GitHub.com itself, then a (short, retakeable, multiple choice) knowledge check quiz. This adds up to around 30 minutes per module, so 8 hours for the entire learning path.

Modules

Whilst the overall learning path wasn’t especially well organised, this was clearly because each module had been designed as an independent unit. For example, whilst the module “Contribute to an open-source project on GitHub” is clearly intended to come after the “Introduction to GitHub” module, it’s clearly written to also be suitable by itself.

This led to a small amount of going over topics again, but this was probably beneficial for the target audience of the course, since the minor parts of repeated content would typically be approached from a new perspective, and in a different level of detail. In general each module built on earlier modules’ teachings, so this is a minor complaint.

Exercises

Easily the best feature of the training was the exercise repos on GitHub itself! Each of these (e.g. “Review pull requests”) requires forking a project, which triggers the README.md’s instructions to update in your fork of the project. Once the new instructions are followed, the README.md updates with extra information on what happened, and newer instructions to continue the exercise. Once this is repeated a few times, and the hands-on lessons have been learned, the exercise is complete.

All the exercises have the same getting started instructions:

This simple cycle, performed by GitHub Actions, excellently highlights how to use GitHub by forcing the user to actually perform the steps. It also gives a hint at how powerful GitHub is, and that it is far more than just a file storage or a collaboration tool. The exercises even cover useful yet rarely taught abilities like “connecting the dots” to hunt down a bug in a project using git blame.

Despite knowing how these features work very well (I’ve likely reviewed 1000+ PRs!), I still completed the exercises because they were genuinely well written and fun. For a new user to GitHub, this hand-holding yet independent approach to getting the basics sorted would be unbelievably helpful.

I’ll definitely be taking a look at all the “skills” training repos available and both trying some more myself and recommending them to more junior developers.

Exam

So I enjoyed the 7-8 hours of training, time to take the exam! Should be easy, right?

Well, maybe if it went smoothly…

Availability

I took this exam for free via GitHub Student Pack. There was an unfortunate issue on initial release where the certification was made free to everyone(!) and the program was paused, but as of the 11th November it’s available again for free.

This 2 month delay was a little annoying, but luckily I didn’t actually start studying until it was made available again. 2 months after incorrect implementation to get the vouchers working again seems a pretty long time, but it’s free so I can’t complain!

Registering

When registering, the voucher to make the exam free was applied automatically, and there was a smooth handover between GitHub and the exam system (PSI exams).

Some unusual additional information was required, such as a full home address without any explanation, and a request for my phone number. When I entered my number I was told my country wasn’t supported, but luckily I could skip this step! That same phone number was accepted later on as a contact number, so I’m not sure what changed.

The exam can be taken whenever you want, within 60 days of your registration. The scheduling confirmation email had some… odd parts (it was actually a 2-hour exam, and it had a name!), which was perhaps yet another warning that this process wasn’t perfect:

• Test: Exam Name
• Duration: 11 minutes
• Exam Availability: Anytime 24/7
• Location: On Demand Testing

The actual booking process was uneventful:

Taking exam

Finally, I went to start my exam. It required downloading and installing “PSI Bridge Secure Browser” which actually seemed shady enough that I double-checked the domain & company were legitimate! They were, and I had no other options if I wanted the certification, so I installed the browser.

Security check

Once installed, it somehow knew the exam I was taking and ran it’s “Security Check”.

This check was pretty obnoxious, I understand it’s to prevent cheating but what a pain it is! I had to unplug my 2nd monitor, close Chrome, Spotify, WhatsApp, VSCode, and even open up “Services” and disable a few Hyper-V and Nvidia processes. Again, I understand why I can’t have Chrome open, but this is a non-proctored exam and my phone is right in front of me, I suspect these controls work better in a classroom environment!

Starting the exam immediately took me into what seemed like a post-exam survey, asking if I felt I’d had enough time, how I found the exam etc. These required answers were impossible to answer yet, so I just submitted neutral answers with the intention of revisiting them afterwards.

Submitting exam

After an hour or so of answering every question (more on those later), I clicked submit and… received a fullscreen “Something went wrong” message. There was a “Details” button, so of course I clicked it to discover it was a TypeError around an undefined total!

Not ideal. I tried every control I had available to me (changing colour scheme, contrast, navigating via different routes, refreshing the exam) and it would happen every time. I tried reopening the secure browser and luckily the answers saved, but same error. Restarted laptop, same error. Uh oh.

Customer support pain

Ready for a rant? Feel free to skip!

I reached out to PSI’s support email and was told I had to talk to the technical team instead, via phone or live chat. Opening live chat led to a very frustrating conversation with an obviously script-following support agent who essentially ignored what I said unless it directly answered a question, despite me showing him the error at the very start!

After 20 minutes of slow & pointless back and forth, he asked if I’d restarted the secure browser. I had (and had told him in the first message), this apparently meant I had to contact GitHub! There were no more detailed instructions, he offered to give me a ticket number which was better than nothing, so… sure, off to GitHub we go.

Over on GitHub I raised a support ticket, and had a far better experience. They replied within an hour that they are aware of the issue and are “coordinating with PSI” on it, with updates promised. 6 hours later, I received an email from Credly with my GitHub Foundation badge, I guess they managed to fix it!

Overall PSI were very unhelpful, and I had to fend off multiple pointless suggestions (e.g. “Talk to your professor and ask to retake”) whilst also being pushed between support platforms (PSI email, PSI live chat, GitHub support) without any handover. This meant I had to explain my situation 3x, with only GitHub showing any empathy or responsibility.

Exam contents

The exam’s contents were surprising. Instead of being a knowledge check of GitHub basics, it was more of a trivia and obscure information check.

I would estimate the exam consisted of:

• 30%: Things a developer would actually need to know, and should be tested on (what is a branch, what is a fork),
• 60%: Entirely pointless trivia that there is no value whatsoever in memorising, and can be easily looked up (how to access a setting, what view options are available for projects, features in GitHub paid plans).
• 5%: Debatable answers that have different answers for different teams (best practices, how to interact on open source repositories, PR behaviour).
• 5%: Incorrect, outdated, or unclear questions.

For example, one question asked “Which of the following can be performed within GitHub Mobile?”, with 5 possible answers. The correct answer was “Managing notifications from github.com”, and incorrect answers included “Managing enterprise and organization settings” but what is the point in knowing this? A user with the app installed can just use the website if they need to, and the app isn’t required anyway!

Another poor question asked where the 2FA settings can be found, with options including “Profile > Account > 2FA” and “Settings > Password & Authentication > 2FA”. This is an essentially impossible question, since it’s a thing most users only configure occasionally, and the two answers are very similar regardless. Again, what’s the point in ever memorising the navigation path to 2FA? If you need to change it, you’ll click your user profile in the top right, and find a Settings-y option, and go from there.

Finally, one particularly silly example. One question asked about “Private beta” and “Public beta” feature previews. This terminology was replaced a month ago, so there is no correct answer to the question!

Conclusion

I really enjoyed the studying for the GitHub Foundations Certification exam, especially the hands-on exercises, even if the majority of it wasn’t new information. This was fully expected, since I’ve been a software engineer for 10 years so should know my way around GitHub! The training even gives a trophy, arguably almost as good as taking the actual exam:

Unfortunately the exam’s tendency to test pointless trivia (not to mention fatal technical issues) was far less enjoyable.

Reputability

I discovered after passing the exam that there’s many “practice exams” available online that essentially have very similar / identical questions and answers. I won’t link to them here since I’m pretty sure that’s essentially cheating, but it’s worth mentioning!

Due to this, and the basic sounding “Foundations” certification, I’m not sure how much value this certification will actually add to a LinkedIn profile or Resume. I’d actually find completing Microsoft’s study guide training far more impressive (if the exercises are included), since it’s real, hands-on experience, in contrast to the exam’s trivia.

Other certifications

Overall I don’t think this certification is a good “advert” for GitHub’s certification program, at least for personal development. The study guides are essentially a more focused version of the existing documentation, with the exam more covering how well you can memorise minutia than actually use the tools.

If my employment heavily involved GitHub Actions, Administration, Advanced Security, or Copilot I might consider working through the study guides and getting corporate sponsorship (especially Actions), but as an Android Engineer they’re not worth it yet. A redditor has compared their experience taking all 5 exams.

Summary

I’d absolutely recommend the GitHub Foundations Certification to students since it’s completely free, or those with a corporate sponsor who will support their education. It teaches skills that almost every software engineer will need in their very first role.

However, I wouldn’t recommend paying for it yourself, since arguably the most valuable part is the freely available training. I’d also not recommend it if you have a year or two of real world software engineering experience, instead it’s more useful as a “bridge” between a Computer Science degree education and actually using GitHub day-to-day.

This article will assume Kotlin is used, if you require Java just remove the ktx dependency and adjust the provided code. All code used in this article is available as a GitHub gist.

Scenario

The ability to force a user to update their app is something that seems pointless… until it’s suddenly essential. This might be due to shutting down an outdated or insecure endpoint, a particularly bad bug in older versions, or even just the desire for customers to experience new features.

Regardless of the exact reason for a future force update, it’s a core piece of functionality for any app from the very beginning.

Whilst the in-app library does support optional (“Flexible”) updates, this article will just cover required (“Immediate”) updates. They’re self-explanatory, below are Google’s representative images:

Flexible / Optional update	Immediate / Required update

Preparing your app

Unsurprisingly, the library needs to be added to your app! I’m using version catalogs and Kotlin DSL for Gradle, if you’re using Groovy or defining dependencies in a more classic way that approach works fine.

Defining the dependency

Inside my libs.versions.toml, I add the latest version of the library & ktx version (2.1.0 at time of writing):

[versions]
android-playAppUpdate = '2.1.0'

[libraries]
android-playAppUpdate = { module = "com.google.android.play:app-update", version.ref = "android-playAppUpdate" }
android-playAppUpdateKtx = { module = "com.google.android.play:app-update-ktx", version.ref = "android-playAppUpdate" }

Using the dependency

Inside any module that you want to be able to force an update from, add the dependencies:

dependencies {
    implementation(libs.android.playAppUpdate)
    implementation(libs.android.playAppUpdateKtx)
}

Preparing a wrapper

Whilst there is documentation on calling the library, it’s hard to follow. All you’re actually doing is:

1. Checking if an update is available.
2. If it is, display the force update dialog.

That’s it! There’s complexity added due to the messy callback structure of the library, but this can all be abstracted away.

My wrapper is essentially the same as the official documentation, with a bit of function extracting etc for readability and simplicity. I’ll break down the component parts, feel free to just look at the full code.

Handling the update dialog’s result

Somewhat counterintuitively, we’ll look at the final step first.

Once the force update dialog has been shown, our app will receive a callback. We’ll just do basic logging for now in most scenarios, except if the user cancels / closes our dialog. This is a mandatory update, so we’ll pass in activity.finish() as a callback to close our app if this happens!

    handleUpdateResult(result) {
        activity.finish()
    }

    ...

    private fun handleUpdateResult(result: ActivityResult, onUpdateDialogClose: () -> Unit) {
        when (result.resultCode) {
            Activity.RESULT_OK -> Timber.i("User has started mandatory update")
            Activity.RESULT_CANCELED -> onUpdateDialogClose.invoke()
            RESULT_IN_APP_UPDATE_FAILED -> Timber.i("Mandatory update failed")
            else -> Timber.i("Error whilst updating (${result.resultCode}): ${result.data?.data}")
        }
    }

Displaying the force update dialog

Again, working backwards, we need to actually display the dialog assuming all conditions have been met.

We can just use a wrapper around the library’s startUpdateFlowForResult function, where activityResultLauncher is essentially a container with our handleUpdateResult from earlier.

    private fun startForceUpdateFlow(
        appUpdateInfo: AppUpdateInfo,
        activityResultLauncher: ActivityResultLauncher<IntentSenderRequest>,
        appUpdateManager: AppUpdateManager
    ) {
        appUpdateManager.startUpdateFlowForResult(
            appUpdateInfo,
            activityResultLauncher,
            AppUpdateOptions.newBuilder(IMMEDIATE).build()
        )
    }

Deciding if dialog should be shown

Finally we come to the first step, determining whether the dialog actually needs displaying!

This is where the library really shines, boiling down all the complexity of checking if an update is required into a single function that returns a AppUpdateInfo. There’s a couple of helper functions to simplify the logic, and you should recognise our handleUpdateResult and startForceUpdateFlow functions.

The final core logic is very readable, simply “if update is in progress or an update is required, display the force update dialog”. Note that resuming an in progress update is the recommended behaviour.

    fun forceUpdateIfNeeded(activity: ComponentActivity) {
        // Must be declared before activity is resumed: https://stackoverflow.com/a/67582633/608312
        val activityResult = activity.registerForActivityResult(ActivityResultContracts.StartIntentSenderForResult()) { result ->
            handleUpdateResult(result) {
                activity.finish()
            }
        }
        val appUpdateManager = AppUpdateManagerFactory.create(activity)
        val appUpdateInfoTask = appUpdateManager.appUpdateInfo

        appUpdateInfoTask.addOnSuccessListener { updateInfo ->
            if (updateInfo.isUpdateInProgress() || updateInfo.isForceUpdateRequired()) {
                startForceUpdateFlow(updateInfo, activityResult, appUpdateManager)
            }
        }
    }

    private fun AppUpdateInfo.isUpdateInProgress() =
        updateAvailability() == DEVELOPER_TRIGGERED_UPDATE_IN_PROGRESS

    private fun AppUpdateInfo.isForceUpdateRequired() =
        updateAvailability() == UPDATE_AVAILABLE && isUpdateTypeAllowed(IMMEDIATE)

Remotely control the minimum version

The force update flow now works!

However, we need the ability to remotely control which versions should be force updated. There are two built-in methods for controlling this, but we’ll use Firebase Remote Config instead (any remote value system works fine). The built-in options are:

1. Determine update behaviour based on how old the user’s app version is. This wasn’t suitable for me as I only wanted to force update in specific circumstances.
2. Set inAppUpdatePriority via the Google Play Developer API, then determine update behaviour in-app based on the priority value. This wasn’t suitable for me as I wanted a simpler way of setting the version to upgrade from, and for all the logic to be remote. Additionally, the value can only be set on initial rollout.

So, what will we use? Firebase Remote Config! Any system that lets you remotely serve a number will work, even if that’s something like checking a text file on your server. Remote Config is useful since it also lets us target specific values to subsets of our audience, for example only forcing users on bad version 100 to update to 101 whilst leaving users on good version 99 alone.

In this example, abTestManager is a wrapper within my app’s codebase, and not relevant or required.

We fetch a minimum allowed version code (e.g. 1000), and if the current app version (BuildConfig.VERSION_CODE) is higher or equal, none of the in-app update library code is called. This also adds a layer of safety from bugs in the library, as we can easily remotely disable the library’s ability to lock the user out.

    fun forceUpdateIfNeeded(activity: ComponentActivity) {
        val minimumAllowedVersion = abTestManager.remoteConfigLong(FirebaseRemoteConfigKeys.minimum_version)
        if (BuildConfig.VERSION_CODE >= minimumAllowedVersion) {
            return
        }

        ...
    }

Putting it all together

We’re done!

We’ve checked the current version requires updating, we’ve used the library to check the update is available, then used the library to display a force update dialog, and listen to callbacks about the result.

Again, all code in this article is available as a GitHub Gist.

Calling the wrapper

Once you’ve obtained an instance of your ForceUpdateHandler (I used dependency injection), the whole checking and updating process can be kicked off by calling it with an Activity or similar class (I used ComponentActivity):

updateHandler.forceUpdateIfNeeded(this)

This should be done as soon as possible in your app’s main / launcher Activity (e.g. in onCreate), wherever users start when opening the app. It’s also fine to call this from multiple Activities, e.g. if deep linked users go via a different Activity.

Note that this must be called before your Activity’s onResume, as explained in this StackOverflow comment.

Testing

To quote myself about testing on the PR to implement this feature:

Oh god. This took as long as the implementation!

It’s one of the hardest features I’ve ever had to test, due to the strict requirements on seeing the dialog, namely:

1. The app must be installed from the store.
2. A newer version of the app must be available to you on the store.
3. You must be using the device’s primary email (in my testing at least).
4. There are various device & server caches that take hours to invisibly clear.
5. You cannot use an emulator (again, in my testing at least).

Since we don’t want to actually deploy multiple new versions of our app to the store just to test a feature, we’ll be using the “Internal testing” track to give ourselves access to pre-release builds.

This internal sharing requirement is likely the cause of most of the complexity, since it requires bypassing all usual build preparation steps. In this scenario our live version code is 100, and we will be using 101 -> 102 to test our updating.

Note that whilst Google does have documentation for this process, it’s very limited and misses many of the steps / requirements.

Preparing “old” app version

First, a candidate to be force updated from needs to end up in Internal sharing!

1. Update your build with a higher version code (e.g. 101) than your current live version (e.g. 100).
2. Prepare a production keystore signed version of your app, it’s fine if you use Google Play Key Signing so long as your signing matches your usual production app process.
3. Upload this to the “Internal sharing” release track on Google Play Console, and make sure it is “released”.

Preparing your device

Next, we need to get this version onto our phone.

On your desktop:

1. Update the list of “Internal sharing” users to include your physical device’s primary email.
2. Find the internal testing opt-in link (will look something like https://play.google.com/apps/internaltest/123456).
3. Open this opt-in link in a browser with this same primary email logged in, and join internal testing (I had to use a desktop browser for this).

On your phone:

1. Go to the store listing for your app, and check it says “You’re an internal tester”.
2. Check the app version matches your test version (101), download and install the app.
3. Turn off automatic updates for this app (guide).

If that all went smoothly, you now have a test version on your device! There may be small delays at any stage whilst various caches update, techniques like restarting your phone may help.

Preparing “new” app version

Now we need a newer version to force update to.

1. Repeat all the steps in “Preparing old app version”, except with a higher version code (e.g. 102).
2. Open the system you’re using to control the minimum version (Firebase Remote Config in this example), and set the minimum version to the newly uploaded version (102).

Triggering the force update

So, we now have version 101 on our device, version 102 on the store, and version 102 set as the minimum. Opening our now outdated app, we can see… nothing happens. Huh!?

You’ll now need to wait at least an hour or two for Firebase Remote Config cache to clear, Google Play cache to clear, and countless other delays along the way! It took around 4 hours of waiting for me, very painful when you’re trying to find out if a new feature works.

It’s fine to reopen the app during this wait, I didn’t find any way to “force” the latest version information to be updated. Whilst I tried closing my app, restarting the device, clearing the cache of Google Play Store and various other techniques they didn’t make any difference. I presume this is due to the delay being server side.

Anyway, eventually you’ll open your app and… be prompted to update!

Next steps

Our app now has the ability to force update on demand, but that’s all. It can’t gently nudge to update, it can’t automatically prompt a user to update if their version is too old, or anything else more advanced. It also uses a default system dialog, which may not be desirable.

Flexible updates

This is the obvious next step, prompting the user to update days before we force them.

Flexible updates seem more complex, with the app itself being responsible for (optionally) restarting once the update is downloaded, and an expectation that the update prompting dialog does not show too frequently.

The optional update feature will likely work well with clientVersionStalenessDays, as simple logic such as prompting users when their version is >7 days out of date would drastically reduce the users lingering on outdated versions. Performing a force update after another fixed interval is also an attractive proposition, especially as the risk of users getting “stuck” due to minimum SDK requirements etc is very minimal.

Custom screens

Of course, this is just a starting point. You might find the update prompting screen doesn’t fit your app’s tone of voice or marketing style, and want to build your own.

This can be done by replacing the contents of the startForceUpdateFlow function to display whatever blocking dialog you want, whilst being careful to ensure the user can’t “escape” by pressing back or using deep links.

Conclusion

The ability to force a user to update from a specific version to another is absolutely essential for any app. Nudging to update from outdated versions might be helpful, but getting the user off a bad version can avoid catastrophes.

Implementing this using Google’s library allows skipping a lot of the manual work (e.g. how does the app know a new version is available?), and avoids having to keep an up-to-date record somewhere of which versions are acceptable.

However, the trade-off for this is that the library’s somewhat roundabout set of functions needs to be used. This library is also rarely updated, with the last update 18 months before this article. Whilst this might mean it’s flawless, I suspect it actually means it’s mostly abandoned unless something major breaks! I’m certainly not holding out hope for usability improvements.

Aaaand one last time in case someone scrolled straight to the bottom: Here’s the GitHub Gist for the force update functionality.