Android 升级邀请

升级邀请是一个用户体验流程，展示了当前可用的重大 Android OS 升级所包含的主要新功能。

此流程旨在帮助说服用户将其设备升级到最新的操作系统版本。

如果设备上有一个正在等待用户批准的操作系统升级，则用户会收到一个展示新功能并邀请其执行升级的推送通知。

如需为您的 Android OS 启用升级邀请，请使用“请求激活 Android 升级邀请”表单进行注册。

自定义升级邀请体验

您可以通过以下方式自定义升级邀请体验：

• 移除不相关的功能。
• 更新文本块中的语言。
• 修改动画、颜色和字体，使其契合您的品牌风格。

如需自定义该流程，请查看“升级邀请风格指南”中的准则，并在请求激活 Android 升级邀请表中添加您的自定义信息。

测试升级邀请流程

1. 在 Android 设备上，依次转到设置 > Google > Upgrade Party 调试。
2. 为相关设备操作系统备妥升级邀请触发器（具体取决于当前的操作系统版本以及要测试的特定升级邀请流程）。请执行以下任一操作：
   1. 点击写入模拟升级（当前版本）。（例如，如果您运行的是 Android 13 操作系统，则会触发 Android 13 测试流程）
   2. 点击写入待执行的升级（当前版本 +1）。（例如，如果您运行的是 Android 12 操作系统，则会触发 Android 13 测试流程）
   3. 点击报告操作系统升级
3. 点击收到的通知，或点击打开升级邀请。

升级邀请的触发选项

您可以通过 3 种不同的方式来触发升级邀请流程： 1. 自动 2. 广播 3. 触发的 Play 服务 SDK

自动 - Google 触发的通知（仅限运行 gOTA 的设备）

对于运行 gOTA 的 OEM 设备，系统会自动集成，无需升级邀请集成步骤。检测到待执行的重大操作系统升级后，Google Play 服务会向设备发送一个推送通知，从而触发升级邀请流程。

Android 广播 - Google 触发的通知（推荐）

应用广播是集成升级邀请流程的最简单的推荐方法。

借助广播接收器，您可以在自己的应用中使用广播消息来触发升级邀请流程。广播会通过 Google Play 服务向设备发送一个推送通知，从而触发升级邀请流程。

广播前提条件

为了让您的应用做好准备，请完成以下部分中的步骤。

确保您应用的配置文件使用以下值：

• minSdkVersion 14 或更高版本
• compileSdkVersion 28 或更高版本
• android.permission.RECOVERY 的 usesPermission

发送广播

请参阅 OEM 应用（或代码）的以下说明，了解如何发送 Android 广播以触发推送通知：

1. 发送带有操作的广播。

   com.google.android.gms.growth.upgradeparty.upgradeinvite.ACTION_SYSTEM_UPDATE
   

2. 将 com.google.android.gms 包添加到广播。

   com.google.android.gms
   

其他要求

借助升级邀请流程，用户还可以直接从流程执行操作系统升级。

为此，请公开一个自定义 intent，让 Google 能在升级邀请流程中调用该 intent，以触发下载更新。

广播用法示例

请参阅以下应用广播示例：

Context context = getApplicationContext();
Intent upgradeInviteIntent = new Intent()
  .setAction( "com.google.android.gms.growth.upgradeparty.upgradeinvite.ACTION_SYSTEM_UPDATE")
  .setPackage("com.google.android.gms");
  .putExtra("com.google.android.gms.growth.upgradeparty.upgradeinvite.EXTRA_PENDING_ANDROID_OS_VERSION_NUMBER", 14);

context.sendBroadcast(updateIntent);

EXTRA_PENDING_ANDROID_OS_VERSION_NUMBER 键的值是一个整数，表示待升级的操作系统版本（在此示例中，要安装的 Android 版本为 14）。这将用于确定将触发哪个升级邀请流程。

Play 服务 SDK - 仅限流程触发

借助第三方 SDK，您可以从自己的应用或 OTA 通知中触发升级邀请流程。使用第三方外部 API 激活升级邀请流程本身。我们不推荐使用此方法。

前提条件

为了让您的应用做好准备，请完成以下部分中的步骤。

确保您应用的 build 文件使用以下值：

• minSdkVersion 14 或更高版本
• compileSdkVersion 28 或更高版本

配置您的应用

如需配置您的应用，请执行以下操作：

1. Extract the library from the provided .zip file, and place it in your

仓库。 2. 将 Google Growth SDK 的依赖项添加到模块的应用级 Gradle 文件（通常为 app/build.gradle）中：

   dependencies {
    implementation files('<PATH_TO_BINARY>/play-services-growth-16.1.0-eap04.aar')
   }

1. 如需提供客户端的依赖项，请添加以下库：

   com.google.android.gms:play-services-base:18.0.1
   com.google.android.gms:play-services-basement:18.0.0
   com.google.android.gms:play-services-tasks:18.0.1
   

API 初始化

1. 如需初始化客户端，请使用 UpgradeParty 类：

   import com.google.android.gms.growth.UpgradeParty;
   UpgradeParty.getClient(activity);
   

2. activity 参数必须是发起 activity 的对象。

API 功能

生成的 UpgradePartyClient 公开以下功能。

isEligibleForUpgradeInvite

import com.google.android.gms.growth.UpgradeInviteEligibilityParams;

Task<Boolean> isEligibleForUpgradeInvite(UpgradeInviteEligibilityParams params);

/** Contains parameters for the eligibility query. */
class UpgradeInviteEligibilityParams {


/** Integer indicating the pending OS version (in this example, the Android version to be installed is 14). This is used to determine which Upgrade Invite flow will be triggered. */
  int pendingAndroidOsVersionNumber;
}

返回“任务”，用于异步验证用户是否符合升级邀请条件。生成的布尔值表示用户是否符合条件。

invokeUpgradeInvite

Task<Void> invokeUpgradeInvite();

调用升级邀请 activity。生成的 _Task _object 会指明在启动 activity 时是否出现了错误。

错误代码

这两种 API 方法都可能会失败，显示 com.google.android.gms.common.api.ApiException 类型的异常。在这些情况下，调用方应稍后重试。预期的常见状态代码包括：

• INTERNAL_ERROR：适用于底层逻辑流程中的任何错误
• TIMEOUT：在无法及时处理请求时显示。
• API_NOT_CONNECTED：当 API 不可用（即 UpgradeParty 模块尚未准备就绪）时显示
• NETWORK_ERROR：因网络错误而无法处理请求时显示
• DEVELOPER_ERROR：在发起调用的软件包无法访问 UpgradeParty API 时显示

SDK 用法示例

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import com.google.android.gms.growth.UpgradeParty;
import com.google.android.gms.growth.UpgradePartyClient;

public class SampleActivity extends Activity {

 @Override
 protected void onCreate(Bundle savedInstanceState) {
   super.onCreate(savedInstanceState);
   final UpgradePartyClient client = UpgradeParty.getClient(this);

   // Hide the invocation button initially
   View startUpgradeInviteButton = findViewById(R.id.__some_button__);
   startUpgradeInviteButton.setVisibility(View.GONE);

   // Register an onClick handler to invoke the Upgrade Party Activity
   startUpgradeInviteButton
       .setOnClickListener(
           view -> {
             client
                 .invokeUpgradeInvite()
                 .addOnCompleteListener(
                     task -> {
                       if (!task.isSuccessful()) {
                         // Do something with error, see task.getException()
                       }
                     });
           });
   }

   // Check if eligible for an Upgrade Party
   client
       .isEligibleForUpgradeInvite()
       .addOnCompleteListener(
           task -> {
             if (!task.isSuccessful()) {
               // Do something with error, see task.getException()
             } else {
                  // Show/Hide invocation button, based on the result
                  int visibility = 
                        task.getResult() ? View.VISIBLE : View.GONE;
                  startUpgradeInviteButton.setVisibility(visibility);
             }
           });
   }