升級邀請是一種使用者流程，可展示目前可用的 Android 作業系統主要升級版本中提供的主要新功能。
這項流程旨在說服使用者將裝置升級至最新的 OS 版本。
當裝置有待使用者核准的作業系統升級時，使用者會收到推播通知，顯示新功能並邀請他們執行升級。
如要啟用 Android OS 的升級邀請功能，請使用這份表單申請啟用。
自訂升級邀請體驗
您可以透過下列方式自訂升級邀請：
- 移除不相關的功能。
- 更新文字區塊中的語言。
- 修改動畫、顏色和字型，配合您的品牌。
如要自訂流程，請參閱「Upgrade Invite Style Guide」中的規範，並在Android Upgrade Invite 啟用申請表單中加入自訂資訊。
升級邀請樣式指南
您可以使用這份樣式指南，修改升級邀請的外觀，以符合自家品牌的風格 (螢幕、顏色、字型)。強烈建議您將大小和結構保持與原始設計相近。
升級邀請流程包含以下三個部分：
- 簡介畫面
- 功能畫面
- Outro 畫面
每個畫面上都有動畫，可協助說明各項功能。
簡介畫面
簡介畫面包含簡短的動畫，歡迎使用者並鼓勵他們開始在簡介畫面中顯示的流程。
版面配置
裝置動畫一律包含：
- 白色背景和彩色圖形
- 裝置邊框
- UI 內容
樣式
如果您選擇採用 Material You 樣式，可以使用範例中顯示的預設顏色和形狀。
如果您使用自家的品牌顏色，請確保該顏色與 UI 背景搭配良好。
動作
選項 1：主畫面上顯示時鐘
- 畫面上會顯示數字。
- 數字會移至中央，同時減少大小。手機框架會隨即顯示。
- 手機尺寸會縮小。形狀開始進入畫面。
- 動畫已完成。形狀會持續緩慢移動。
|
|
選項 2：主畫面上不顯示時鐘
- 手機進入畫面。
- 手機會移動到中央並放大。形狀開始進入畫面。
- 手機達到最大尺寸，形狀持續移動。
|
|
功能畫面
每個功能畫面都會強調新作業系統中的某項功能。
版面配置
裝置動畫一律包含：
- 色彩繽紛的背景
- 裝置邊框
- UI 內容
樣式
- 選擇適合 UI 內容及一般外觀的背景顏色。
- 設定畫面中的字型大小。視需要設定較大的字型大小。
動作
記錄每個功能的流程動畫，包括觸控互動。將錄製內容匯出為 Lottie 檔案。
Outro 畫面
結尾畫面會完成流程。這會向使用者指出他們已瀏覽過所有畫面。
版面配置
裝置動畫一律包含：
- 背景有半圓形 (加上動畫形狀)
- 裝置邊框
- UI 內容
樣式
- 請選取與 UI 內容和一般外觀相容的背景顏色。
- 使用半圓形的形狀，
動作
按照標準的外螢幕動畫流程操作：
- 手機向上移動。
- 背景會顯示圓圈。
- 手機背後各種形狀。
- 圖形會像五彩碎紙般從背景飛出。
|
|
測試升級邀請流程
- 在 Android 裝置上依序前往「設定」>「Google」>「Upgrade Party 偵錯」。
- 為相關裝置作業系統準備升級邀請的觸發條件 (取決於目前的 OS 版本，以及要測試的特定升級邀請流程)。以下任一項：
- 按一下「Write Fake 升級 (目前版本)」。(例如，如果您執行 Android 13 OS，這會觸發 Android 13 測試流程)
- 按一下「Write pending upgrade (current version + 1)」。(例如，如果您執行的是 Android 12 OS，將會觸發 Android 13 測試流程)
- 按一下「回報 OS 升級」
- 點選收到的通知，或點選「開啟升級邀請」。
升級邀請的觸發條件選項
觸發升級邀請流程的方式有 3 種： 1. 自動 2. 廣播 3. 觸發 Play 服務 SDK
自動 - Google 觸發通知 (僅適用於執行 gOTA 的裝置)
如果是執行 gOTA 的 OEM 裝置，系統會自動整合，不需要執行升級邀請整合步驟。一旦偵測到待處理的主要 OS 升級，Google Play 服務就會透過推播通知傳送至裝置，並導向升級邀請流程。
Android 廣播 - Google 觸發通知 (建議)
應用程式廣播是整合升級邀請流程最簡單且建議的方式。
廣播接收器可讓您使用廣播訊息，從應用程式觸發升級邀請流程。廣播訊息會透過 Google Play 服務向裝置傳送推播通知，藉此前往升級邀請流程。
廣播必要條件
如要讓應用程式做好準備，請完成下列各節的步驟。
請確認應用程式的設定檔使用下列值：
- minSdkVersion 為 14 以上
- compileSdkVersion 為 28 以上
- usesPermission 的 android.permission.RECOVERY
傳送廣播
請參閱下方的操作說明，瞭解如何透過 OEM 應用程式 (或程式碼) 傳送 Android 廣播訊息，觸發推播通知：
傳送含有動作的廣播訊息。
com.google.android.gms.growth.upgradeparty.upgradeinvite.ACTION_SYSTEM_UPDATE將
com.google.android.gms套件新增至廣播。com.google.android.gms
補充規定
升級邀請流程也能讓使用者直接從流程中執行 OS 升級。
為使這項功能運作，請公開自訂意圖，讓 Google 可從升級邀請流程中呼叫，進而觸發下載更新。
廣播用法示例
請參考以下應用程式廣播範例：
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 鍵的值是整數，表示待安裝的 OS 版本 (在本例中，要安裝的 Android 版本為 14)。這項屬性可用於決定要觸發哪個升級邀請流程。
Play 服務 SDK - 僅觸發流程
第三方 SDK 可讓您透過應用程式或自己的 OTA 通知觸發升級邀請流程。使用第三方外部 API 啟用升級邀請流程本身。我們不太建議使用這個方法。
必要條件
如要讓應用程式做好準備，請完成下列各節的步驟。
請確認應用程式的版本檔案使用下列的值：
- 14 以上版本的 minSdkVersion
- 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')
}
如要提供用戶端的依附元件，請納入下列程式庫：
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 初始化
如要初始化用戶端，請使用 UpgradeParty 類別：
import com.google.android.gms.growth.UpgradeParty; UpgradeParty.getClient(activity);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;
}
傳回 Task，以非同步方式驗證使用者是否符合升級邀請資格。產生的布林值會指出使用者是否符合資格。
invokeUpgradeInvite
Task<Void> invokeUpgradeInvite();
叫用升級邀請活動。產生的 _Task _ 物件會指出啟動活動時是否發生錯誤。
錯誤程式碼
這兩種 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);
}
});
}