Google PAI资料整理及实现
总览
利用Play Auto Installs(PAI),OEM可以为设备创建单个软件版本(单个工厂ROM)并支持服务器端配置。然后,制造商可以通过选择要安装的Google Play商店应用来进一步定制该设备,以作为最终用户开箱即用体验的一部分。
为什么选择PAI?
OEM通常会构建相同的硬件SKU并将其交付给各种各样的客户(从运营商到最终用户),然后针对该硬件SKU使用多种软件变体来满足单个客户的需求。在许多情况下,软件变体之间的差异仅限于预加载的应用程序和功能集。
借助PAI,OEM可以配置目标参数,以将特定的一组应用程序发送到特定的一组设备(例如,使用特定运营商,在特定国家/地区或特定硬件SKU中部署的一组设备)。PAI使用应用程序的最新版本来避免进行大规模的空中更新(无论用户是否已登录设备)。
PAI先决条件
在构建PAI配置之前:
-
获取对Android Device Config门户(ADCP)的访问权限,这 是一个面向合作伙伴的门户,用于配置PAI应用。设置PAI的功能是按用户进行访问控制的;要访问门户并获取PAI的必要权限,请与您的Google技术客户经理(TAM)联系。
-
确保设备支持。参与PAI的设备必须运行包含Google Play商店APK 7.4.33或更高版本的软件。PAI版本2与Android版本分离,并且在所有设备上都可用。
PAI应用要求
由于PAI应用程序已预先安装在设备上,因此它们必须满足其他要求。特别:
-
必须通过Google Play商店提供应用。无法通过Google Play提供的应用无法与PAI一起使用。
-
应用必须发布并遵守 Google Play开发者分发协议。
-
应用程序必须对收件人设备可见/可用。应用分发过滤适用于PAI应用,与适用于其他Google Play应用的过滤相同。
-
应用程序的数量(包括URL快捷方式)必须少于50。
-
对于运行Android 6.0(API级别23)或更高版本的设备,必须针对Android 6.0(API级别23)或更高版本编译应用。
-
应用必须免费下载(但是允许进行应用内购买和需要登录的应用)。
PAI工作流程
OEM使用Android设备配置门户(ADCP)创建PAI产品配置,然后将其与Google Play商店基础架构配合使用,将指定的一组应用推送到目标设备。
PAI操作涉及以下步骤:
-
OEM 构建 所需的PAI APK:
-
OEM将存根APK添加到将接收PAI应用程序的设备(目标设备)上。
-
在ADCP中,OEM:
-
ADCP验证配置并与Google Play共享,以使其能够将正确的PAI应用程序集发送到目标设备。
-
设备首次启动并进入设置向导流程时,Google Play会提供设备配置APK,然后安装指定的一组应用程序。有关详细信息,请参见用户体验。
建筑PAI APK
您可以同时构建设备配置和存根APK。
第1步:查看APK要求
查看APK要求:
步骤2:设定APK环境
使用提供的示例代码从预先配置的设置开始,然后针对您的PAI应用进行自定义。
-
下载示例代码 并将其解压缩到构建树中。
-
导航到
PlayAutoInstallsConfig
目录。存根代码包含在/stub
目录中。 -
在中
build_APK.mk
,进行编辑LOCAL_CERTIFICATE
以指向将用于对APK签名的证书。 -
在
AndroidManifest.xml
:-
编辑行
package=
以设置包名称。 -
确保
oem
in中的值android.autoinstalls.config.oem
设置为OEM名称(必填)。
-
-
在中
stub/AndroidManifest.xml
,进行编辑package=
以将包名称设置为与步骤4中使用的值相同。
步骤3:配置变体
对于每个变体(例如,不同的语言环境或运算符),请执行以下步骤:
-
在中
Android.mk
,添加变体名称(例如vzw-us
)。 -
使用语法创建变体目录 (例如 :)。
res-variantname
res-vzw-us
-
创建两个子目录
xml/
和values/
。 -
在中
xml/
,创建并配置用于控制PAI应用显示和处理的XML文件:-
使用该
default_layout.xml
文件设置主屏幕布局。 -
使用该
auto_install.xml
文件定义组和后台安装。
-
-
在中
values/
,编辑strings.xml
文件以为目录名称设置正确的字符串。
步骤4:建立APK
使用make
以下命令构建APK :
$ make TARGET_BUILD_APPS='PlayAutoInstallConfig-variantname' TARGET_BUILD_VARIANT=userdebug
关于设备配置APK
设备配置APK文件列出了要在特定设备上预安装的应用。您必须为要定位的每个设备(例如,针对不同区域和运营商的设备)创建单独的“设备配置” APK文件。
要求
设备配置APK具有以下要求:
-
软件包名称应与存根APK的名称匹配。
-
套餐
AndroidManifest.xml
必须:-
使用以下意图过滤器定义接收器:
<intent-filter>
<action android:name="android.autoinstalls.config.action.PLAY_AUTO_INSTALL" /> </intent-filter> -
有属性
android:exported="false"
。 -
android:hasCode="false"
如果APK没有代码,则具有属性。
-
-
设备配置APK必须:
-
将设置为
versionCode
大于1000的值。 -
使用APK本地化资源为各种文件夹名称语言提供备用字符串。
-
包括两个XML文件:
-
default_layout.xml
,它描述启动器图标的位置。 -
auto_install.xml
,它描述安装组。工作区XML标识要自动安装的应用程序列表。
-
-
使用与存根APK相同的**签名。
-
使用与存根APK相同的证书签名。
-
-
设备配置APK绝不能定义任何权限,活动,其他接收者,内容提供者或服务。
-
列为PAI应用程序的应用程序包名称:
-
必须在Google Play中发布。
-
必须对设备可见。
-
XML文件
设备配置APK包含两个XML文件,这些文件定义了PAI应用程序集。
default_layout.xml
该文件定义了在启动器屏幕上显示图标的PAI应用程序列表(以及其他预加载的图标)。该文件必须满足以下要求:
-
支持启动程序期望的格式。有关详细信息,请参阅AOSP启动器。
-
支持放置PAI下载的应用程序的应用程序小部件。
-
支持指定的URL(浏览器链接)。
-
支持
<include>
包含XML文件的标签;此类文件还应遵循default_layout.xml XML格式。
查看示例default_layout.xml
auto_install.xml
该文件定义了在启动器屏幕上不显示图标的PAI应用程序列表。包括没有图标的应用程序(无头应用程序)。
查看示例auto-install.xml文件
自动安装参数
在中定义PAI应用时 default_layout.xml
,您可以使用autoinstall
标签指定应自动安装该应用。的autoinstall
标签支持以下附加PAI参数。
参数 | 描述 |
---|---|
utmCampaign |
可以由已安装的应用使用Play Install Referrer API读取的归因参数。 |
requiredPreload |
确定是否需要在设备上安装应用程序。设置:
|
installByDefault |
确定是否预先选择了可选应用。设置:
|
groupId |
定义应用发起人。可用组类型: 对于 |
关于存根APK
存根APK是安装在目标设备上的小型应用程序,以使该设备能够参与PAI。
要求
设备系统映像必须包含存根APK,该存根APK满足以下授予设备配置APK附加权限的要求。
-
存根APK必须具有以下软件包名称:
-
按
android.autoinstalls.config
原样使用前缀。建议的格式为android.autoinstalls.config.<oem-name>.<device>
,其中OEM是OEM的品牌。 -
在设备系列中是唯一的。
-
-
软件包AndroidManifest.xml必须:
-
使用意图过滤器定义接收器:
<intent-filter>
<action android:name="android.autoinstalls.config.action.PLAY_AUTO_INSTALL" /> </intent-filter> -
有一个属性
android:exported="false"
。 -
android:hasCode="false"
如果APK没有代码,则具有属性。
-
-
在预安装的应用程序集中,必须只有一个APK定义了上面的接收器。
-
存根APK必须:
-
将设置
versionCode
为1。 -
被存储在
/system/app
(不应有特权的地方)。 -
用私钥签名。不允许使用测试键;不建议使用平台**签名。
-
在出厂ROM中处于禁用状态。当同一SKU交付给多个运营商时,这一点很重要。
-
-
存根APK绝对不能定义任何权限,活动,其他接收者,内容提供者或服务。
具有特权权限的应用
要将PAI与具有特权权限的应用程序一起使用,请在设备的特权应用程序文件夹(/system/priv-app
)中预加载一个空的占位符应用程序,其中包含必要的特权权限声明。
在将应用程序安装到设备上之前,您可以禁用占位符应用程序以将其向用户隐藏(除非安装了PAI,否则用户无法安装该应用程序)。在PAI设置过程中,该应用程序会安装在设备上,并且Google Play商店会启用该应用程序(使其在应用程序列表中可见)。
测试中
创建设备配置和存根APK之后,您可以使用一个或多个测试设备来测试PAI操作。
端到端测试
要在PAI配置上执行端到端测试:
-
将存根APK预安装在测试设备上。
-
在 ADCP中,创建一个新的产品配置。
-
在元数据中:
-
输入配置名称。
-
输入与您的测试设备的基本构建指纹匹配的指纹。
-
启用发布配置。
-
-
在定位中:
-
输入与您的测试设备的基本构建指纹匹配的指纹。
-
输入测试设备IMEI或***作为硬件ID。
-
-
上载设备配置APK。
-
根据需要配置自动安装。
-
-
恢复测试设备的出厂设置。
-
在设置过程中,验证PAI屏幕显示正确的应用程序集。
-
设置完成后,请在“设置” >“ 应用程序”中检查APK版本,以验证是否已成功下载PAI配置APK 。
在不恢复出厂设置的情况下验证APK下载
对于运行userdebug或eng build的测试设备,您可以通过手动触发VPA服务来确认设备下载了Device Configuration APK,而无需恢复出厂设置。例:
$ adb root
$ adb shell am startservice -n \
com.android.vending/com.google.android.finsky.setup.VpaService -d \
playsetupservice://startvpa
这会将APK安装排队,而无需下载。要强制下载应用,请先停止然后重新启动Play商店应用。
收集调试信息
如果您在配置或实施PAI时遇到问题,可以与您的Google联系人联系以寻求帮助。与我们联系之前,请从测试设备收集日志和一些基本信息(Google Play商店版本和Android ID)。
收集日志
要从测试设备收集日志:
-
将测试设备连接到工作站(以便您可以
adb
在设备上运行命令)。 -
确保设备正在运行Play商店的用户 调试版本(因为您需要root访问权限才能获取日志)。
-
将设备恢复出厂设置并在安装向导的第一页上停止。
-
从连接的工作站:
-
设置日志记录以写入文件:
$ adb root
$ adb logcat -v threadtime > long.trace.txt -
设置适当的日志记录级别:
$ adb shell setprop log.tag.DfeProto VERBOSE
$ adb shell setprop log.tag.Finsky VERBOSE
$ adb shell setprop log.tag.Volley VERBOSE
$ adb shell setprop log.tag.SetupWizard VERBOSE
$ adb shell am broadcast -a \
com.google.gservices.intent.action.GSERVICES_OVERRIDE -e \
finsky.enable_sensitive_logging true
$ adb shell am broadcast -a \
com.google.gservices.intent.action.GSERVICES_OVERRIDE -e \
finsky.debug_options_enabled true
$ adb shell am broadcast -a \
com.google.gservices.intent.action.GSERVICES_OVERRIDE -e \
finsky.http.log_requests_curl true -
强制重启Google Play商店:
$ adb shell kill `adb shell ps | grep com.android.vending | sed -e "s/^[^ ]* *//;s/[^0-9].*$//"`;
-
-
在测试设备上,完成安装向导。
获取基本设备信息
从连接的工作站:
-
获取Google Play商店版本:
$ adb shell pm dump com.android.vending | grep versionName | cut -d "=" -f 2
-
获取设备的Android ID:
$ adb shell su root sqlite3 \
/data/data/com.google.android.gsf/databases/gservices.db "SELECT * FROM main" | grep android_id用户体验
根据网络的可用性,在安装向导期间或之后开始PAI应用程序下载。对于以下用户:
-
未计量的网络(例如Wi-Fi),安装向导完成后会立即开始应用下载。
-
计量网络,应用程序下载将推迟到提供Wi-Fi为止。但是,用户可以选择通过移动数据下载应用程序。
有关更多方案,请参阅下载方案。
设定精灵
作为设置向导流程的一部分,Play商店会 在用户进入主屏幕之前下载与ADCP上配置的过滤规则匹配的设备配置APK 。启动器读取工作空间的APK资源并加载它们。
安装向导流程
图1.安装向导流程
安装向导应包括一个屏幕或一个可选步骤,通知用户自动安装了哪些应用程序,并允许用户选择安装了哪些可选应用程序。如果在没有通知用户的情况下自动安装了应用程序,则必须在启动器主屏幕上放置应用程序图标。
启动器应用程序图标
PAI应用程序图标可以放在启动器主屏幕,文件夹或热座上的任何位置。在未通知用户的情况下自动安装的任何应用程序的应用程序图标必须放置在启动器主屏幕上。URL(浏览器)快捷方式图标也可以放置在启动器主页上。
OEM启动器必须支持显示所有PAI应用程序的承诺图标和承诺小部件。Promise图标和Promise小部件是UI功能,指示尚未将应用程序加载到设备上,但正在下载和安装过程中。
图2. Promise图标
设置向导屏幕
下表总结了针对PAI配置可能出现的所有安装向导屏幕:
屏幕 无线上网 零利率数据 仅计量数据 断线 加载PAI配置 在设置向导中下载PAI设备配置APK。 当Play客户端与Google服务器同步时(可能在网络可用后的24小时之内),设备配置APK会下载。加载APK后,设备会显示“完成设置”的通知。 应用选择 显示带有“将在Wi-Fi上下载应用程序”副标题的“ 查看其他应用程序”屏幕。 在“ 查看其他应用程序”屏幕上显示副标题为“如果立即下载应用程序,则不收取数据费”。 显示带有“带有Wi-Fi时将下载应用程序”副标题的“ 查看其他应用程序”屏幕。 显示带有“连接到互联网时将下载应用程序”副标题的“ 查看其他应用程序”屏幕。 应用下载和安装 立即下载。 等待Wi-Fi(除非用户单击“使用数据”)。 等待网络。 PAI进度通知 显示进度栏和“正在安装X个Y应用程序”通知。 显示“将在有Wi-Fi时下载应用程序”和带有“使用数据”的按钮来更改默认行为。 如果设备配置APK已下载且用户:
-
尚未看到应用程序选择屏幕,显示“完成设置”通知。
-
已经看到应用程序选择屏幕,显示“网络可用时将下载应用程序”消息。
无极图标/小工具放置 答应放置在主屏幕上的图标和/或小部件。如果用户单击一个Promise图标,它们将被带到应用程序详细信息页面。 承诺图标和/或小部件将不会放置在主屏幕上。 详细页面信息 常规屏幕上带有标签,提示当前未下载特定应用时,“应用已在下载队列中”。 带有“正在等待Wi-Fi”标签的常规屏幕。 带有“等待网络”标签的常规屏幕。 在安装过程中,用户可以选择从其他功能中查看其他应用程序。屏幕。在“ 查看其他应用程序”中,用户可以查看并选择或取消选择PAI可选应用程序。要使应用程序成为可选应用程序并预先选择要下载的应用程序,请参阅Config APK XML文件。
图3. Setup Wizard应用程序选择屏幕,用户可以选择查看其他应用程序 图4. 安装向导查看其他应用程序屏幕。屏幕打开时,将根据连接状态调整“应用程序将被下载...”字符串。 警报: 如果您删除其他内容?屏幕或“ 安装向导”中的“ 查看其他应用程序”屏幕,您必须将所有PAI应用程序放置在启动器主屏幕上。下载和安装状态
在下载应用程序时,用户可以查看进度通知。
转存失败重新上传取消
转存失败重新上传取消
图5. 用户未计量连接时的通知 图6. 用户没有Wi-Fi或零费率连接时的通知 如果用户在Google Play中打开应用的详细页面,他们还可以查看下载和安装状态。
图7. Google Play中应用程序下载和安装状态的示例
下载场景
应用会根据以下条件开始下载:
图8.应用交付逻辑
立即下载(非计量网络)
对于非计量网络(例如Wi-Fi)上的用户,应用程序下载将在安装向导完成后立即开始。用户不会收到有关下载的通知。
Wi-Fi卸载(计量网络)
对于使用计费网络的用户,应用程序下载将推迟到Wi-Fi可用或用户连接到未计费的网络为止;这样可以保护用户的数据计划。用户可能同意使用移动数据或计量数据下载应用程序。
注意:要下载PAI应用程序进行Wi-Fi卸载需要Android 7.x或更高版本。Android 7.0需要其他向导脚本。Android 7.1+已包含更改。零税率
为PAI应用启用了零税率且运营商已将用于PAI下载的IP / URL列入白名单时:
-
用户免费下载与PAI应用相关的所有内容。
-
安装向导完成后,PAI应用程序下载立即开始。
-
用户将收到免费下载的通知。
有关详细信息,请参见启用零利率。
延迟设定
当用户设置没有数据连接的新设备时,Play商店将无法下载设备配置APK或任何自动安装应用。在这些情况下,设置将推迟到设备获得连接为止。
当后台服务检测到连接时,设备会自动下载设备配置APK,并向用户显示不可撤销的通知,提示他们完成设置。例:
图9.不可取消的通知以完成设置
从通知中,用户可以:
-
在应用选择屏幕上查看应用,或
-
安装所有应用程序(跳过查看并安装所有PAI应用程序)。
然后,设备下载选定的应用程序。
注意: 如果在安装向导中未运行PAI,则应用程序图标不会放置在主屏幕上。延迟插入SIM卡
在完成安装向导后插入SIM卡的用户将看到略有不同的PAI流程,其中入口点有所不同,但总体流程,通知和UI保持不变。
延迟插入SIM卡要求设备预先加载Google Play商店13.1或更高版本。
验证
当用户插入SIM卡并连接到移动网络时,Google Play会检查以下内容:
-
设备在不到7天前被**。
-
之前尚未通过插入的SIM卡触发PAI设置。
-
已为此设备配置了PAI应用,但当前尚未安装。
如果上述所有条件都成立,则Play会触发通知,通知用户可以下载PAI应用。
注意:在用于后期SIM卡流程的PAI中,配置为“ 必需”的应用程序显示为“ 可选”,但已预先选择。由于用户可能已经使用该设备一段时间,因此用户可以取消选择他们不想要的应用程序。多个SIM卡设备
由于PAI仅支持与主SIM卡对应的下载,因此 仅向用户显示一(1)条通知。
主SIM卡的Play商店定义是用于数据连接的SIM卡。在其中一个SIM卡用于语音和SMS且另一个SIM卡用于数据的情况下,主SIM卡是用于数据的SIM卡(因此是用于PAI的SIM卡)。
用户体验
在完成安装向导后插入SIM卡的用户将看到一条拒绝输入PAI的通知。
-
如果用户点击 INSTALL ALL,则设备会将所有应用程序排队等待安装,并且用户会根据其数据连接看到图5或图6。
-
如果用户点击通知正文或REVIEW ,则会显示一个类似于图4的应用程序选择屏幕。从先前的PAI流程中安装的应用程序将从应用程序选择屏幕的列表中过滤掉。
用户选择要安装的应用程序后,安装流程与常规PAI流程相同。
注意: 由于用户可能已经自定义了自己的启动器,因此晚期SIM PAI不提供主屏幕图标的放置。PAI安装完成后,设备将显示安装完成通知。
图10. PAI设置完成时的通知
-
指标字段
类型 | 领域 | 描述 |
---|---|---|
STRING(尺寸) | build_fingerprint |
设备构建指纹(ro.build.fingerprint )。 |
STRING(尺寸) | event_type |
PAI事件类型。可能的值:
|
时间戳(尺寸) | timestamp |
PAI事件的时间戳。 |
STRING(尺寸) | ro_oem_key |
构建道具键(ro.oem.key )用作PAI目标属性。 |
STRING(尺寸) | carrier |
运营商名称。 |
STRING(尺寸) | ip_country |
该国家/地区的两个字符代码用作PAI目标属性。 |
STRING(尺寸) | package_name |
正在安装的应用程序名称的唯一标识符。仅在event_type = APP时有效。 |
STRING(尺寸) | mcc_mnc |
运营商的MCC_MNC代码。 |
STRING(尺寸) | pai_group |
分配给虚拟预加载配置中包含的一组硬件ID的唯一字符串。格式: eng.android_partner.pai.prod。<设备>。<产品>。<虚拟预加载ID> |
整数(公制) | success_count |
成功事件数。 |
整数(公制) | failure_count |
失败事件数。 |
整数(公制) | unique_count |
成功涉及的唯一设备总数。例如,如果一台设备两次恢复出厂设置 |
常问问题
哪些版本的Android支持PAI?
Android 5.x及更高版本支持PAI。
在安装向导过程中没有数据连接时的行为是什么?
当用户设置的设备没有数据连接时:
-
启动器将显示默认工作空间(嵌入在启动器中)。
-
PAI使用延迟的设置 流程。
用户跳过Google帐户登录时的行为是什么?
即使用户跳过登录,PAI应用程序仍会下载。
ADCP如何评估产品配置列表?
ADCP使用从上到下的顺序评估产品配置。与设备匹配的第一个定位规则确定将哪个配置发布到设备;找到规则匹配后,将不评估其他任何规则。设置规则的顺序以控制对传入设备请求评估规则的顺序。
可以将多少个应用程序加载到PAI中?
自动安装的应用程序数量上限为50;推荐数量为10-15个应用。
PAI是否支持付费应用程序(下载前需要付款)?
没有。
PAI如何处理已经预先加载在系统映像中的PAI应用程序?
预加载的应用程序包含在PAI应用程序中。如果预加载的版本已过期,则会使用其余的PAI应用程序进行更新。
PAI如何与现有应用配合使用?
如果预加载的应用程序版本已过期,则PAI将自动更新该应用程序(在等待Wi-Fi之后)。
通过PAI安装的应用是否可用于用户登录的其他设备?
PAI应用是特定于设备的,这意味着PAI仅下载和安装已为特定设备配置的应用。您可以在Google Play>我的应用>所有中查看安装到设备上的PAI应用 。
PAI如何处理SIM卡交换?
SIM卡交换不会触发PAI(但是,出厂重置会触发PAI)。
如果用户在完成安装向导后第一次插入SIM卡怎么办?
在预加载了Google Play Store 13.1或更高版本的设备上,向用户显示在完成安装向导后插入SIM卡的PAI流程略有不同,其中入口点有所不同,但总体流程,通知和UI保持不变。有关详细信息,请参阅SIM后插入。
在未预加载Google Play商店13.1或更高版本的设备上,PAI仅运行一次。如果在用户添加SIM卡之前运行了PAI,则即使使用SIM卡提供的设备载体,它也不会再次执行。使用运营商作为配置机制的合作伙伴应在设置向导中添加一个屏幕,以提示用户插入有效的SIM卡,以确保交付正确的应用程序。
是否可以在安装向导之外触发PAI的意图?
没有。