Once you have an OAuth 2.0 implementation, you can optionally configure
OAuth-based App Flip, which allows your
Android users to more quickly link their accounts in your
authentication system to their Google Accounts. The following sections
describe how to design and implement App Flip for your
Cloud-to-cloud integration on Android.

## Design guidelines

This section describes the design requirements and recommendations for the App
Flip account linking consent screen. After Google calls your app, your app
displays the consent screen to the user.

### Requirements

1. You must have a Google authorization statement such as "Once linked, Google will have permission to control your devices."
2. You must communicate that the user's account is being linked to Google, **not** to a specific Google product, such as Google Home or Google Assistant.
3. You must state a clear call-to-action on your consent screen and use the wording "Agree and link" for linking action. This is because users need to understand what data they're required to share with Google to link their accounts.
4. You must provide a way for users to go back, deny or cancel, if they choose not to link. Use the wording "Cancel" for the cancel action.
5. You must implement this workflow: After clicking "Agree and link", you must show linking success and redirect the user back to the Google Home app automatically. The user should now see the linked device on the Google Home app with your action. After clicking "Cancel" you should redirect the user back to the Google Home app.

### Recommendations

We recommend that you do the following:

1. **Display Google's Privacy Policy.** Include a link to
   [Google's Privacy Policy](http://policies.google.com)
   on the consent screen.

2. **Data to be shared.** Use clear and concise language to tell the user what
   data of theirs Google requires and why.

3. **Ability to unlink.** Offer a mechanism for users to unlink, such as a
   URL to their account settings on your platform. Alternatively, you can
   include a link to [Google Account](https://myaccount.google.com) where users
   can manage their linked account.

4. **Ability to change user account.** Suggest a method for users to switch
   their account(s). This is especially beneficial if users tend to have
   multiple accounts.

   - If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with *OAuth linking* and the *implicit* flow.
5. **Include your logo.** Display your company logo on the consent screen.
   Use your style guidelines to place your logo. If you wish
   to also display Google's logo, see
   [Logos and trademarks](https://www.google.com/permissions/logos-trademarks/).

![This figure shows an example consent screen with call-outs to the
individual requirements and recommendations to be followed when
you design a user consent screen.](https://developers.home.google.com/static/identity/images/app-flip-guidance.png) Figure 1: Account linking consent screen design guidelines.

## Set up for OAuth-based App Flip

The following sections describe the prerequisites for OAuth-based App Flip
and how to configure your App Flip project in the Google Home Developer
Console.

### Create a Cloud-to-cloud integration and set up an OAuth 2.0 server

Before you can configure App Flip, you need to do the
following:

- **Set up an OAuth 2.0 server.** For more information about setting up an OAuth server, see [Implement an OAuth 2.0
  server](https://developers.home.google.com/cloud-to-cloud/project/authorization).
- **Create a Cloud-to-cloud integration.** To create an integration, follow the instructions in [Create a Cloud-to-cloud
  integration](https://developers.home.google.com/cloud-to-cloud/integration/create).

### Configure App Flip in the Developer Console

The following section describes how to configure App Flip in the
[Developer Console](https://console.home.google.com/).

1. Fill out all the **required(\*)** fields under **Account Linking.** (If App Flip isn't supported, regular OAuth is used as a fallback.)
2. Provide a URL for **Cloud fulfillment URL.** The **Cloud fulfillment
   URL** is used to process your smart home intents. Check **Local
   fulfillment.**
3. Under **App Flip (optional)** , check **Android app.**
4. Fill out the following fields:
   - **Application ID.** The Application ID is a unique ID that you set for your app.
   - **App signature.** Android apps must be 'signed' with a public-key certificate before they can be installed. For information about obtaining your app signature, see [Authenticating Your Client](https://developers.google.com/android/guides/client-auth).
   - **Authorization intent.** In this field, enter a string that specifies your intent action.
5. If you want to optionally configure your client, add scopes and click **Add scope** under **Scopes(s) (optional).**
6. If your client requires it, select the **Have Google transmit Client ID
   and secret via HTTP basic auth header.**


You can now continue to the next section to implement
App Flip in your
Android
app.

## Implement App Flip in your native apps

To implement App Flip, you need to modify the user
authorization code in your app to accept a deep link from Google.

OAuth-based App Flip linking (App Flip) inserts your Android app into the
Google Account Linking flow. A traditional account linking flow requires the
user to enter their credentials in the browser. The use of App Flip defers user
sign-in to your Android app, which allows you to leverage existing
authorizations. If the user is signed in to your app, they don't need to
re-enter their credentials to link their account. A minimal amount of code
changes are required to implement App Flip on your Android app.

In this document, you learn how to modify your Android app to support
App Flip.

### Try the sample

The App Flip linking [sample app](https://github.com/googlesamples/identity-appflip-android)
demonstrates an App Flip-compatible account linking integration on Android. You
can use this app to verify how to respond to an incoming App Flip intent from
Google mobile apps.

The sample app is preconfigured to integrate with the [App Flip Test Tool for
Android](https://github.com/googlesamples/identity-appflip-tester-android),
which you can use to verify your Android app's integration with App
Flip before you configure account linking with Google. This app simulates the
intent triggered by Google mobile apps when App Flip is enabled.

### How it works

The following steps are required to carry out an App Flip integration:

1. The Google app checks if your app is installed on the device using its *package name*.
2. The Google app uses a package signature check to validate that the installed app is the correct app.
3. The Google app builds an intent to start a designated activity in your app. This intent includes additional data required for linking. It also checks to see if your app supports App Flip by resolving this intent through the Android framework.
4. Your app validates that the request is coming from the Google app. To do so, your app checks the package signature and the provided client ID.
5. Your app requests an authorization code from your OAuth 2.0 server. At the end of this flow, it returns either an authorization code or an error to the Google app.
6. The Google app retrieves the result and continues with account linking. If an authorization code is provided, the token exchange happens server-to-server, the same way it does in the browser-based OAuth linking flow.

### Modify your Android app to support App Flip

To support App Flip, make the following code changes to your Android app:

1. Add an `<intent-filter>` to your `AndroidManifest.xml` file with an action
   string that matches the value you entered in the **App Flip Intent** field.

       <activity android:name="AuthActivity">
         <!-- Handle the app flip intent -->
         <intent-filter>
           <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
           <category android:name="android.intent.category.DEFAULT"/>
         </intent-filter>
       </activity>

2. Validate the calling app's signature.

   You need to match the package name and signature for any Google apps
   that users may use to account link. For example, to link with Google
   Home and Search apps, add their package names and signatures:
   - Package name: `com.google.android.apps.chromecast.app`
   - Original SHA-256 lineage certificate: `3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A`
   - Rotated Play App Signing SHA-256 certificate: `5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6`

   and
   - Package name: `com.google.android.googlequicksearchbox`
   - Signature: `F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83`

   Smart home linking requests are initiated directly by the
   Google Home app (GHA). If your application restricts callers and
   previously only allowed the Google Search app, you must add
   `com.google.android.apps.chromecast.app` and its SHA-256 certificates to
   your allowlist so that App Flip continues to succeed.

       private fun verifyFingerprint(
           expectedPackage: String,
           expectedFingerprints: List<String>
       ): Boolean {
           val callingPackage = callingActivity?.packageName ?: return false
           if (callingPackage != expectedPackage) return false
           return expectedFingerprints.any { hex ->
               val sha256Bytes =
                   hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
               packageManager.hasSigningCertificate(
                   callingPackage,
                   sha256Bytes,
                   PackageManager.CERT_INPUT_SHA256
               )
           }
       }

3. Extract the client ID from the intent parameters and verify that the client
   ID matches the expected value.

       private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
       private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
       // Original lineage certificate (3D:7A...) and active rotated
       // Play App Signing certificate (5A:AD...)
       private val EXPECTED_FINGERPRINTS = listOf(
           "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
           "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
       )
       ...

       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)

           val clientId = intent.getStringExtra("CLIENT_ID")

           if (clientId == EXPECTED_CLIENT &&
               verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {

               // ...authorize the user...
           }
       }

4. Upon successful authorization, return the resulting authorization code back
   to Google.

       // Successful result
       val data = Intent().apply {
           putExtra("AUTHORIZATION_CODE", authCode)
       }
       setResult(Activity.RESULT_OK, data)
       finish()

5. If an error occurred, return an error result instead.

   > [!NOTE]
   > **Note:** Don't handle the error directly within your app, instead return the error result via `setResult`. This ensures that the appropriate fallback method is triggered if the app linking flow fails.

       // Error result
       val error = Intent().apply {
           putExtra("ERROR_TYPE", 1)
           putExtra("ERROR_CODE", 1)
           putExtra("ERROR_DESCRIPTION", "Invalid Request")
       }
       setResult(-2, error)
       finish()

### Content of the launch intent

The Android intent that launches your app includes the following fields:

- `CLIENT_ID` (`String`): Google `client_id` registered under your app.
- `SCOPE` (`String[]`): A list of scopes requested.
- `REDIRECT_URI` (`String`): The redirect URL.

### Content of the response data

The data returned to the Google app is set in your app by calling `setResult()`.
This data includes the following:

- `AUTHORIZATION_CODE` (`String`): The authorization code value.
- `resultCode` (`int`): Communicates the success or failure of the process and takes one of the following values:
  - `Activity.RESULT_OK`: Indicates success; an authorization code is returned.
  - `Activity.RESULT_CANCELLED`: A recoverable error. Signals that the user has cancelled the process. In this case, the Google app will attempt account linking again using your authorization URL.
  - `-2`: Indicates that an error has occurred. Different types of errors are described below.
- `ERROR_TYPE` (`int`): The type of error, which takes one of the following values:
  - `1`: Recoverable error: The Google app will attempt account linking using the authorization URL.
  - `2`: Unrecoverable error: The Google app aborts account linking.
  - `3`: Invalid or missing request parameters.
- `ERROR_CODE` (`int`): An integer representing the nature of the error. To see what each error code means, refer to the [table of error codes](https://developers.home.google.com/cloud-to-cloud/enhancements/app-flip-android#table_of_error_codes).
- `ERROR_DESCRIPTION` (`String`, optional): Human-readable status message
  describing the error.

  > [!NOTE]
  > **Note:** See the OAuth 2.0 standard for more information on [possible errors](https://www.oauth.com/oauth2-servers/server-side-apps/possible-errors/) and the optional contents of the `error_description` field.

A value for the `AUTHORIZATION_CODE` is expected when
`resultCode == Activity.RESULT_OK`. In all other cases, the value for
`AUTHORIZATION_CODE` needs to be empty. If `resultCode == -2`, then the
`ERROR_TYPE` value is expected to be populated.

### Table of error codes

The table below shows the different error codes and whether each is a recoverable or unrecoverable error:

| Error code | Meaning | Recoverable | Unrecoverable |
|---|---|---|---|
| `1` | `INVALID_REQUEST` | ✔ |   |
| `2` | `NO_INTERNET_CONNECTION` |   | ✔ |
| `3` | `OFFLINE_MODE_ACTIVE` | ✔ |   |
| `4` | `CONNECTION_TIMEOUT` | ✔ |   |
| `5` | `INTERNAL_ERROR` | ✔ |   |
| `6` | `AUTHENTICATION_SERVICE_UNAVAILABLE` |   | ✔ |
| `8` | `CLIENT_VERIFICATION_FAILED` | ✔ |   |
| `9` | `INVALID_CLIENT` | ✔ |   |
| `10` | `INVALID_APP_ID` | ✔ |   |
| `11` | `INVALID_REQUEST` | ✔ |   |
| `12` | `AUTHENTICATION_SERVICE_UNKNOWN_ERROR` |   | ✔ |
| `13` | `AUTHENTICATION_DENIED_BY_USER` |   | ✔ |
| `14` | `CANCELLED_BY_USER` |   | ✔ |
| `15` | `FAILURE_OTHER` |   | ✔ |
| `16` | `USER_AUTHENTICATION_FAILED` | ✔ |   |

For all error codes, you must return the error result via `setResult` to
ensure the appropriate fallback is triggered.

## Test App Flip on your device

Now that you've created a Cloud-to-cloud integration and configured App Flip
on the console and in your app, you can test App Flip on your mobile device.
You can use the Google Home app to test App Flip.

To test App Flip from the Google Home app,
follow these steps:

> [!NOTE]
> **Note:** Make sure that you are signed in to the Google Home app with your test account.

1. Go to the [Developer Console](https://console.home.google.com/) and select your project.
2. Go to **Cloud-to-cloud \> Test**.
3. Trigger the account linking flow from the Home app:
   1. Open the [Google Home app (GHA)](https://play.google.com/store/apps/details?id=com.google.android.apps.chromecast.app).
   2. Click the **+** button.
   3. Click **Set up device**.
   4. Click **Have something already set up?**
   5. Select your Cloud-to-cloud integration from the list of providers. It will be prefixed with "\[test\]" in the list. When you select your \[test\] integration from the list, it should open your app.
   6. Verify that your app was launched and begin testing your authorization flow.