# Print output for @column tags ?> PackageInstaller - Android SDK | Android Developers
Developer Console

Most visited

Recently visited

Results for

PackageInstaller

public class PackageInstaller
extends Object

java.lang.Object
   ↳ android.content.pm.PackageInstaller

Offers the ability to install, upgrade, and remove applications on the device. This includes support for apps packaged either as a single "monolithic" APK, or apps packaged as multiple "split" APKs.

An app is delivered for installation through a PackageInstaller.Session, which any app can create. Once the session is created, the installer can stream one or more APKs into place until it decides to either commit or destroy the session. Committing may require user intervention to complete the installation, unless the caller falls into one of the following categories, in which case the installation will complete automatically.

  • the device owner
  • the affiliated profile owner

Sessions can install brand new apps, upgrade existing apps, or add new splits into an existing app.

Apps packaged as multiple split APKs always consist of a single "base" APK (with a null split name) and zero or more "split" APKs (with unique split names). Any subset of these APKs can be installed together, as long as the following constraints are met:

  • All APKs must have the exact same package name, version code, and signing certificates.
  • All APKs must have unique split names.
  • All installations must contain a single base APK.

The ApiDemos project contains examples of using this API: ApiDemos/src/com/example/android/apis/content/InstallApk*.java.

Summary

Nested classes

class PackageInstaller.Session

An installation that is being actively staged. 

class PackageInstaller.SessionCallback

Events for observing session lifecycle. 

class PackageInstaller.SessionInfo

Details for an active install session. 

class PackageInstaller.SessionParams

Parameters for creating a new PackageInstaller.Session. 

Constants

String ACTION_SESSION_COMMITTED

Broadcast Action: Explicit broadcast sent to the last known default launcher when a session for a new install is committed.

String ACTION_SESSION_DETAILS

Activity Action: Show details about a particular install session.

String ACTION_SESSION_UPDATED

Broadcast Action: Send information about a staged install session when its state is updated.

String EXTRA_OTHER_PACKAGE_NAME

Another package name relevant to a status.

String EXTRA_PACKAGE_NAME

Package name that an operation is working with.

String EXTRA_SESSION

SessionInfo that an operation is working with.

String EXTRA_SESSION_ID

An integer session ID that an operation is working with.

String EXTRA_STATUS

Current status of an operation.

String EXTRA_STATUS_MESSAGE

Detailed string representation of the status, including raw details that are useful for debugging.

String EXTRA_STORAGE_PATH

Storage path relevant to a status.

int STATUS_FAILURE

The operation failed in a generic way.

int STATUS_FAILURE_ABORTED

The operation failed because it was actively aborted.

int STATUS_FAILURE_BLOCKED

The operation failed because it was blocked.

int STATUS_FAILURE_CONFLICT

The operation failed because it conflicts (or is inconsistent with) with another package already installed on the device.

int STATUS_FAILURE_INCOMPATIBLE

The operation failed because it is fundamentally incompatible with this device.

int STATUS_FAILURE_INVALID

The operation failed because one or more of the APKs was invalid.

int STATUS_FAILURE_STORAGE

The operation failed because of storage issues.

int STATUS_PENDING_USER_ACTION

User action is currently required to proceed.

int STATUS_SUCCESS

The operation succeeded.

Public methods

void abandonSession(int sessionId)

Completely abandon the given session, destroying all staged data and rendering it invalid.

int createSession(PackageInstaller.SessionParams params)

Create a new session using the given parameters, returning a unique ID that represents the session.

PackageInstaller.SessionInfo getActiveStagedSession()

This method is deprecated. Use getActiveStagedSessions() as there can be more than one active staged session

List<PackageInstaller.SessionInfo> getActiveStagedSessions()

Returns list of active staged sessions.

List<PackageInstaller.SessionInfo> getAllSessions()

Return list of all known install sessions, regardless of the installer.

List<PackageInstaller.SessionInfo> getMySessions()

Return list of all known install sessions owned by the calling app.

PackageInstaller.SessionInfo getSessionInfo(int sessionId)

Return details for a specific session.

List<PackageInstaller.SessionInfo> getStagedSessions()

Return list of all staged install sessions.

void installExistingPackage(String packageName, int installReason, IntentSender statusReceiver)

Install the given package, which already exists on the device, for the user for which this installer was created.

PackageInstaller.Session openSession(int sessionId)

Open an existing session to actively perform work.

void registerSessionCallback(PackageInstaller.SessionCallback callback, Handler handler)

Register to watch for session lifecycle events.

void registerSessionCallback(PackageInstaller.SessionCallback callback)

Register to watch for session lifecycle events.

void uninstall(VersionedPackage versionedPackage, IntentSender statusReceiver)

Uninstall the given package with a specific version code, removing it completely from the device.

void uninstall(String packageName, IntentSender statusReceiver)

Uninstall the given package, removing it completely from the device.

void unregisterSessionCallback(PackageInstaller.SessionCallback callback)

Unregister a previously registered callback.

void updateSessionAppIcon(int sessionId, Bitmap appIcon)

Update the icon representing the app being installed in a specific session.

void updateSessionAppLabel(int sessionId, CharSequence appLabel)

Update the label representing the app being installed in a specific session.

Inherited methods

Constants

ACTION_SESSION_COMMITTED

public static final String ACTION_SESSION_COMMITTED

Broadcast Action: Explicit broadcast sent to the last known default launcher when a session for a new install is committed. For managed profile, this is sent to the default launcher of the primary profile.

The associated session is defined in EXTRA_SESSION and the user for which this session was created in Intent#EXTRA_USER.

Constant Value: "android.content.pm.action.SESSION_COMMITTED"

ACTION_SESSION_DETAILS

public static final String ACTION_SESSION_DETAILS

Activity Action: Show details about a particular install session. This may surface actions such as pause, resume, or cancel.

This should always be scoped to the installer package that owns the session. Clients should use SessionInfo#createDetailsIntent() to build this intent correctly.

In some cases, a matching Activity may not exist, so ensure you safeguard against this.

The session to show details for is defined in EXTRA_SESSION_ID.

Constant Value: "android.content.pm.action.SESSION_DETAILS"

ACTION_SESSION_UPDATED

public static final String ACTION_SESSION_UPDATED

Broadcast Action: Send information about a staged install session when its state is updated.

The associated session information is defined in EXTRA_SESSION.

Constant Value: "android.content.pm.action.SESSION_UPDATED"

EXTRA_OTHER_PACKAGE_NAME

public static final String EXTRA_OTHER_PACKAGE_NAME

Another package name relevant to a status. This is typically the package responsible for causing an operation failure.

See also:

Constant Value: "android.content.pm.extra.OTHER_PACKAGE_NAME"

EXTRA_PACKAGE_NAME

public static final String EXTRA_PACKAGE_NAME

Package name that an operation is working with.

See also:

Constant Value: "android.content.pm.extra.PACKAGE_NAME"

EXTRA_SESSION

public static final String EXTRA_SESSION

SessionInfo that an operation is working with.

See also:

Constant Value: "android.content.pm.extra.SESSION"

EXTRA_SESSION_ID

public static final String EXTRA_SESSION_ID

An integer session ID that an operation is working with.

See also:

Constant Value: "android.content.pm.extra.SESSION_ID"

EXTRA_STATUS

public static final String EXTRA_STATUS

Current status of an operation. Will be one of STATUS_PENDING_USER_ACTION, STATUS_SUCCESS, STATUS_FAILURE, STATUS_FAILURE_ABORTED, STATUS_FAILURE_BLOCKED, STATUS_FAILURE_CONFLICT, STATUS_FAILURE_INCOMPATIBLE, STATUS_FAILURE_INVALID, or STATUS_FAILURE_STORAGE.

More information about a status may be available through additional extras; see the individual status documentation for details.

See also:

Constant Value: "android.content.pm.extra.STATUS"

EXTRA_STATUS_MESSAGE

public static final String EXTRA_STATUS_MESSAGE

Detailed string representation of the status, including raw details that are useful for debugging.

See also:

Constant Value: "android.content.pm.extra.STATUS_MESSAGE"

EXTRA_STORAGE_PATH

public static final String EXTRA_STORAGE_PATH

Storage path relevant to a status.

See also:

Constant Value: "android.content.pm.extra.STORAGE_PATH"

STATUS_FAILURE

public static final int STATUS_FAILURE

The operation failed in a generic way. The system will always try to provide a more specific failure reason, but in some rare cases this may be delivered.

See also:

Constant Value: 1 (0x00000001)

STATUS_FAILURE_ABORTED

public static final int STATUS_FAILURE_ABORTED

The operation failed because it was actively aborted. For example, the user actively declined requested permissions, or the session was abandoned.

See also:

Constant Value: 3 (0x00000003)

STATUS_FAILURE_BLOCKED

public static final int STATUS_FAILURE_BLOCKED

The operation failed because it was blocked. For example, a device policy may be blocking the operation, a package verifier may have blocked the operation, or the app may be required for core system operation.

The result may also contain EXTRA_OTHER_PACKAGE_NAME with the specific package blocking the install.

See also:

Constant Value: 2 (0x00000002)

STATUS_FAILURE_CONFLICT

public static final int STATUS_FAILURE_CONFLICT

The operation failed because it conflicts (or is inconsistent with) with another package already installed on the device. For example, an existing permission, incompatible certificates, etc. The user may be able to uninstall another app to fix the issue.

The result may also contain EXTRA_OTHER_PACKAGE_NAME with the specific package identified as the cause of the conflict.

See also:

Constant Value: 5 (0x00000005)

STATUS_FAILURE_INCOMPATIBLE

public static final int STATUS_FAILURE_INCOMPATIBLE

The operation failed because it is fundamentally incompatible with this device. For example, the app may require a hardware feature that doesn't exist, it may be missing native code for the ABIs supported by the device, or it requires a newer SDK version, etc.

See also:

Constant Value: 7 (0x00000007)

STATUS_FAILURE_INVALID

public static final int STATUS_FAILURE_INVALID

The operation failed because one or more of the APKs was invalid. For example, they might be malformed, corrupt, incorrectly signed, mismatched, etc.

See also:

Constant Value: 4 (0x00000004)

STATUS_FAILURE_STORAGE

public static final int STATUS_FAILURE_STORAGE

The operation failed because of storage issues. For example, the device may be running low on space, or external media may be unavailable. The user may be able to help free space or insert different external media.

The result may also contain EXTRA_STORAGE_PATH with the path to the storage device that caused the failure.

See also:

Constant Value: 6 (0x00000006)

STATUS_PENDING_USER_ACTION

public static final int STATUS_PENDING_USER_ACTION

User action is currently required to proceed. You can launch the intent activity described by Intent#EXTRA_INTENT to involve the user and continue.

You may choose to immediately launch the intent if the user is actively using your app. Otherwise, you should use a notification to guide the user back into your app before launching.

See also:

Constant Value: -1 (0xffffffff)

STATUS_SUCCESS

public static final int STATUS_SUCCESS

The operation succeeded.

Constant Value: 0 (0x00000000)

Public methods

abandonSession

public void abandonSession (int sessionId)

Completely abandon the given session, destroying all staged data and rendering it invalid. Abandoned sessions will be reported to SessionCallback listeners as failures. This is equivalent to opening the session and calling Session#abandon().

Parameters
sessionId int

Throws
SecurityException when the caller does not own the session, or the session is invalid.

createSession

public int createSession (PackageInstaller.SessionParams params)

Create a new session using the given parameters, returning a unique ID that represents the session. Once created, the session can be opened multiple times across multiple device boots.

The system may automatically destroy sessions that have not been finalized (either committed or abandoned) within a reasonable period of time, typically on the order of a day.

Parameters
params PackageInstaller.SessionParams: This value cannot be null.
Returns
int positive, non-zero unique ID that represents the created session. This ID remains consistent across device reboots until the session is finalized. IDs are not reused during a given boot.
Throws
IOException if parameters were unsatisfiable, such as lack of disk space or unavailable media.
SecurityException when installation services are unavailable, such as when called from a restricted user.
IllegalArgumentException when SessionParams is invalid.

getActiveStagedSession

public PackageInstaller.SessionInfo getActiveStagedSession ()

This method is deprecated.
Use getActiveStagedSessions() as there can be more than one active staged session

Returns first active staged session, or null if there is none.

For more information on what sessions are considered active see SessionInfo#isStagedSessionActive().

Returns
PackageInstaller.SessionInfo

getActiveStagedSessions

public List<PackageInstaller.SessionInfo> getActiveStagedSessions ()

Returns list of active staged sessions. Returns empty list if there is none.

For more information on what sessions are considered active see * SessionInfo#isStagedSessionActive().

Returns
List<PackageInstaller.SessionInfo> This value cannot be null.

getAllSessions

public List<PackageInstaller.SessionInfo> getAllSessions ()

Return list of all known install sessions, regardless of the installer.

Returns
List<PackageInstaller.SessionInfo> This value cannot be null.

getMySessions

public List<PackageInstaller.SessionInfo> getMySessions ()

Return list of all known install sessions owned by the calling app.

Returns
List<PackageInstaller.SessionInfo> This value cannot be null.

getSessionInfo

public PackageInstaller.SessionInfo getSessionInfo (int sessionId)

Return details for a specific session. No special permissions are required to retrieve these details.

Parameters
sessionId int

Returns
PackageInstaller.SessionInfo details for the requested session, or null if the session does not exist.

getStagedSessions

public List<PackageInstaller.SessionInfo> getStagedSessions ()

Return list of all staged install sessions.

Returns
List<PackageInstaller.SessionInfo> This value cannot be null.

installExistingPackage

public void installExistingPackage (String packageName, 
                int installReason, 
                IntentSender statusReceiver)

Install the given package, which already exists on the device, for the user for which this installer was created.

This will PackageInstaller.SessionParams#setWhitelistedRestrictedPermissions(Set).
Requires Manifest.permission.INSTALL_PACKAGES and android.Manifest.permission.INSTALL_EXISTING_PACKAGES

Parameters
packageName String: The package to install. This value cannot be null.
installReason int: Reason for install. Value is PackageManager.INSTALL_REASON_UNKNOWN, PackageManager.INSTALL_REASON_POLICY, PackageManager.INSTALL_REASON_DEVICE_RESTORE, PackageManager.INSTALL_REASON_DEVICE_SETUP, PackageManager.INSTALL_REASON_USER, or android.content.pm.PackageManager.INSTALL_REASON_ROLLBACK
statusReceiver IntentSender: Where to deliver the result. This value may be null.

openSession

public PackageInstaller.Session openSession (int sessionId)

Open an existing session to actively perform work. To succeed, the caller must be the owner of the install session.

Parameters
sessionId int

Returns
PackageInstaller.Session This value cannot be null.
Throws
IOException if parameters were unsatisfiable, such as lack of disk space or unavailable media.
SecurityException when the caller does not own the session, or the session is invalid.

registerSessionCallback

public void registerSessionCallback (PackageInstaller.SessionCallback callback, 
                Handler handler)

Register to watch for session lifecycle events. No special permissions are required to watch for these events.

Parameters
callback PackageInstaller.SessionCallback: This value cannot be null.
handler Handler: to dispatch callback events through, otherwise uses calling thread. This value cannot be null.

registerSessionCallback

public void registerSessionCallback (PackageInstaller.SessionCallback callback)

Register to watch for session lifecycle events. No special permissions are required to watch for these events.

Parameters
callback PackageInstaller.SessionCallback: This value cannot be null.

uninstall

public void uninstall (VersionedPackage versionedPackage, 
                IntentSender statusReceiver)

Uninstall the given package with a specific version code, removing it completely from the device. If the version code of the package does not match the one passed in the versioned package argument this method is a no-op. Use PackageManager#VERSION_CODE_HIGHEST to uninstall the latest version of the package.

This method is available to:

  • the current "installer of record" for the package
  • the device owner
  • the affiliated profile owner

Requires Manifest.permission.DELETE_PACKAGES or Manifest.permission.REQUEST_DELETE_PACKAGES

Parameters
versionedPackage VersionedPackage: The versioned package to uninstall. This value cannot be null.
statusReceiver IntentSender: Where to deliver the result. This value cannot be null.

See also:

uninstall

public void uninstall (String packageName, 
                IntentSender statusReceiver)

Uninstall the given package, removing it completely from the device. This method is available to:

  • the current "installer of record" for the package
  • the device owner
  • the affiliated profile owner

Requires Manifest.permission.DELETE_PACKAGES or Manifest.permission.REQUEST_DELETE_PACKAGES

Parameters
packageName String: The package to uninstall. This value cannot be null.
statusReceiver IntentSender: Where to deliver the result. This value cannot be null.

See also:

unregisterSessionCallback

public void unregisterSessionCallback (PackageInstaller.SessionCallback callback)

Unregister a previously registered callback.

Parameters
callback PackageInstaller.SessionCallback: This value cannot be null.

updateSessionAppIcon

public void updateSessionAppIcon (int sessionId, 
                Bitmap appIcon)

Update the icon representing the app being installed in a specific session. This should be roughly ActivityManager#getLauncherLargeIconSize() in both dimensions.

Parameters
sessionId int

appIcon Bitmap: This value may be null.
Throws
SecurityException when the caller does not own the session, or the session is invalid.

updateSessionAppLabel

public void updateSessionAppLabel (int sessionId, 
                CharSequence appLabel)

Update the label representing the app being installed in a specific session.

Parameters
sessionId int

appLabel CharSequence: This value may be null.
Throws
SecurityException when the caller does not own the session, or the session is invalid.
Get news & tips
Blog Support

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.

Android 7.0 r1 —

About Android Auto TV Wear Legal