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
andredirect_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
andstate
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
): Googleclient_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.
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
.