Develop

In-app update Platform SDK APIs

Updated: Oct 30, 2026

Overview

The purpose of providing the in-app update APIs is to give you more control over your app update experience. It’s up to you to use these APIs in ways that best fit your specific requirements. This document describes a broad overview of these APIs. The exact details of the APIs along with their parameters are available in the Platform SDK Application Package reference.
To launch a different app instead of updating your own, see App Deep Linking.
The APIs are suspend functions on the Application class. Call them from a coroutine scope such as lifecycleScope or viewModelScope. A failed request throws an ApplicationException. getVersion() requires Meta Horizon OS v79 or later, and the download and install APIs require v85 or later.
Complete the steps in Get Started Kotlin Development, then add the Application package to ./gradle/libs.versions.toml:
[libraries]
# Existing lines
application-kotlin = { module = "com.meta.horizon.platform.sdk:application-kotlin", version.ref = "horizonPlatformSdk" }
And to your app’s dependencies:
dependencies {
    // Existing lines
    implementation(libs.application.kotlin)
}

GetVersion API

Once the user opens up the app and starts interacting with the app, the app can try to check if an update is required on that particular device or not. This can be done by making use of this API. This API returns the currently installed version on the device, the latest available version and the size and release date of the latest version. These values will help in deciding if an update is required or not. If the app determines that an update is required then the APIs described later will help in performing the update process. This is an example usage -
import horizon.platform.application.Application
import horizon.platform.application.ApplicationException

val application = Application()
try {
    val version = application.getVersion()
    if (version.currentCode != version.latestCode) {
        // An update is available. Prompt the user to initiate or do it automatically
    }
} catch (e: ApplicationException) {
    Log.e(TAG, "getVersion failed: ${e.displayableMessage}")
}

StartAppDownload API

This API will start the download of the latest available app update. Once this request is made, the installer automatically figures out which version of the app needs to be installed on the device. This is an example usage -
try {
    val result = application.startAppDownload()
    // handle success
} catch (e: ApplicationException) {
    // handle error here
}
At this point depending on the success or failure of the operation, the app can decide to show some kind of in-app notification to the user to indicate that the download is complete. In case it was successful, the app can call the InstallAppUpdateAndRelaunch API to install this update and then automatically relaunch the app. If the request fails, see Additional details about the install result status.

CancelAppDownload API

If during the download process, the app wants to cancel the ongoing download for some reason, then this API can be used to immediately cancel the download. No further action needs to be taken after this.

CheckAppDownloadProgress API

The app download process can take a long time to finish depending on the size of the update that needs to be downloaded. This API can be called when the download process started by the StartAppDownload API is still in progress. This will return the number of bytes to be downloaded, the number of bytes that have already been downloaded and the current status of the app. This can be used by app developers to show some kind of progress bar to users if they want to. The result has the following fields -
  • downloadBytes: Total number of bytes that need to be downloaded
  • downloadedBytes: Number of bytes that have already been downloaded
  • statusCode: An AppStatus value
The app status is one of the following values -
  • Unknown
  • Entitled
  • DownloadQueued
  • Downloading
  • Installing
  • Installed
  • Uninstalling
  • InstallQueued

InstallAppUpdateAndRelaunch API

Once the app update has been successfully downloaded, the app can use this API to perform the actual install of the update. During the install process the app is automatically killed by the Operating System and relaunched once the install is complete. So the user will need to wait for some time before they can start using the app again. The app developer has the option to specify the deep link at which they would like to relaunch the app to. This will help users resume what they were doing before the install was initiated. This is an example usage -
import horizon.platform.application.options.ApplicationOptions

val appOptions = ApplicationOptions.builder()
    .withDeeplinkMessage(deeplink)
    .withDestinationApiName(destinationApiName)
    .build()

try {
    application.installAppUpdateAndRelaunch(appOptions)
} catch (e: ApplicationException) {
    // handle error
}

Additional details about the install result status

When a request fails, the code of the ApplicationException matches the value of an ApplicationStatusCode entry, which provides additional details about the reason for the failure, for example ApplicationStatusCode.LowStorage, NetworkError, DuplicateRequest, UserCancelled, or AuthorizationError. For the full list, see the Platform SDK Application Package reference.