App Flip for iOS

OAuth-based App Flip linking (App Flip) opens your iOS app from a Google app to help the Google app user link their account more easily. You need to make minor code changes to your iOS app to implement this feature.

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

Try the sample

The App Flip sample app demonstrates an account linking integration on iOS that's App Flip-compatible. You can use this app to verify how to respond to an incoming App Flip universal link from Google mobile apps.

The sample app is preconfigured to integrate with the App Flip Test Tool for iOS, which you can use to verify your iOS app's integration with App Flip before you configure account linking with Google. This app simulates the universal link triggered by Google mobile apps when App Flip is enabled.

How it works

The following are the flow steps that the Google app and your app take when App Flip occurs:

The Google app attempts to open your app’s universal link. It's able to open your app if it's installed on the user’s device and associated with the universal link. See Supporting Universal Links for details.
Your app checks that the client_id and redirect_uri parameter encoded in the incoming URL matches the expected Google universal link.
Your app requests an authorization code from your OAuth2 server. At the end of this flow, your app returns either an authorization code or an error to the Google app. To do this, it opens Google's universal link with appended parameters for the authorization code or error.
The Google app handles the incoming Google universal link and continues with the rest of the flow. If an authorization code is provided, the linking is completed immediately. The token exchange happens server-to-server, the same way it does in the browser-based OAuth linking flow. If an error code is returned, the linking flow continues with the alternative options.

Modify your iOS app to support App Flip

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

Handle NSUserActivityTypeBrowsingWeb in your App Delegate.
Capture redirect_uri and state parameters from the URL to use later.

Check that redirect_uri matches this format:

https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

Verify that the client ID matches the expected value. Use the following code sample:

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool
{
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL,
        let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
        let params = components.queryItems else {
            return false
    }

    if let clientId = params.filter({$0.name == "client_id"}).first?.value,
        let state = params.filter({$0.name == "state"}).first?.value,
        let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {

        // Save the redirect_uri and state for later...

        // Verify the client id
        return (clientId == GOOGLE_CLIENT_ID)
    } else {
        // Missing required parameters
        return false
    }
}

Upon successful authorization, call the redirect URI with the authorization code. Use the following code sample:

func returnAuthCode(code: String, state: String, redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramAuthCode = URLQueryItem(name: "code", value: code)
    let paramState = URLQueryItem(name: "state", value: state)
    components?.queryItems = [paramAuthCode, paramState]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

If an error occurred, attach an error result to the redirect URI instead. Use the following code sample:

func returnError(redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramError = URLQueryItem(name: "error", value: "invalid_request")
    let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
    components?.queryItems = [paramError, paramDescription]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

Query parameters for your app’s universal link

When opened by the Google app, your app’s universal link includes the following query parameters:

client_id (String): Google client_id that's registered under your app.
scope (List of String): A list of space-separated scopes requested.
state (String): A nonce used by Google to verify that the authorization result is in response to Google’s outgoing request.
redirect_uri (String): Google's universal link. The "flip" URI to open the Google app and pass results.

Query parameters for Google’s universal link

Parameters used when the authorization result is returned successfully:

code (String): The value of the authorization code, if available.
state (String): The exact value received from the incoming universal link.

Parameters used when the authorization result is returned unsuccessfully:

error (String), with the following values:
- cancelled: A recoverable error. The Google app will attempt account linking using the authorization URL. Some examples are the user failing to sign in, a device being offline or a connection timing out.
- unrecoverable: An unrecoverable error. For example, the user attempts to link with a disabled account.The Google app will abort account linking.
- invalid_request: The request parameters are invalid or missing. This is a recoverable error. The Google app will attempt account linking using the authorization URL.
- access_denied: The user rejects the consent request. This is a non-recoverable error; the Google app aborts linking.
error_description (String, optional): A user-friendly error message.

Note: For more information on possible errors and the optional contents of the error_description field, see the OAuth 2.0 standard.

For all error types, you must return the response data to the specified REDIRECT_URI to ensure the appropriate fallback is trigerred.

Modify your authorization endpoint to support App Flip

Configure your platform to accept requests using Google's App Flip redirect URLs:

Google Home app

https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast

Google Assistant app

https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.OPA
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA

Check that client_id and the URL specified by the redirect_uri parameter match the expected values when a request is received. if the client verification fails, return the error invalid_request to the redirect_uri.