Android Upgrade Invite

Upgrade Invite is a user flow that showcases the key new features included in the current available major Android OS upgrade.

The flow is intended to help convince users to upgrade their device to the latest OS version.

Once a device has an OS upgrade pending user approval, users receive a push notification displaying the new features and inviting them to perform the upgrade.

To enable Upgrade Invite for your Android OS, register using the Request to activate Android Upgrade Invite form.

Customize the Upgrade Invite experience

You can customize the Upgrade Invite experience in the following ways:

• Remove irrelevant features.
• Update the language in the text blocks.
• Modify the animations, colors, and fonts to match your brand.

To customize the flow, review the guidelines in the Upgrade Invite Style Guide and include your customization information in the Request to activate Android Upgrade Invite form.

Test the Upgrade Invite Flow

1. On the Android device, go to: Settings > Google > Upgrade Party debug.
2. Prepare the trigger for Upgrade Invite for the relevant device OS (depending on your current OS version, and the specific Upgrade Invite flow to test. Either:
   1. Click Write Fake upgrade (current version). (for example, if you run Android 13 OS this will trigger the Android 13 test flow)
   2. Click Write pending upgrade (current version + 1). (for example, if you run Android 12 OS this will trigger the Android 13 test flow)
   3. Click Report OS upgrade
3. Either click the received notification, or click Open Upgrade Invite.

Trigger options for Upgrade Invite

There are 3 different ways for triggering the Upgrade Invite flow: 1. automatic 2. broadcast 3. Play Services SDK triggered

Automatic - Google triggered notification (for gOTA running devices only)

For OEM devices that run gOTA, integration is automatic and no Upgrade Invite integration steps are required. Once a pending major OS upgrade is detected, this will send a push notification to the device from Google Play services, leading to the Upgrade Invite flow.

Android Broadcast - Google triggered notification (Recommended)

An app broadcast is the simplest and recommended way to integrate the Upgrade Invite flow.

A broadcast receiver enables you to trigger the Upgrade Invite flow from your app using a broadcast message. The broadcast sends a push notification to the device from Google Play services, leading to the Upgrade Invite flow.

Broadcast Prerequisites

To prepare your app, complete the steps in the following sections.

Make sure that your app's configuration files use the following values:

• A minSdkVersion of 14 or higher
• A compileSdkVersion of 28 or higher
• A usesPermission of android.permission.RECOVERY

Send the Broadcast

See below the instructions for the OEM app (or code) to send an Android broadcast to trigger the push notification:

1. Send broadcast with the action.

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

2. Add the com.google.android.gms package to the broadcast.

   com.google.android.gms
   

Additional requirements

The Upgrade Invite flow also enables users to perform the OS upgrade directly from the flow.

For this to work, expose a custom intent that Google can call from the Upgrade Invite flow that triggers the downloading of the update.

Example Broadcast Usage

See the following example of a application broadcast:

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);

The value of the EXTRA_PENDING_ANDROID_OS_VERSION_NUMBER key is an 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.

Play Services SDK - flow triggering only

The third party SDK enables you to trigger the Upgrade Invite flow from your app or your own OTA notifications. Use a third party external API to activate the Upgrade Invite flow itself. This method is less recommended.

Prerequisites

To prepare your app, complete the steps in the following sections.

Make sure that your app's build file uses the following values:

• A minSdkVersion of 14 or higher
• A compileSdkVersion of 28 or higher

Configure your app

To configure your app:

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

repository. 2. Add the dependencies for the Google Growth SDK to your module's app-level Gradle file, normally app/build.gradle:

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

1. To provide the client’s dependencies, include the following libraries:

   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 Initialization

1. To initialize a client, use the UpgradeParty class:

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

2. The activity parameter should be the initiating Activity object.

API functions

The resulting UpgradePartyClient exposes the following functionality.

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;
}

Returns a Task that asynchronously verifies if the user is eligible for an Upgrade Invite. The resulting boolean value indicates whether the user is eligible or not.

invokeUpgradeInvite

Task<Void> invokeUpgradeInvite();

Invokes the Upgrade Invite Activity. The resulting _Task _object indicates whether an error occurred when starting the activity.

Error Codes

Both API methods may fail with an exception of type com.google.android.gms.common.api.ApiException. In such cases, the caller is expected to retry at a later time. Expected common status codes) include:

• INTERNAL_ERROR - for any error in the underlying logic’s flow
• TIMEOUT - if the request couldn't be handled in a timely manner
• API_NOT_CONNECTED - when the API isn't available (that is, UpgradeParty module is not ready yet)
• NETWORK_ERROR - the request couldn't be handled due to network errors
• DEVELOPER_ERROR - the calling package isn't allowed to access the UpgradeParty API

Example SDK Usage

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);
             }
           });
   }