Added in API level 21

Summary: Constants | Inherited Constants | Fields | Ctors | Methods | Inherited Methods

PackageInstaller.SessionParams

---

Kotlin |Java

public static class PackageInstaller.SessionParams
extends Object implements Parcelable

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

---

Parameters for creating a new PackageInstaller.Session.

Summary

Constants
int	MODE_FULL_INSTALL Mode for an install session whose staged APKs should fully replace any existing APKs for the target app.
int	MODE_INHERIT_EXISTING Mode for an install session that should inherit any existing APKs for the target app, unless they have been explicitly overridden (based on split name) by the session.
int	PERMISSION_STATE_DEFAULT Value is passed by the installer to setPermissionState(java.lang.String, int) to set the state of a permission.
int	PERMISSION_STATE_DENIED Value is passed by the installer to setPermissionState(java.lang.String, int) to set the state of a permission.
int	PERMISSION_STATE_GRANTED Value is passed by the installer to setPermissionState(java.lang.String, int) to set the state of a permission.
int	USER_ACTION_NOT_REQUIRED This value is passed by the installer to SessionParams#setRequireUserAction(int) to indicate that user action is not required for this install.
int	USER_ACTION_REQUIRED This value is passed by the installer to SessionParams#setRequireUserAction(int) to indicate that user action is required for this install.
int	USER_ACTION_UNSPECIFIED This value is passed by the installer to SessionParams#setRequireUserAction(int) to indicate that user action is unspecified for this install.

Inherited constants

From interface android.os.Parcelable int CONTENTS_FILE_DESCRIPTOR Descriptor bit used with describeContents(): indicates that the Parcelable object's flattened representation includes a file descriptor. int PARCELABLE_WRITE_RETURN_VALUE Flag for use with writeToParcel(Parcel, int): the object being written is a return value, that is the result of a function such as "Parcelable someFunction()", "void someFunction(out Parcelable)", or "void someFunction(inout Parcelable)".

Fields
public static final Creator<PackageInstaller.SessionParams>	CREATOR
public static final Set<String>	RESTRICTED_PERMISSIONS_ALL Special constant to refer to all restricted permissions.

Public constructors
SessionParams(int mode) Construct parameters for a new package install session.

Public methods
int	describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
void	setAppIcon(Bitmap appIcon) Optionally set an icon representing the app being installed.
void	setAppLabel(CharSequence appLabel) Optionally set a label representing the app being installed.
void	setAppPackageName(String appPackageName) Optionally set the package name of the app being installed.
void	setApplicationEnabledSettingPersistent() Request to keep the original application enabled setting.
void	setAutoRevokePermissionsMode(boolean shouldAutoRevoke) This method was deprecated in API level 31. No longer used
void	setDontKillApp(boolean dontKillApp) Requests that the system not kill any of the package's running processes as part of a SessionParams#MODE_INHERIT_EXISTING session in which splits being added.
void	setInstallLocation(int installLocation) Provide value of PackageInfo#installLocation, which may be used to determine where the app will be staged.
void	setInstallReason(int installReason) Set the reason for installing this package.
void	setInstallScenario(int installScenario) Sets the install scenario for this session, which describes the expected user journey.
void	setInstallerPackageName(String installerPackageName) Set the installer package for the app.
void	setMultiPackage() Set this session to be the parent of a multi-package install.
void	setOriginatingUid(int originatingUid) Sets the UID that initiated the package installation.
void	setOriginatingUri(Uri originatingUri) Optionally set the URI where this package was downloaded from.
void	setPackageSource(int packageSource) Optionally indicate the package source of the app being installed.
PackageInstaller.SessionParams	setPermissionState(String permissionName, int state) Sets the state of permissions for the package at installation.
void	setReferrerUri(Uri referrerUri) Optionally set the URI that referred you to install this package.
void	setRequestUpdateOwnership(boolean enable) Optionally indicate whether the package being installed needs the update ownership enforcement.
void	setRequireUserAction(int requireUserAction) Optionally indicate whether user action should be required when the session is committed.
void	setSize(long sizeBytes) Optionally indicate the total size (in bytes) of all APKs that will be delivered in this session.
void	setUnarchiveId(int unarchiveId) Used to set the unarchive ID received as part of an Intent#ACTION_UNARCHIVE_PACKAGE.
void	setWhitelistedRestrictedPermissions(Set<String> permissions) Sets which restricted permissions to be allowlisted for the app.
void	writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface android.os.Parcelable abstract int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. abstract void writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Constants

MODE_FULL_INSTALL

Added in API level 21

public static final int MODE_FULL_INSTALL

Mode for an install session whose staged APKs should fully replace any existing APKs for the target app.

Constant Value: 1 (0x00000001)

MODE_INHERIT_EXISTING

Added in API level 21

public static final int MODE_INHERIT_EXISTING

Mode for an install session that should inherit any existing APKs for the target app, unless they have been explicitly overridden (based on split name) by the session. For example, this can be used to add one or more split APKs to an existing installation.

If there are no existing APKs for the target app, this behaves like MODE_FULL_INSTALL.

Constant Value: 2 (0x00000002)

PERMISSION_STATE_DEFAULT

Added in API level 34

public static final int PERMISSION_STATE_DEFAULT

Value is passed by the installer to setPermissionState(java.lang.String, int) to set the state of a permission. This indicates no preference by the installer, relying on the device's default policy to set the grant state of the permission.

Constant Value: 0 (0x00000000)

PERMISSION_STATE_DENIED

Added in API level 34

public static final int PERMISSION_STATE_DENIED

Value is passed by the installer to setPermissionState(java.lang.String, int) to set the state of a permission. This indicates the installers wants to deny the permission by default to the package being installed. The user and other actors in the system may still be able to grant the permission after installation.

Constant Value: 2 (0x00000002)

PERMISSION_STATE_GRANTED

Added in API level 34

public static final int PERMISSION_STATE_GRANTED

Value is passed by the installer to setPermissionState(java.lang.String, int) to set the state of a permission. This indicates the installers wants to automatically grant the permission to the package being installed. The user and other actors in the system may still be able to deny the permission after installation.

Constant Value: 1 (0x00000001)

USER_ACTION_NOT_REQUIRED

Added in API level 31

public static final int USER_ACTION_NOT_REQUIRED

This value is passed by the installer to SessionParams#setRequireUserAction(int) to indicate that user action is not required for this install.

Constant Value: 2 (0x00000002)

USER_ACTION_REQUIRED

Added in API level 31

public static final int USER_ACTION_REQUIRED

This value is passed by the installer to SessionParams#setRequireUserAction(int) to indicate that user action is required for this install.

Constant Value: 1 (0x00000001)

USER_ACTION_UNSPECIFIED

Added in API level 31

public static final int USER_ACTION_UNSPECIFIED

This value is passed by the installer to SessionParams#setRequireUserAction(int) to indicate that user action is unspecified for this install. requireUserAction also defaults to this value unless modified by SessionParams#setRequireUserAction(int)

Constant Value: 0 (0x00000000)

Fields

CREATOR

Added in API level 21

public static final Creator<PackageInstaller.SessionParams> CREATOR

RESTRICTED_PERMISSIONS_ALL

Added in API level 29

public static final Set<String> RESTRICTED_PERMISSIONS_ALL

Special constant to refer to all restricted permissions.

Public constructors

SessionParams

Added in API level 21

public SessionParams (int mode)

Construct parameters for a new package install session.

Parameters
mode	int: one of MODE_FULL_INSTALL or MODE_INHERIT_EXISTING describing how the session should interact with an existing app.

Public methods

describeContents

Added in API level 21

public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int	a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or CONTENTS_FILE_DESCRIPTOR

setAppIcon

Added in API level 21

public void setAppIcon (Bitmap appIcon)

Optionally set an icon representing the app being installed. This should be roughly ActivityManager#getLauncherLargeIconSize() in both dimensions.

Parameters
appIcon	Bitmap: This value may be null.

setAppLabel

Added in API level 21

public void setAppLabel (CharSequence appLabel)

Optionally set a label representing the app being installed. This value will be trimmed to the first 1000 characters.

Parameters
appLabel	CharSequence: This value may be null.

setAppPackageName

Added in API level 21

public void setAppPackageName (String appPackageName)

Optionally set the package name of the app being installed. It's strongly recommended that you provide this value when known, so that observers can communicate installing apps to users.

If the APKs staged in the session aren't consistent with this package name, the install will fail. Regardless of this value, all APKs in the app must have the same package name.

Parameters
appPackageName	String: This value may be null.

setApplicationEnabledSettingPersistent

Added in API level 34

public void setApplicationEnabledSettingPersistent ()

Request to keep the original application enabled setting. This will prevent the application from being enabled if it was previously in a disabled state.

setAutoRevokePermissionsMode

Added in API level 30
Deprecated in API level 31

public void setAutoRevokePermissionsMode (boolean shouldAutoRevoke)

This method was deprecated in API level 31.
No longer used

Sets whether permissions should be auto-revoked if this package is unused for an extended periodd of time. It's disabled by default but generally the installer should enable it for most packages, excluding only those where doing so might cause breakage that cannot be easily addressed by simply re-requesting the permission(s). If user explicitly enabled or disabled it via settings, this call is ignored.

Parameters
shouldAutoRevoke	boolean: whether permissions should be auto-revoked.

setDontKillApp

Added in API level 34

public void setDontKillApp (boolean dontKillApp)

Requests that the system not kill any of the package's running processes as part of a SessionParams#MODE_INHERIT_EXISTING session in which splits being added. By default, all installs will result in the package's running processes being killed before the install completes.

Parameters
dontKillApp	boolean: set to true to request that the processes belonging to the package not be killed as part of this install.

setInstallLocation

Added in API level 21

public void setInstallLocation (int installLocation)

Provide value of PackageInfo#installLocation, which may be used to determine where the app will be staged. Defaults to PackageInfo#INSTALL_LOCATION_INTERNAL_ONLY.

Parameters
installLocation	int

setInstallReason

Added in API level 26

public void setInstallReason (int installReason)

Set the reason for installing this package.

The install reason should be a pre-defined integer. The behavior is undefined if other values are used.

Parameters
installReason	int: 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

See also:

• PackageManager.INSTALL_REASON_UNKNOWN
• PackageManager.INSTALL_REASON_POLICY
• PackageManager.INSTALL_REASON_DEVICE_RESTORE
• PackageManager.INSTALL_REASON_DEVICE_SETUP
• PackageManager.INSTALL_REASON_USER

setInstallScenario

Added in API level 31

public void setInstallScenario (int installScenario)

Sets the install scenario for this session, which describes the expected user journey.

Parameters
installScenario	int: Value is PackageManager.INSTALL_SCENARIO_DEFAULT, PackageManager.INSTALL_SCENARIO_FAST, PackageManager.INSTALL_SCENARIO_BULK, or PackageManager.INSTALL_SCENARIO_BULK_SECONDARY

setInstallerPackageName

Added in API level 34

public void setInstallerPackageName (String installerPackageName)

Set the installer package for the app. By default this is the app that created the PackageInstaller object. Note: Only applications with Manifest.permission.INSTALL_PACKAGES permission are allowed to set an installer that is not the caller's own installer package name, otherwise it will cause a SecurityException when creating the install session.

Parameters
installerPackageName	String: The name of the installer package, its length must be less than 255, otherwise it will be invalid. This value may be null.

setMultiPackage

Added in API level 29

public void setMultiPackage ()

Set this session to be the parent of a multi-package install. A multi-package install session contains no APKs and only references other install sessions via ID. When a multi-package session is committed, all of its children are committed to the system in an atomic manner. If any children fail to install, all of them do, including the multi-package session.

setOriginatingUid

Added in API level 24

public void setOriginatingUid (int originatingUid)

Sets the UID that initiated the package installation. This is informational and may be used as a signal for anti-malware purposes.

Parameters
originatingUid	int

setOriginatingUri

Added in API level 21

public void setOriginatingUri (Uri originatingUri)

Optionally set the URI where this package was downloaded from. This is informational and may be used as a signal for anti-malware purposes.

Parameters
originatingUri	Uri: This value may be null.

See also:

• Intent.EXTRA_ORIGINATING_URI

setPackageSource

Added in API level 33

public void setPackageSource (int packageSource)

Optionally indicate the package source of the app being installed. This is informational and may be used as a signal by the system. An installer should specify PackageInstaller.PACKAGE_SOURCE_OTHER if no other package source constant adequately reflects the source for this session. The default value is PackageInstaller.PACKAGE_SOURCE_UNSPECIFIED.

Parameters
packageSource	int: Value is PackageInstaller.PACKAGE_SOURCE_UNSPECIFIED, PackageInstaller.PACKAGE_SOURCE_STORE, PackageInstaller.PACKAGE_SOURCE_LOCAL_FILE, PackageInstaller.PACKAGE_SOURCE_DOWNLOADED_FILE, or PackageInstaller.PACKAGE_SOURCE_OTHER

setPermissionState

Added in API level 34

public PackageInstaller.SessionParams setPermissionState (String permissionName, 
                int state)

Sets the state of permissions for the package at installation.

Granting any runtime permissions require the android.Manifest.permission#INSTALL_GRANT_RUNTIME_PERMISSIONS permission to be held by the caller. Revoking runtime permissions is not allowed, even during app update sessions.

Holders without the permission are allowed to change the following special permissions:

On platform UPSIDE_DOWN_CAKE:

• Manifest.permission#USE_FULL_SCREEN_INTENT

Install time permissions, which cannot be revoked by the user, cannot be changed by the installer.

See Permissions on Android for more information.

Parameters
permissionName	String: The permission to change state for. This value cannot be null.
state	int: Either PERMISSION_STATE_DEFAULT, PERMISSION_STATE_GRANTED, or PERMISSION_STATE_DENIED to set the permission to. Value is PERMISSION_STATE_DEFAULT, PERMISSION_STATE_GRANTED, or PERMISSION_STATE_DENIED

Returns
PackageInstaller.SessionParams	This object for easier chaining. This value cannot be null.

setReferrerUri

Added in API level 21

public void setReferrerUri (Uri referrerUri)

Optionally set the URI that referred you to install this package. This is informational and may be used as a signal for anti-malware purposes.

Parameters
referrerUri	Uri: This value may be null.

See also:

• Intent.EXTRA_REFERRER

setRequestUpdateOwnership

Added in API level 34

public void setRequestUpdateOwnership (boolean enable)

Optionally indicate whether the package being installed needs the update ownership enforcement. Once the update ownership enforcement is enabled, the other installers will need the user action to update the package even if the installers have been granted the INSTALL_PACKAGES permission. Default to false. The update ownership enforcement can only be enabled on initial installation. Set this to true on package update is a no-op. Note: To enable the update ownership enforcement, the installer must have the ENFORCE_UPDATE_OWNERSHIP permission.
Requires Manifest.permission.ENFORCE_UPDATE_OWNERSHIP

Parameters
enable	boolean

setRequireUserAction

Added in API level 31

public void setRequireUserAction (int requireUserAction)

Optionally indicate whether user action should be required when the session is committed.

Defaults to USER_ACTION_UNSPECIFIED unless otherwise set. When unspecified for installers using the REQUEST_INSTALL_PACKAGES permission will behave as if set to USER_ACTION_REQUIRED, and USER_ACTION_NOT_REQUIRED otherwise. When requireUserAction is set to USER_ACTION_REQUIRED, installers will receive a PackageInstaller.STATUS_PENDING_USER_ACTION callback once the session is committed, indicating that user action is required for the install to proceed.

For installers that have been granted the REQUEST_INSTALL_PACKAGES permission, user action will not be required when all of the following conditions are met:

• requireUserAction is set to USER_ACTION_NOT_REQUIRED.
• The app being installed targets:
  • API 29 or higher on Android S (API 31)
  • API 30 or higher on Android T (API 33)
  • API 31 or higher on Android U (API 34)
  • API 33 or higher on Android V (API 35)
• The installer is:
  • The update owner of an existing version of the app (in other words, this install session is an app update) if the update ownership enforcement is enabled.
  • The installer of record of an existing version of the app (in other words, this install session is an app update) if the update ownership enforcement isn't enabled.
  • Updating itself.
• The installer declares the UPDATE_PACKAGES_WITHOUT_USER_ACTION permission.

Note: The target API level requirement will advance in future Android versions. Session owners should always be prepared to handle PackageInstaller.STATUS_PENDING_USER_ACTION.

Parameters
requireUserAction	int: whether user action should be required. Value is USER_ACTION_UNSPECIFIED, USER_ACTION_REQUIRED, or USER_ACTION_NOT_REQUIRED

setSize

Added in API level 21

public void setSize (long sizeBytes)

Optionally indicate the total size (in bytes) of all APKs that will be delivered in this session. The system may use this to ensure enough disk space exists before proceeding, or to estimate container size for installations living on external storage.

Parameters
sizeBytes	long

See also:

• PackageInfo.INSTALL_LOCATION_AUTO
• PackageInfo.INSTALL_LOCATION_PREFER_EXTERNAL

setUnarchiveId

Added in API level 35

public void setUnarchiveId (int unarchiveId)

Used to set the unarchive ID received as part of an Intent#ACTION_UNARCHIVE_PACKAGE.

The ID should be retrieved from the unarchive intent and passed into the session that's being created to unarchive the app in question. Used to link the unarchive intent and the install session to disambiguate.

Parameters
unarchiveId	int

setWhitelistedRestrictedPermissions

Added in API level 29

public void setWhitelistedRestrictedPermissions (Set<String> permissions)

Sets which restricted permissions to be allowlisted for the app. Allowlisting is not granting the permissions, rather it allows the app to hold permissions which are otherwise restricted. Allowlisting a non restricted permission has no effect.

Permissions can be hard restricted which means that the app cannot hold them or soft restricted where the app can hold the permission but in a weaker form. Whether a permission is restricted or soft restricted depends on the permission declaration. Allowlisting a hard restricted permission allows the app to hold that permission and allowlisting a soft restricted permission allows the app to hold the permission in its full, unrestricted form.

Permissions can also be immutably restricted which means that the allowlist state of the permission can be determined only at install time and cannot be changed on updated or at a later point via the package manager APIs.

Initially, all restricted permissions are allowlisted but you can change which ones are allowlisted by calling this method or the corresponding ones on the PackageManager. Only soft or hard restricted permissions on the current Android version are supported and any invalid entries will be removed.

Parameters
permissions	Set: This value may be null.

See also:

• PackageManager.addWhitelistedRestrictedPermission(String, String, int)
• PackageManager.removeWhitelistedRestrictedPermission(String, String, int)

writeToParcel

Added in API level 21

public void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Parameters
dest	Parcel: The Parcel in which the object should be written. This value cannot be null.
flags	int: Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES