Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
OAuth-basierte App-Flip-Verknüpfung (App Flip) öffnet Ihre iOS-App über eine Google-App.
damit Nutzer der Google App ihr Konto leichter verknüpfen können. Sie müssen
kleinere Codeänderungen an Ihrer iOS-App vornehmen, um diese Funktion zu implementieren.
In diesem Dokument erfahren Sie, wie Sie Ihre iOS-App so ändern, dass sie App Flip unterstützt.
Beispiel ausprobieren
Beispiel-App „App Flip“
zeigt eine Kontoverknüpfungsintegration unter iOS, die mit App Flip kompatibel ist.
Mit dieser App kannst du überprüfen, wie du auf eingehende App Flip universelle Antworten
von mobilen Google-Apps aus.
Die Beispiel-App ist für die Integration in das App-Flip-Testtool für
iOS
Damit können Sie die Integration Ihrer iOS-App mit App-Flip überprüfen,
konfigurieren Sie die Kontoverknüpfung mit Google. Diese App simuliert den universellen Link
wird von mobilen Google-Apps ausgelöst, wenn App Flip aktiviert ist.
Funktionsweise
Die Google App und Ihre App führen folgende Schritte aus, wenn
App-Flip:
Die Google App versucht, den universellen Link Ihrer App zu öffnen. Sie kann
Ihre App öffnen, wenn sie auf dem Gerät des Nutzers installiert und mit
den universellen Link. Weitere Informationen finden Sie unter Unterstützen von universellen Links.
Deine App prüft, ob die Parameter client_id und redirect_uri codiert sind
in der eingehenden URL mit dem erwarteten universellen Google-Link übereinstimmt.
Ihre Anwendung fordert einen Autorisierungscode von Ihrem OAuth2-Server an. Am Ende
dieses Vorgangs gibt Ihre Anwendung entweder einen Autorisierungscode oder einen Fehler an
der Google App. Dazu wird der universelle Link von Google mit angehängten
-Parameter für den Autorisierungscode oder -fehler.
Die Google App verarbeitet die eingehende universelle Google-Verknüpfung und fährt mit
für den Rest des Ablaufs. Wenn ein Autorisierungscode angegeben wird, erfolgt die Verknüpfung
sofort abgeschlossen werden. Der Tokenaustausch erfolgt
Server-zu-Server.
wie im browserbasierten OAuth-Verknüpfungsvorgang. Wenn ein Fehlercode
zurückgegeben wird, wird der Verknüpfungsvorgang mit den alternativen Optionen fortgesetzt.
iOS-App für App Flip anpassen
Nehmen Sie die folgenden Codeänderungen an Ihrer iOS-App vor, um App-Flip zu unterstützen:
Verarbeiten Sie NSUserActivityTypeBrowsingWeb in Ihrem App Delegate.
Erfassen Sie die Parameter redirect_uri und state aus der URL, um sie später zu verwenden.
Rufen Sie nach erfolgreicher Autorisierung den Weiterleitungs-URI mit der Autorisierung auf.
Code. Verwenden Sie das folgende Codebeispiel:
funcreturnAuthCode(code:String,state:String,redirectUri:String){varredirectURL=URL(string:redirectUri)varcomponents=URLComponents(url:redirectURL,resolvingAgainstBaseURL:false)// Return the authorization code and original stateletparamAuthCode=URLQueryItem(name:"code",value:code)letparamState=URLQueryItem(name:"state",value:state)components?.queryItems=[paramAuthCode,paramState]ifletresultURL=components?.url{UIApplication.shared.open(resultURL,options:[UIApplicationOpenURLOptionUniversalLinksOnly:true],completionHandler:nil)}}
Wenn ein Fehler aufgetreten ist, hängen Sie stattdessen ein Fehlerergebnis an den Weiterleitungs-URI an.
Verwenden Sie das folgende Codebeispiel:
funcreturnError(redirectUri:String){varredirectURL=URL(string:redirectUri)varcomponents=URLComponents(url:redirectURL,resolvingAgainstBaseURL:false)// Return the authorization code and original stateletparamError=URLQueryItem(name:"error",value:"invalid_request")letparamDescription=URLQueryItem(name:"error_description",value:"Invalid Request")components?.queryItems=[paramError,paramDescription]ifletresultURL=components?.url{UIApplication.shared.open(resultURL,options:[UIApplicationOpenURLOptionUniversalLinksOnly:true],completionHandler:nil)}}
Suchparameter für den universellen Link Ihrer App
Wenn der universelle Link Ihrer App in der Google App geöffnet wird, enthält er Folgendes:
Suchparameter:
client_id (String): Google client_id, das unter deiner App registriert ist.
scope (List of String): Eine Liste der durch Leerzeichen getrennten Bereiche, die angefordert wurden.
state (String): Eine Nonce, mit der Google überprüft, ob die Autorisierung
auf die ausgehende Anfrage von Google folgt.
redirect_uri (String): Universeller Link von Google. Die Umklappe Zu öffnender URI
und die Ergebnisse übergeben.
Suchparameter für den universellen Link von Google
Parameter, die verwendet werden, wenn das Autorisierungsergebnis erfolgreich zurückgegeben wird:
code (String): Der Wert des Autorisierungscodes, falls verfügbar.
state (String): Der genaue Wert, der vom eingehenden universellen Link empfangen wird.
Parameter, die verwendet werden, wenn das Autorisierungsergebnis nicht zurückgegeben wird:
error (String) mit den folgenden Werten:
cancelled: Ein behebbarer Fehler. Die Google App versucht, dein Konto
über die Autorisierungs-URL verknüpft werden. Ein Beispiel hierfür sind Fehler,
wenn ein Gerät offline ist oder die Verbindung abbricht.
unrecoverable: Ein nicht behebbarer Fehler. Wenn der Nutzer beispielsweise versucht, eine Verknüpfung mit einem deaktivierten Konto herzustellen, wird die Kontoverknüpfung von der Google App abgebrochen.
invalid_request: Die Anfrageparameter sind ungültig oder fehlen. Dies ist ein behebbarer Fehler. Die Google App versucht, die Kontoverknüpfung mithilfe der Autorisierungs-URL zu verknüpfen.
access_denied: Der Nutzer lehnt die Einwilligungsanfrage ab. Dies ist ein nicht behebbarer Fehler. bricht die Verknüpfung der Google App ab.
error_description (String, optional): Eine nutzerfreundliche Fehlermeldung.
Für alle Fehlertypen müssen die Antwortdaten an den angegebenen
REDIRECT_URI, damit das entsprechende Fallback ausgelöst wird.
Ändere deinen Autorisierungsendpunkt so, dass er App Flip unterstützt
Konfigurieren Sie Ihre Plattform so, dass Anfragen über die App-Flip-Weiterleitungs-URLs von Google akzeptiert werden:
Prüfe, ob client_id und die durch den redirect_uri-Parameter angegebene URL
Sie entsprechen den erwarteten Werten, wenn eine Anfrage eingeht. wenn die Überprüfung durch den Kunden
schlägt er fehl, wird der Fehler invalid_request an redirect_uri zurückgegeben.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Benötigte Informationen nicht gefunden","missingTheInformationINeed","thumb-down"],["Zu umständlich/zu viele Schritte","tooComplicatedTooManySteps","thumb-down"],["Nicht mehr aktuell","outOfDate","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Problem mit Beispielen/Code","samplesCodeIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-07-25 (UTC)."],[[["\u003cp\u003eOAuth-based App Flip linking simplifies account linking for Google app users by enabling them to seamlessly open your iOS app for authorization.\u003c/p\u003e\n"],["\u003cp\u003eTo support App Flip, you need to modify your iOS app to handle universal links, validate incoming parameters, and return authorization codes or errors to the Google app.\u003c/p\u003e\n"],["\u003cp\u003eYour authorization endpoint must be configured to accept Google's App Flip redirect URLs and perform client verification for incoming requests.\u003c/p\u003e\n"],["\u003cp\u003eThe App Flip sample app and test tool provide a practical demonstration and verification environment for your iOS app's integration with App Flip.\u003c/p\u003e\n"]]],[],null,["# App Flip for iOS\n\nOAuth-based App Flip linking (App Flip) opens your iOS app from a Google app\nto help the Google app user link their account more easily. You need to make\nminor code changes to your iOS app to implement this feature.\n\nIn this document, you learn how to modify your iOS app to support App Flip.\n\n### Try the sample\n\nThe App Flip [sample app](https://github.com/googlesamples/identity-appflip-ios)\ndemonstrates an account linking integration on iOS that's App Flip-compatible.\nYou can use this app to verify how to respond to an incoming App Flip universal\nlink from Google mobile apps.\n\nThe sample app is preconfigured to integrate with the [App Flip Test Tool for\niOS](https://github.com/googlesamples/identity-appflip-tester-ios),\nwhich you can use to verify your iOS app's integration with App Flip before\nyou configure account linking with Google. This app simulates the universal link\ntriggered by Google mobile apps when App Flip is enabled.\n\n### How it works\n\nThe following are the flow steps that the Google app and your app take when\nApp Flip occurs:\n\n1. The Google app attempts to open your app's universal link. It's able to\n open your app if it's installed on the user's device and associated with\n the universal link. See [Supporting Universal Links](https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content) for details.\n\n2. Your app checks that the `client_id` and `redirect_uri` parameter encoded\n in the incoming URL matches the expected Google universal link.\n\n3. Your app requests an authorization code from your OAuth2 server. At the end\n of this flow, your app returns either an authorization code or an error to\n the Google app. To do this, it opens Google's universal link with appended\n parameters for the authorization code or error.\n\n4. The Google app handles the incoming Google universal link and continues with\n the rest of the flow. If an authorization code is provided, the linking is\n completed immediately. The token exchange happens server-to-server, the same\n way it does in the browser-based OAuth linking flow. If an error code is\n returned, the linking flow continues with the alternative options.\n\n### Modify your iOS app to support App Flip\n\nTo support App Flip, make the following code changes to your iOS app:\n\n1. Handle `NSUserActivityTypeBrowsingWeb` in your App Delegate.\n2. Capture `redirect_uri` and `state` parameters from the URL to use later.\n3. Check that `redirect_uri` matches this format: \n\n ```\n https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID\n https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID\n ```\n4. Verify that the client ID matches the expected value. Use the following\n code sample:\n\n func application(_ application: UIApplication,\n continue userActivity: NSUserActivity,\n restorationHandler: @escaping ([Any]?) -\u003e Void) -\u003e Bool\n {\n guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,\n let incomingURL = userActivity.webpageURL,\n let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),\n let params = components.queryItems else {\n return false\n }\n\n if let clientId = params.filter({$0.name == \"client_id\"}).first?.value,\n let state = params.filter({$0.name == \"state\"}).first?.value,\n let redirectUri = params.filter({$0.name == \"redirect_uri\"}).first?.value {\n\n // Save the redirect_uri and state for later...\n\n // Verify the client id\n return (clientId == GOOGLE_CLIENT_ID)\n } else {\n // Missing required parameters\n return false\n }\n }\n\n5. Upon successful authorization, call the redirect URI with the authorization\n code. Use the following code sample:\n\n func returnAuthCode(code: String, state: String, redirectUri: String) {\n var redirectURL = URL(string: redirectUri)\n var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)\n\n // Return the authorization code and original state\n let paramAuthCode = URLQueryItem(name: \"code\", value: code)\n let paramState = URLQueryItem(name: \"state\", value: state)\n components?.queryItems = [paramAuthCode, paramState]\n if let resultURL = components?.url {\n UIApplication.shared.open(\n resultURL,\n options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],\n completionHandler: nil)\n }\n }\n\n6. If an error occurred, attach an error result to the redirect URI instead.\n Use the following code sample:\n\n **Note:** Do not handle the error directly within your app, instead return the error result to the `REDIRECT_URL`. This ensures that the appropriate fallback method is trigerred if the app linking flow fails. \n\n func returnError(redirectUri: String) {\n var redirectURL = URL(string: redirectUri)\n var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)\n\n // Return the authorization code and original state\n let paramError = URLQueryItem(name: \"error\", value: \"invalid_request\")\n let paramDescription = URLQueryItem(name: \"error_description\", value: \"Invalid Request\")\n components?.queryItems = [paramError, paramDescription]\n if let resultURL = components?.url {\n UIApplication.shared.open(\n resultURL,\n options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],\n completionHandler: nil)\n }\n }\n\n### Query parameters for your app's universal link\n\nWhen opened by the Google app, your app's universal link includes the following\nquery parameters:\n\n- `client_id` (`String`): Google `client_id` that's registered under your app.\n- `scope` (`List of String`): A list of space-separated scopes requested.\n- `state` (`String`): A nonce used by Google to verify that the authorization result is in response to Google's outgoing request.\n- `redirect_uri` (`String`): Google's universal link. The \"flip\" URI to open the Google app and pass results.\n\n### Query parameters for Google's universal link\n\nParameters used when the authorization result is returned successfully:\n\n- `code` (`String`): The value of the authorization code, if available.\n- `state` (`String`): The exact value received from the incoming universal link.\n\nParameters used when the authorization result is returned unsuccessfully:\n\n- `error` (`String`), with the following values:\n\n - `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.\n - `unrecoverable`: An unrecoverable error. For example, the user attempts to link with a disabled account.The Google app will abort account linking.\n - `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.\n - `access_denied`: The user rejects the consent request. This is a non-recoverable error; the Google app aborts linking.\n- `error_description` (`String`, optional): A user-friendly error message.\n\n | **Note:** 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, see the OAuth 2.0 standard.\n\nFor all error types, you must return the response data to the specified\n`REDIRECT_URI` to ensure the appropriate fallback is trigerred.\n\n### Modify your authorization endpoint to support App Flip\n\nConfigure your platform to accept requests using Google's App Flip redirect URLs:\n\n- Google Home app \n\n ```\n https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev\n https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise\n https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast\n https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev\n https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise\n https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast\n ```\n- Google Assistant app \n\n ```\n https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev\n https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise\n https://oauth-redirect.googleusercontent.com/a/com.google.OPA\n https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev\n https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise\n https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA\n ```\n\nCheck that `client_id` and the URL specified by the `redirect_uri` parameter\nmatch the expected values when a request is received. if the client verification\nfails, return the error `invalid_request` to the `redirect_uri`."]]
