AppUpdateWrapper

A wrapper for Android AppUpdateManager to simplify in-app update flow.

Here is an intoroduction article to this library describing problems I've come across when implementing in-app updates in a real-world Android application.

Contents

• Features
• Basics
• Using in your project
  • 1. Setting up the dependency
  • 2. Implementing AppUpdateView
    • activity (mandatory)
    • updateReady (mandatory)
    • updateFailed (mandatory)
    • updateChecking (optional)
    • updateDownloadStarts (optional)
    • updateInstallUiVisible (optional)
    • updateComplete (optional)
    • nonCriticalUpdateError (optional)
  • 3. Start your update flow
    • checkActivityResult
    • userCanceledUpdate and userConfirmedUpdate
    • cleanup
    • Starting IMMEDIATE update
    • Starting FLEXIBLE update
  • Non-intrusive flexible updates with UpdateFlowBreaker
• Using library in multi-activity setup
  • AppUpdateManager instance
  • Use safe event handlers
  • A possible implementation
• Logging
  • Enabling logger
  • Logging rules

Features

• A complete lifecycle-aware component to take a burden of managing update state (especially FLEXIBLE).
• You should only implement a couple of UI methods to display install consents the way you like it to get running.
• Makes things easier to run flexible update for multi-activity applications - suspends and resumes UI interaction along with main application flow.
• Flexible updates are non-intrusive for app users with UpdateFlowBreaker.

Basics

Refer to original documentation to understand the basics of in-app update. This library consists of two counterparts:

• AppUpdateWrapper is a presenter (or presentation model to some extent) that is responsible for carrying out the IMMEDIATE or FLEXIBLE update flow. It is designed as a single-use lifecycle observer that starts the flow as soon as it is created. The wrapper will also maintain a current state of update especially the UI state (the thing missing in original AppUpdateManager). The update flow completes either with calling updateComplete() or updateFailed(e: Throwable) methods of AppUpdateView.
• AppUpdateView is a presenter counterpart that you implement to ask user consents, notify of update errors, etc.

Here is the basic activity setup that is enough to run a flexible update in background each time your activity starts:

/**
 * Basic update activity that checks for update
 */
class TestActivity : AppCompatActivity(), AppUpdateView {
    /**
     * Update flow
     */
    private lateinit var updateWrapper: AppUpdateWrapper

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Starts flexible update flow that (if cancelled) will ask again tomorrow
        updateWrapper = startFlexibleUpdate(
            AppUpdateManagerFactory.create(this.applicationContext),
            this,
            UpdateFlowBreaker.forOneDay(getSharedPreferences("uiState", Context.MODE_PRIVATE))
        )
    }

    // Passes an activity result to wrapper to check for play-core interaction
    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        if (updateWrapper.checkActivityResult(requestCode, resultCode)) {
            // Result handled and processed
            return
        }
        // Process your request codes
    }

    /********************************/
    /* AppUpdateView implementation */
    /********************************/

    // AppUpdateManager needs your activity to start dialogs
    override val resultContractRegistry: ActivityResultRegistry = this.activityResultRegistry

    // Called when flow starts
    override fun updateChecking() {
        // Show some spinner...
    }

    // Update is downloaded and ready to install
    override fun updateReady() {
        // Display confirmation dialog of your choice and complete update...
        updateWrapper.userConfirmedUpdate()
        // ...or cancel it
        updateWrapper.userCanceledUpdate()
    }

    // Update check complete
    override fun updateComplete() {
        Toast.makeText(this, "Update check complete", Toast.LENGTH_SHORT).show()
    }

    // Update check critical error (effective in IMMEDIATE flow)
    override fun updateFailed(e: Throwable) {
        Toast.makeText(this, "Update failed", Toast.LENGTH_SHORT).show()
        finish()
    }
}

Using in your project

Follow the steps below to use AppUpdateWrapper in your application. Some of them are optional, some of them are required for multi-activity applications only.

1. Setting up the dependency

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.motorro.appupdatewrapper:appupdatewrapper:x.x.x@aar'
}

2. Implementing AppUpdateView

AppUpdateView represents a UI part of application update flow and the only point of interaction between your application and AppUpdateWrapper. You may directly extend it in your hosting Activity or delegate it to some fragment. Here are the methods you may implement:

resultContractRegistry (mandatory)

val resultContractRegistry: ActivityResultRegistry

AppUpdateManager launches activities on behalf of your application. Implement this value to pass the activity result registry that will handle the onActivityResult. Typically you pass your activity activityResultRegistry there.

updateReady (mandatory)

fun updateReady()

Called in flexible flow to report that update has been downloaded and ready to be installed. The UI may display some confirmation dialogue at this point. Depending on user's answer call AppUpdateWrapper.userConfirmedUpdate to install and restart or AppUpdateWrapper.userCanceledUpdate to postpone installation. The next time the user will be asked to update an app in a latter case is configurable.

updateFailed (mandatory)

fun updateFailed(e: Throwable)

Effective within the IMMEDIATE update flow to report a critical update error. Within the immediate update flow this is considered critical and you may want to terminate application.

updateDownloadProgress (optional)

fun updateDownloadProgress(bytesLoaded: Long, bytesTotal: Long)

Called in flexible flow to report that update download progress. You may display a progress bar or something.

• bytesLoaded - number of bytes downloaded
• bytesTotal - total number of bytes to download

updateChecking (optional)

fun updateChecking()

Called by presenter when update flow starts. UI may display a spinner of some kind.

updateDownloadStarts (optional)

fun updateDownloadStarts()

Called when user confirms flexible update and background download begins. Called in flexible flow.

updateInstallUiVisible (optional)

fun updateInstallUiVisible()

Called when play-core install activity covers your application. In some cases (immediate update flow for example) you may want to finish your main activity (or clear stack) at this point so user won't 'back' to it from update screen.

updateComplete (optional)

fun updateComplete()

Called when flow is finished. Either update not found, or cancelled, etc. Indicates a successful outcome. Called in flexible flow. Immediate flow either restarts (on success) or fails with updateFailed.

nonCriticalUpdateError (optional)

fun nonCriticalUpdateError(e: Throwable)

Some error occurred during the update but it is considered non-critical within selected update flow. UI may toast or notify the user in some other way. Called in flexible flow. Immediate flow is designed to be mandatory so it fails with critical updateFailed.

3. Start your update flow

The library supports both IMMEDIATE and FLEXIBLE update flows.

• Choose IMMEDIATE flow when you need user to update or to quit. For example you may receive a 'not-supported' message from your server and user can't use the outdated application anymore.
• Choose FLEXIBLE flow when you just check if there is a new version available. User may install it or may reject to do so. In the latter case it is considered a good UX practice to not to annoy user with every activity start but rather to delay and ask him to update later. See UpdateFlowBreaker below for details.

Both flows implement the AppUpdateWrapper interface with the following methods to consider:

userCanceledUpdate and userConfirmedUpdate

fun userCanceledUpdate()
fun userConfirmedUpdate()

When flexible flow download completes you should ask for user consent with install and application restart. At this point AppUpdateWrapper calls your view updateReady callback. Present a consent UI of your choice and call either userConfirmedUpdate or userCanceledUpdate. See the UpdateFlowBreaker below to find out what happens if user cancels.

cleanup

fun cleanup()

Call this method to abort update check and cleanup all update flow internals. Sometimes you may need to cancel the flexible update check to start immediate flow right away. So you may end up with the following in your host activity:

/**
 * Update wrapper instance
 */
private var updateWrapper: AppUpdateWrapper? = null
    set(value) {
        field?.cleanup()
        field = value
    }
    
/**
 * Starts immediate application update
 */
fun updateRightAway() {
    updateWrapper = startImmediateUpdate(appUpdateManager, this)
}

/**
 * Checks if update available
 */
fun checkForUpdate() {
    updateWrapper = startFlexibleUpdate(
        appUpdateManager,
        this,
        flowBreaker
    )
}
 

Starting IMMEDIATE update

Choose IMMEDIATE flow when you need user to update or to quit. For example you may receive a 'not-supported' message from your server and user can't use the outdated application anymore. To start immediate flow call the following function from your lifecycle owner (activity):

fun LifecycleOwner.startImmediateUpdate(appUpdateManager: AppUpdateManager, view: AppUpdateView): AppUpdateWrapper

Parameters:

• appUpdateManager - application update manager instance
• view - your AppUpdateView implementation

This flow requires no user interaction on your side besides that you should implement updateFailed as you'll want to shutdown your application in that case. The flow ends up in application being restarted (so you may not see the updateComplete call) or failure (above).

Starting FLEXIBLE update

Chose FLEXIBLE update if you just want to notify user if update is available but there is no problem if he cancels it. To start the flow call the following function from your lifecycle owner (activity):

fun LifecycleOwner.startFlexibleUpdate(
    appUpdateManager: AppUpdateManager,
    view: AppUpdateView,
    flowBreaker: UpdateFlowBreaker
): AppUpdateWrapper

Parameters:

• appUpdateManager - application update manager instance
• view - your AppUpdateView implementation
• flowBreaker - the delegate that will acknowledge user cancellation and make sure you won't bother him too much. More on this follows.

If update is available, the flow displays a consent with download window (play-core internal activity). So make sure to pass the onActivityResult data to checkActivityResult. When update is downloaded, the wrapper calls your updateReady callback where you should call either userConfirmedUpdate or userCanceledUpdate of workflow to continue.

Non-intrusive flexible updates with UpdateFlowBreaker

One of the possible ways to implement a non-intrusive flexible workflow is to run it in background when your activity starts and notify user the update is available. The user continues to use application normally while update check runs. If user cancels the update he will be prompted again when an activity starts again which is a bit annoying. To overcome this flaw the flexible update of this library incorporates a couple of simple interface that are used to postpone update checks if user has already declined:

/**
 * Checks if user has already refused to install update and terminates update flow
 */
interface UpdateFlowBreaker: TimeCancelledStorage {
    /**
     * Checks if enough time has passed since user had explicitly cancelled update
     */
    fun isEnoughTimePassedSinceLatestCancel(): Boolean

    /**
     * An extra point to check if update available is of any value to user
     * For example you may implement extra logic on update priority level (set from play market) or
     * staleness. Called _instead_ of [isEnoughTimePassedSinceLatestCancel] when processing
     * available update so you may want to combine both time of last offer and update value at the
     * same time.
     * @param updateInfo
     */
    fun isUpdateValuable(updateInfo: AppUpdateInfo): Boolean
}

/**
 * Stores time the update was cancelled
 */
interface TimeCancelledStorage {
    /**
     * Gets the latest time user has explicitly cancelled update (in milliseconds)
     */
    fun getTimeCanceled(): Long

    /**
     * Saves current time as the latest one user has explicitly cancelled update
     */
    fun saveTimeCanceled()
}

You may want to implement them yourself but the library has some already. They are created by calling corresponding factory functions of UpdateFlowBreaker:

fun alwaysOn(): UpdateFlowBreaker

Creates a breaker that is always turned on and never breaks the flow.

fun withInterval(interval: Long, timeUnit: TimeUnit, storage: TimeCancelledStorage): UpdateFlowBreaker

Used to postpone check for interval since user explicitly cancelled

fun forOneDay(storage: TimeCancelledStorage): UpdateFlowBreaker

Postpones update for one day

fun forOneDay(storage: SharedPreferences): UpdateFlowBreaker

Postpones update for one day storing cancellation time in shared preferences.

fun UpdateFlowBreaker.withUpdateValueCheck(valueCheck: (Boolean, AppUpdateInfo) -> Boolean): UpdateFlowBreaker

Extends the existing breaker with an update value check function [valueCheck] which is called when update info gets available. Update priority or staleness combined with last update offer time will hel you to decide if to ask again or even cancel the flexible flow and switch to immediate flow. The function you pass will receive a time check result from your wrapped breaker and an update info from update manager.

Take a look how to pass the breaker to the workflow in a basic example.

Using library in multi-activity setup

When the app is based on multiple activities it presents an extra challenge to implement a flexible update due to multiple onResume, onPause workflow events. The update may start in one activity and the other one should respond to download complete event and present an install consent. Most (hopefully) of these cases are addressed in library design and tested in a large multi-activity application. It seems however the original AppUpdateManager was written with single-activity design in mind and several issues are to be solved.

Start update everywhere

The library does not store any common update state between wrapper instances. The only state it uses is what google play-core provides. This is done intentionally as the update is downloaded without your control and there is no way to stay sync with it unless you are in a foreground (so-so). Thus in order to catch-up with things going on, the wrapper should be started in any activity that may take part in update process (interact with user concerning update). The update flow will be updated to correct state as long as the google-provided status allows to do it.

AppUpdateManager instance

Consider using a singleton instance injecting it to your flow instances from an application scope. Using several AppUpdateManager instances simultaneously didn't work for me.

Use safe event handlers

Google has fixed the issue with event listeners in 'com.google.android.play:core:1.6.3' If you use library 1.3.3 and above you don't need this fix

When using a singleton AppUpdateMaanager with multiple activities there is a problem with managing subscription to update flow events. When several listeners are connected to a single manager and try to usnsubscribe in an event handler the manager crashes with ConcurrentModificationException. This is due to a non-copy hash-set iteration is used to notify listeners internally. See the test file for the details. To overcome the problem for a moment the library uses a duct-tape solution which will hopefully be removed in the future. All-in-all if you are using a multi-activity setup and come across such exceptions (see when download completes) turn on the solution prior to your flow is created like this:

class App: Application() {
    override fun onCreate() {
        super.onCreate()
        AppUpdateWrapper.USE_SAFE_LISTENERS = true
    }
}

A possible implementation

You may want to implemented the AppUpdateView in your base activity (if you have any) injecting it with a singleton AppUpdateManager. I will not put a complete listing here but you may take a look at the following gists for complete reference:

• Base activity setup
• Dagger providers for update wrapper

Logging

Sometimes you'll want to see what is going on in the update flow. The library supports logging to Timber.

Enabling logger

The library itself does not plant any tree - you need to do it yourself to get log output:

class App: Application() {
    override fun onCreate() {
        super.onCreate()
        if (BuildConfig.DEBUG) {
            Timber.plant(Timber.DebugTree())
        }
    }
}

Logging rules

• All library log output has common tag prefix: AUW.
• Checking for update and update results have info level.
• Update check failure and critical errors have warning level.
• Internals (state transition, lifecycle updates) have debug level.

All-in-all the library log looks like this:

D/AUW::AppUpdateLifecycleStateMachine: State machine initialized
D/AUW:startImmediateUpdate: Starting FLEXIBLE update flow...
D/AUW::AppUpdateLifecycleStateMachine: Setting new state: Initial
D/AUW::Initial: onStart
D/AUW::AppUpdateLifecycleStateMachine: Setting new state: Checking
D/AUW::AppUpdateLifecycleStateMachine: Starting new state...
D/AUW::Checking: onStart
D/AUW::IntervalBreaker: Last time cancelled: 0, Current time: 1565980326128, Enough time passed: yes
I/AUW::Checking: Getting application update info for FLEXIBLE update...
I/AUW::Checking: Application update info: Update info: 
        - available version code: 62107400
        - update availability: UPDATE_NOT_AVAILABLE
        - install status: UNKNOWN
        - update types allowed: NONE
D/AUW::Checking: Evaluating update info...