Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
A vinculação de app baseado em OAuth (App Flip) abre seu app iOS em um app do Google
para ajudar o usuário do Google app a vincular a conta com mais facilidade. Você precisa fazer
pequenas alterações no código do seu aplicativo iOS para implementar esse recurso.
Neste documento, você vai aprender a modificar seu app iOS para que ele seja compatível com o App Flip.
Testar o exemplo
App de exemplo App Flip
demonstra uma integração de vinculação de contas no iOS compatível com o App Flip.
Você pode usar este app para verificar como responder a um App Flip universal recebido
dos apps para dispositivos móveis do Google.
O app de exemplo está pré-configurado para integração com a App Flip Test Tool para
iOS
que você pode usar para verificar a integração do seu app iOS com o App Flip antes
você configura a vinculação de contas com o Google. Este app simula o link universal
acionada pelos apps para dispositivos móveis do Google quando o App Flip está ativado.
Como funciona
Confira a seguir as etapas de fluxo que o Google app e seu app seguem ao
A virada de app ocorre:
O Google app tenta abrir o link universal do seu app. Ele é capaz de
abrem o app se ele estiver instalado no dispositivo do usuário e associado a
o link universal. Consulte Suporte a links universais para ver mais detalhes.
O app verifica se os parâmetros client_id e redirect_uri estão codificados
no URL de entrada corresponde ao link universal esperado do Google.
O app solicita um código de autorização do servidor OAuth2. No fim
desse fluxo, seu aplicativo retorna um código de autorização ou um erro para
Google app. Para isso, ele abre o link universal do Google com anexos
para o código de autorização ou erro.
O Google app processa o link universal recebido do Google e continua com
o restante do fluxo. Se um código de autorização for fornecido, a vinculação será
concluído imediatamente. A troca de tokens ocorre de servidor para servidor,
no fluxo de vinculação do OAuth baseado no navegador. Se um código de erro for
for retornado, o fluxo de vinculação continuará com as opções alternativas.
Modificar seu app iOS para oferecer suporte ao App Flip
Para oferecer suporte ao App Flip, faça as seguintes alterações de código no seu app iOS:
Gerencie o NSUserActivityTypeBrowsingWeb no delegado do app.
Capture os parâmetros redirect_uri e state do URL para usar depois.
Verifique se redirect_uri corresponde a este formato:
Após a autorização, chame o URI de redirecionamento com a autorização
o código-fonte. Use o exemplo de código a seguir:
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)}}
Se ocorrer um erro, anexe um resultado de erro ao URI de redirecionamento.
Use o exemplo de código a seguir:
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)}}
Parâmetros de consulta para o link universal do seu app
Quando aberto pelo Google app, o link universal do seu app inclui o seguinte:
parâmetros de consulta:
client_id (String): Google client_id que está registrado no app.
scope (List of String): uma lista de escopos separados por espaços solicitados.
state (String): um valor de uso único usado pelo Google para verificar se a autorização
resultado é uma resposta à solicitação enviada pelo Google.
redirect_uri (String): link universal do Google. A "virada" URI a ser aberto
o Google app e transmitir os resultados.
Parâmetros de consulta para o link universal do Google
Parâmetros usados quando o resultado da autorização é retornado com sucesso:
code (String): o valor do código de autorização, se disponível.
state (String): o valor exato recebido do link universal recebido.
Parâmetros usados quando o resultado da autorização é retornado com falha:
error (String), com os seguintes valores:
cancelled: um erro recuperável. O Google app tentará
usando o URL de autorização. Alguns exemplos são os casos de
para fazer login, quando um dispositivo está off-line ou o tempo limite de uma conexão se esgotou.
unrecoverable: um erro irrecuperável. Por exemplo, o usuário tenta vincular com uma conta desativada.O Google app vai cancelar a vinculação da conta.
invalid_request: os parâmetros da solicitação são inválidos ou estão ausentes. Este é um erro recuperável. O Google app tentará vincular a conta usando o URL de autorização.
access_denied: o usuário recusa a solicitação de consentimento. Este é um erro não recuperável; o Google app cancela a vinculação.
error_description (String, opcional): é uma mensagem de erro fácil de usar.
Para todos os tipos de erro, você deve retornar os dados de resposta para o método
REDIRECT_URI para garantir que o substituto apropriado seja acionado.
Modifique seu endpoint de autorização para oferecer suporte ao App Flip
Configure sua plataforma para aceitar solicitações usando os URLs de redirecionamento do App Flip do Google:
Verifique se client_id e o URL especificado pelo parâmetro redirect_uri
correspondem aos valores esperados quando uma solicitação é recebida. se a verificação do cliente
falhar, retorne o erro invalid_request ao redirect_uri.
[null,null,["Última atualização 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`."]]
