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:

  1. 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.

  2. Your app checks that the client_id and redirect_uri parameter encoded in the incoming URL matches the expected Google universal link.

  3. 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.

  4. 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:

  1. Handle NSUserActivityTypeBrowsingWeb in your App Delegate.
  2. Capture redirect_uri and state parameters from the URL to use later.
  3. 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
  4. 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
        }
    }
    
  5. 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)
        }
    }
    
  6. 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)
        }
    }
    

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.

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: The Google app aborts account linking. For example, a disabled account or denied authorization prevents linking accounts.
    • invalid_request: The request parameters are invalid or missing.
  • error_description (String, optional): A user-friendly error message.

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.