Play In-App Update

Native API for Play In-App Update.

Summary

Enumerations
AppUpdateAvailability{
  APP_UPDATE_AVAILABLILITY_UNKNOWN = 0,
  APP_UPDATE_NOT_AVAILABLE = 1,
  APP_UPDATE_AVAILABLE = 2,
  APP_UPDATE_TRIGGERED_IN_PROGRESS = 3
} 		enum
Availability info for an in-app update.
AppUpdateErrorCode{
  APP_UPDATE_NO_ERROR = 0,
  APP_UPDATE_UNKNOWN_ERROR = -2,
  APP_UPDATE_API_NOT_AVAILABLE = -3,
  APP_UPDATE_INVALID_REQUEST = -4,
  APP_UPDATE_UNAVAILABLE = -5,
  APP_UPDATE_NOT_ALLOWED = -6,
  APP_UPDATE_DOWNLOAD_NOT_PRESENT = -7,
  APP_UPDATE_IN_PROGRESS = -8,
  APP_UPDATE_PLAY_STORE_NOT_FOUND = -9,
  APP_UPDATE_APP_NOT_OWNED = -10,
  APP_UPDATE_INTERNAL_ERROR = -100,
  APP_UPDATE_INITIALIZATION_NEEDED = -110,
  APP_UPDATE_INITIALIZATION_FAILED = -111
} 		enum
Errors that can be encountered while using the in-app update API.
AppUpdateStatus{
  APP_UPDATE_STATUS_UNKNOWN = 0,
  APP_UPDATE_PENDING = 1,
  APP_UPDATE_DOWNLOADING = 2,
  APP_UPDATE_INSTALLING = 3,
  APP_UPDATE_INSTALLED = 4,
  APP_UPDATE_FAILED = 5,
  APP_UPDATE_CANCELED = 6,
  APP_UPDATE_DOWNLOADED = 11,
  APP_UPDATE_REQUEST_INFO_PENDING = 100,
  APP_UPDATE_REQUEST_INFO_FAILED = 101,
  APP_UPDATE_REQUEST_INFO_COMPLETED = 102,
  APP_UPDATE_REQUEST_START_UPDATE_PENDING = 110,
  APP_UPDATE_REQUEST_COMPLETE_UPDATE_PENDING = 120
} 		enum
Status returned when requesting an in-app update.
AppUpdateType{
  APP_UPDATE_TYPE_UNKNOWN = -1,
  APP_UPDATE_TYPE_FLEXIBLE = 0,
  APP_UPDATE_TYPE_IMMEDIATE = 1
} 		enum
Methods for performing the in-app update flow.

Typedefs
AppUpdateInfo typedef
struct AppUpdateInfo_
An opaque struct used to access information about an update.
AppUpdateOptions typedef
struct AppUpdateOptions_
An opaque struct used to provide options for an update.

Functions
AppUpdateInfo_destroy(AppUpdateInfo *info)
void
Releases the specified AppUpdateInfo and any references it holds.
AppUpdateInfo_getAvailability(AppUpdateInfo *info)
Returns the update availability for the specified AppUpdateInfo.
AppUpdateInfo_getAvailableVersionCode(AppUpdateInfo *info)
uint32_t
Returns the latest available version code for the specified AppUpdateInfo.
AppUpdateInfo_getBytesDownloaded(AppUpdateInfo *info)
uint64_t
Returns the total number in bytes already downloaded for the specified AppUpdateInfo.
AppUpdateInfo_getClientVersionStalenessDays(AppUpdateInfo *info)
int32_t
Returns the number of days that the Google Play Store app on the user's device has known about an available update.
AppUpdateInfo_getPriority(AppUpdateInfo *info)
int32_t
Returns the priority for this update, as defined by the developer in the Google Play Developer API.
AppUpdateInfo_getStatus(AppUpdateInfo *info)
Returns the update status for the specified AppUpdateInfo.
AppUpdateInfo_getTotalBytesToDownload(AppUpdateInfo *info)
uint64_t
Returns the total bytes to download for the specified AppUpdateInfo.
AppUpdateInfo_isUpdateTypeAllowed(AppUpdateInfo *info, AppUpdateOptions *options)
bool
Returns whether an update is allowed for the specified AppUpdateInfo and AppUpdateOptions.
AppUpdateManager_destroy()
void
Frees up memory allocated for the in-app update API.
AppUpdateManager_getInfo(AppUpdateInfo **out_info)
AppUpdateManager_init(JavaVM *jvm, jobject android_context)
Initialize the in-app update API, making the other functions available to call.
AppUpdateManager_onPause()
Deregisters an internal update status listener.
AppUpdateManager_onResume()
Registers an internal update status listener.
AppUpdateManager_requestCompleteUpdate()
Asynchronously requests to complete a flexible in-app update flow that was started via AppUpdateManager_requestStartUpdate().
AppUpdateManager_requestInfo()
Asynchronously requests information about an update.
AppUpdateManager_requestStartUpdate(AppUpdateInfo *info, AppUpdateOptions *options, jobject android_activity)
Asynchronously requests to start the in-app update flow.
AppUpdateOptions_createOptions(AppUpdateType type, AppUpdateOptions **out_options)
Creates a new AppUpdateOptions with the specified AppUpdateType.
AppUpdateOptions_destroy(AppUpdateOptions *options)
void
Releases the specified AppUpdateOptions and any references it holds.
AppUpdateOptions_getAppUpdateType(AppUpdateOptions *options)
Returns the update type for the specified AppUpdateOptions.
AppUpdateOptions_isAssetPackDeletionAllowed(AppUpdateOptions *options)
bool
Returns whether the app installer should be allowed to delete some asset packs from the app's storage before attempting to update the app, for example if disk space is limited.
AppUpdateOptions_setAssetPackDeletionAllowed(AppUpdateOptions *options, bool allow)
Indicates whether the app installer is allowed to delete existing asset packs while updating the app, for example if disk space is limited.

Enumerations

AppUpdateAvailability

 AppUpdateAvailability

Availability info for an in-app update.

Properties
APP_UPDATE_AVAILABLE

An update is available.

APP_UPDATE_AVAILABLILITY_UNKNOWN

Update availability is unknown.

APP_UPDATE_NOT_AVAILABLE

No updates are available.

APP_UPDATE_TRIGGERED_IN_PROGRESS

An update has been triggered by the developer and is in progress.

AppUpdateErrorCode

 AppUpdateErrorCode

Errors that can be encountered while using the in-app update API.

Properties
APP_UPDATE_API_NOT_AVAILABLE

The in-app update API isn't available on this device.

APP_UPDATE_APP_NOT_OWNED

The app isn't owned by any user on this device.

An app is "owned" if it has been acquired from the Play Store.

APP_UPDATE_DOWNLOAD_NOT_PRESENT

The update has not been (fully) downloaded yet.

APP_UPDATE_INITIALIZATION_FAILED

Error initializing dependencies.

APP_UPDATE_INITIALIZATION_NEEDED

The requested operation failed: call AppUpdateManager_init() first.

APP_UPDATE_INTERNAL_ERROR

An internal error occurred.

APP_UPDATE_INVALID_REQUEST

The function call was invalid, for example due to specifying a null parameter.

APP_UPDATE_IN_PROGRESS

The update is already in progress and there is no UI flow to resume.

APP_UPDATE_NOT_ALLOWED

The update isn't allowed due to the current device state, for example low battery or low disk space.

APP_UPDATE_NO_ERROR

No error has occurred.

APP_UPDATE_PLAY_STORE_NOT_FOUND

The Play Store app is either not installed or not the official version.

APP_UPDATE_UNAVAILABLE

The update is unavailable to this user or device.

APP_UPDATE_UNKNOWN_ERROR

An unknown error occurred.

AppUpdateStatus

 AppUpdateStatus

Status returned when requesting an in-app update.

Properties
APP_UPDATE_CANCELED

An update has been canceled.

APP_UPDATE_DOWNLOADED

An update has been fully downloaded.

APP_UPDATE_DOWNLOADING

Download of an update is in progress.

APP_UPDATE_FAILED

An update has failed.

APP_UPDATE_INSTALLED

An update has been successfully installed.

APP_UPDATE_INSTALLING

An update is being installed.

APP_UPDATE_PENDING

Download of an update is pending and will be processed soon.

APP_UPDATE_REQUEST_COMPLETE_UPDATE_PENDING

Request for completing an update is pending and will be processed soon.

APP_UPDATE_REQUEST_INFO_COMPLETED

Request for update info has completed.

APP_UPDATE_REQUEST_INFO_FAILED

Request for update info has failed.

APP_UPDATE_REQUEST_INFO_PENDING

Request for update info is pending and will be processed soon.

APP_UPDATE_REQUEST_START_UPDATE_PENDING

Request for starting an update is pending and will be processed soon.

APP_UPDATE_STATUS_UNKNOWN

The update status is unknown.

AppUpdateType

 AppUpdateType

Methods for performing the in-app update flow.

Note: regardless of the method selected, the app needs to be restarted to install an update.

Properties
APP_UPDATE_TYPE_FLEXIBLE

Flexible update flow, where the user can still use the app while the update is downloaded.

APP_UPDATE_TYPE_IMMEDIATE

Immediate update flow, where the user is unable to interact with the app while the update is downloaded and installed.

APP_UPDATE_TYPE_UNKNOWN

The app update type is unknown or unspecified.

Typedefs

AppUpdateInfo

struct AppUpdateInfo_ AppUpdateInfo

An opaque struct used to access information about an update.

AppUpdateOptions

struct AppUpdateOptions_ AppUpdateOptions

An opaque struct used to provide options for an update.

Functions

AppUpdateInfo_destroy

void AppUpdateInfo_destroy(
  AppUpdateInfo *info
)

Releases the specified AppUpdateInfo and any references it holds.

Except for rare cases, this function doesn't make JNI calls and can be called every frame.

Details
Parameters
info
The AppUpdateInfo to free.

AppUpdateInfo_getAvailability

AppUpdateAvailability AppUpdateInfo_getAvailability(
  AppUpdateInfo *info
)

Returns the update availability for the specified AppUpdateInfo.

Details
Parameters
info
The AppUpdateInfo for which to get update availability.
Returns
The update availability, for example APP_UPDATE_AVAILABLE.

AppUpdateInfo_getAvailableVersionCode

uint32_t AppUpdateInfo_getAvailableVersionCode(
  AppUpdateInfo *info
)

Returns the latest available version code for the specified AppUpdateInfo.

Details
Parameters
info
The AppUpdateInfo for which to get available version code.
Returns
The available version code for the update, or 0 if unknown.

AppUpdateInfo_getBytesDownloaded

uint64_t AppUpdateInfo_getBytesDownloaded(
  AppUpdateInfo *info
)

Returns the total number in bytes already downloaded for the specified AppUpdateInfo.

Details
Parameters
info
The AppUpdateInfo for which to get bytes downloaded.
Returns
The total number of bytes already downloaded.

AppUpdateInfo_getClientVersionStalenessDays

int32_t AppUpdateInfo_getClientVersionStalenessDays(
  AppUpdateInfo *info
)

Returns the number of days that the Google Play Store app on the user's device has known about an available update.

Details
Parameters
info
The AppUpdateInfo for which to get client version staleness.
Returns
The number of days an app update has been available, or -1 if unknown or unavailable.

AppUpdateInfo_getPriority

int32_t AppUpdateInfo_getPriority(
  AppUpdateInfo *info
)

Returns the priority for this update, as defined by the developer in the Google Play Developer API.

Details
Parameters
info
The AppUpdateInfo for which to get update priority.
Returns
The update priority, or 0 if unknown or unavailable.

AppUpdateInfo_getStatus

AppUpdateStatus AppUpdateInfo_getStatus(
  AppUpdateInfo *info
)

Returns the update status for the specified AppUpdateInfo.

Details
Parameters
info
The AppUpdateInfo for which to get update status.
Returns
The update status, for example APP_UPDATE_REQUEST_INFO_PENDING.

AppUpdateInfo_getTotalBytesToDownload

uint64_t AppUpdateInfo_getTotalBytesToDownload(
  AppUpdateInfo *info
)

Returns the total bytes to download for the specified AppUpdateInfo.

Details
Parameters
info
The AppUpdateInfo for which to get the total bytes to download.
Returns
The total size in bytes for the update, or 0 if unknown.

AppUpdateInfo_isUpdateTypeAllowed

bool AppUpdateInfo_isUpdateTypeAllowed(
  AppUpdateInfo *info,
  AppUpdateOptions *options
)

Returns whether an update is allowed for the specified AppUpdateInfo and AppUpdateOptions.

This function's result can be checked prior to calling AppUpdateManager_requestStartUpdate().

Details
Parameters
info
An AppUpdateInfo to check for whether an update is allowed.
options
The AppUpdateOptions specifying the update flow type.
Returns
True if the specified update options are allowed, or false if either the update isn't allowed or if there is an error, for example due to invalid parameters.

AppUpdateManager_destroy

void AppUpdateManager_destroy()

Frees up memory allocated for the in-app update API.

Does nothing if AppUpdateManager_init() hasn't been called.

AppUpdateManager_getInfo

AppUpdateErrorCode AppUpdateManager_getInfo(
  AppUpdateInfo **out_info
)

Gets the result of an ongoing or completed call to AppUpdateManager_requestInfo(), AppUpdateManager_requestStartUpdate(), or AppUpdateManager_requestCompleteUpdate().

This function doesn't make JNI calls and can be called every frame to monitor progress. See also:AppUpdateInfo_destroy

Details
Parameters
out_info
An out parameter for receiving the result.
Returns
APP_UPDATE_NO_ERROR if the request is ongoing or successful, or an error indicating why in-app update may not currently be possible.

AppUpdateManager_init

AppUpdateErrorCode AppUpdateManager_init(
  JavaVM *jvm,
  jobject android_context
)

Initialize the in-app update API, making the other functions available to call.

See also: AppUpdateManager_destroy

Details
Parameters
jvm
The app's single JavaVM, which can be obtained from ANativeActivity's "vm" field.
android_context
An Android Context, which can be obtained from ANativeActivity's "clazz" field.
Returns
APP_UPDATE_NO_ERROR if initialization succeeded, or an error if not.

AppUpdateManager_onPause

AppUpdateErrorCode AppUpdateManager_onPause()

Deregisters an internal update status listener.

Must be called in ANativeActivity ANativeActivityCallbacks's onPause, or equivalent.

Details
Returns
APP_UPDATE_NO_ERROR if the call succeeded, or an error if not.

AppUpdateManager_onResume

AppUpdateErrorCode AppUpdateManager_onResume()

Registers an internal update status listener.

Must be called in ANativeActivity ANativeActivityCallbacks's onResume, or equivalent.

Details
Returns
APP_UPDATE_NO_ERROR if the call succeeded, or an error if not.

AppUpdateManager_requestCompleteUpdate

AppUpdateErrorCode AppUpdateManager_requestCompleteUpdate()

Asynchronously requests to complete a flexible in-app update flow that was started via AppUpdateManager_requestStartUpdate().

This function can be called after the update reaches the APP_UPDATE_DOWNLOADED status. After calling this function the system installer will close the app, perform the update, and then restart the app at the updated version.

Details
Returns
APP_UPDATE_NO_ERROR if the update completion request started successfully, or an error if not.

AppUpdateManager_requestInfo

AppUpdateErrorCode AppUpdateManager_requestInfo()

Asynchronously requests information about an update.

Needs to be called once before AppUpdateManager_requestStartUpdate() to obtain an AppUpdateInfo, which is required to launch the in-app update flow.

Use AppUpdateManager_getInfo() to poll for the result.

Note: this function isn't idempotent and restarts the request on every call.

Details
Returns
APP_UPDATE_NO_ERROR if the request started successfully, or an error if not.

AppUpdateManager_requestStartUpdate

AppUpdateErrorCode AppUpdateManager_requestStartUpdate(
  AppUpdateInfo *info,
  AppUpdateOptions *options,
  jobject android_activity
)

Asynchronously requests to start the in-app update flow.

Use AppUpdateManager_getInfo() to monitor the current status and download progress of the ongoing asynchronous update operation.

Details
Parameters
info
The AppUpdateInfo containing information needed for an update.
options
The AppUpdateOptions specifying the update flow type.
android_activity
An Android Activity, which can be obtained from ANativeActivity's "clazz" field.
Returns
APP_UPDATE_NO_ERROR if the request started successfully, or an error if not.

AppUpdateOptions_createOptions

AppUpdateErrorCode AppUpdateOptions_createOptions(
  AppUpdateType type,
  AppUpdateOptions **out_options
)

Creates a new AppUpdateOptions with the specified AppUpdateType.

See also: AppUpdateOptions_destroy

Details
Parameters
type
The AppUpdateType specifying the update flow type.
out_options
An out parameter to store the created AppUpdateOptions.
Returns
APP_UPDATE_NO_ERROR if an AppUpdateOptions is created successfully, or an error if not.

AppUpdateOptions_destroy

void AppUpdateOptions_destroy(
  AppUpdateOptions *options
)

Releases the specified AppUpdateOptions and any references it holds.

Details
Parameters
options
The AppUpdateOptions to free.

AppUpdateOptions_getAppUpdateType

AppUpdateType AppUpdateOptions_getAppUpdateType(
  AppUpdateOptions *options
)

Returns the update type for the specified AppUpdateOptions.

Details
Parameters
options
The AppUpdateOptions for which to get the update type.
Returns
The type of app update flow.

AppUpdateOptions_isAssetPackDeletionAllowed

bool AppUpdateOptions_isAssetPackDeletionAllowed(
  AppUpdateOptions *options
)

Returns whether the app installer should be allowed to delete some asset packs from the app's storage before attempting to update the app, for example if disk space is limited.

Details
Parameters
options
The AppUpdateOptions specifying the update flow type.
Returns
Bool indicating whether the app installer should be allowed to delete asset packs (if necessary) during an app update.

AppUpdateOptions_setAssetPackDeletionAllowed

AppUpdateErrorCode AppUpdateOptions_setAssetPackDeletionAllowed(
  AppUpdateOptions *options,
  bool allow
)

Indicates whether the app installer is allowed to delete existing asset packs while updating the app, for example if disk space is limited.

Details
Parameters
options
The AppUpdateOptions on which to configure this setting.
allow
Boolean indicating whether the app installer is allowed to delete asset packs (if necessary) during an app update.
Returns
APP_UPDATE_NO_ERROR if the value is set successfully, or an error if not.