Google은 서드 파티 스마트 홈 계정 연결이 Google Home 앱 내에서 완전히 독립적으로 처리되도록 전환하고 있습니다. 2026년 10월 30일 전에 통합을 업데이트해야 할 수 있습니다. 자세한 내용은 계정 연결 이전 가이드를 참고하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

iOS용 앱 플립

OAuth 2.0 구현이 완료되면 원하는 경우 OAuth 기반 App Flip를 구성할 수 있습니다. 이를 통해 iOS 사용자는 인증 시스템의 계정을 Google 계정에 더 빠르게 연결할 수 있습니다. 다음 섹션에서는 iOS에서 Cloud-to-cloud 통합을 위해 App Flip를 설계하고 구현하는 방법을 설명합니다.

디자인 가이드라인

이 섹션에서는 앱 전환 계정 연결 동의 화면의 설계 요구사항과 권장사항을 설명합니다. Google이 앱을 호출하면 앱은 사용자에게 동의 화면을 표시합니다.

요구사항

'연결되면 Google에서 기기를 제어할 수 있습니다'와 같은 Google 승인 문구가 있어야 합니다.
사용자의 계정이 Google Home 또는 Google 어시스턴트와 같은 특정 Google 제품이 아닌 Google에 연결된다고 알려야 합니다.
동의 화면에 명확한 클릭 유도 문구를 명시하고 연결 작업에는 '동의 및 연결'이라는 문구를 사용해야 합니다. 이는 사용자가 계정을 연결하기 위해 Google과 공유해야 하는 데이터를 이해해야 하기 때문입니다.
사용자가 연결하지 않기로 선택한 경우 뒤로 이동하거나 거부하거나 취소할 수 있는 방법을 제공해야 합니다. 취소 작업에는 '취소'라는 문구를 사용합니다.
'동의 및 연결'을 클릭한 후 연결 성공을 표시하고 사용자를 Google Home 앱으로 자동으로 리디렉션해야 합니다. 이제 사용자는 Google Home 앱에서 연결된 기기를 작업과 함께 확인할 수 있습니다. '취소'를 클릭한 후 사용자를 Google Home 앱으로 다시 리디렉션해야 합니다.

권장사항

다음을 수행하는 것이 좋습니다.

Google 개인정보처리방침을 표시합니다. 동의 화면에 Google 개인정보처리방침 링크를 포함합니다.
공유할 데이터 명확하고 간결한 표현을 사용하여 Google에 필요한 사용자 데이터와 그 이유를 사용자에게 설명합니다.
연결 해제 기능 사용자가 연결을 해제할 수 있는 메커니즘을 제공합니다(예: 플랫폼의 계정 설정 URL). 또는 사용자가 연결된 계정을 관리할 수 있는 Google 계정 링크를 포함할 수 있습니다.
사용자 계정을 변경할 수 있습니다. 사용자가 계정을 전환할 수 있는 방법을 제안합니다. 이는 사용자가 계정을 여러 개 보유하는 경향이 있는 경우 특히 유용합니다.
- 사용자가 계정을 전환하기 위해 동의 화면을 닫아야 하는 경우 사용자가 OAuth 연결 및 암시적 흐름으로 원하는 계정에 로그인할 수 있도록 복구 가능한 오류를 Google에 전송하세요.
로고를 포함합니다. 동의 화면에 회사 로고를 표시합니다. 스타일 가이드라인에 따라 로고를 배치합니다. Google 로고도 표시하려면 로고 및 상표를 참고하세요.

이 그림은 사용자 동의 화면을 설계할 때 따라야 하는 개별 요구사항과 권장사항을 설명하는 콜아웃이 있는 동의 화면의 예를 보여줍니다. — 그림 1: 계정 연결 동의 화면 디자인 가이드라인

OAuth 기반 App Flip 설정

다음 섹션에서는 OAuth 기반 앱 전환의 기본 요건과 Google Home Developer Console에서 앱 전환 프로젝트를 구성하는 방법을 설명합니다.

Cloud-to-Cloud 통합을 만들고 OAuth 2.0 서버 설정

App Flip를 구성하려면 먼저 다음을 수행해야 합니다.

OAuth 2.0 서버를 설정합니다. OAuth 서버 설정에 관한 자세한 내용은 OAuth 2.0 서버 구현을 참고하세요.
클라우드 간 통합을 만듭니다. 통합을 만들려면 클라우드 간 통합 만들기의 안내를 따르세요.

Play Console에서 앱 전환 구성

다음 섹션에서는 Developer Console에서 앱 전환을 구성하는 방법을 설명합니다.

OAuth 클라이언트 정보의 모든 입력란을 작성합니다. (App Flip가 지원되지 않으면 일반 OAuth가 대체로 사용됩니다.)
계정 연결에 앱 사용(선택사항)에서 iOS에 사용 설정을 선택합니다.
범용 링크 입력란을 작성합니다. 범용 링크에 관한 자세한 내용은 앱 및 웹사이트에서 콘텐츠에 연결하도록 허용을 참고하세요.
원하는 경우 클라이언트를 구성하려면 범위를 추가하고 클라이언트 구성 (선택사항)에서 범위 추가를 클릭합니다.
저장을 클릭합니다.

이제 다음 섹션으로 이동하여 iOS 앱에 App Flip를 구현할 수 있습니다.

네이티브 앱에 App Flip 구현

App Flip를 구현하려면 Google의 딥 링크를 허용하도록 앱의 사용자 승인 코드를 수정해야 합니다.

OAuth 기반 앱 전환 연결 (앱 전환)은 Google 앱에서 iOS 앱을 열어 Google 앱 사용자가 계정을 더 쉽게 연결할 수 있도록 합니다. 이 기능을 구현하려면 iOS 앱의 코드를 약간 변경해야 합니다.

이 문서에서는 앱 전환을 지원하도록 iOS 앱을 수정하는 방법을 알아봅니다.

샘플 사용해 보기

앱 전환 샘플 앱은 앱 전환과 호환되는 iOS의 계정 연결 통합을 보여줍니다. 이 앱을 사용하여 Google 모바일 앱에서 수신되는 앱 전환 범용 링크에 응답하는 방법을 확인할 수 있습니다.

샘플 앱은 iOS용 앱 전환 테스트 도구와 통합되도록 사전 구성되어 있으며, 이를 사용하여 Google과의 계정 연결을 구성하기 전에 iOS 앱과 앱 전환의 통합을 확인할 수 있습니다. 이 앱은 앱 전환이 사용 설정된 경우 Google 모바일 앱에서 트리거하는 범용 링크를 시뮬레이션합니다.

작동 방식

다음은 앱 전환이 발생할 때 Google 앱과 개발자 앱에서 수행하는 흐름 단계입니다.

Google 앱이 앱의 범용 링크를 열려고 시도합니다. 사용자의 기기에 앱이 설치되어 있고 범용 링크와 연결되어 있으면 앱을 열 수 있습니다. 자세한 내용은 범용 링크 지원을 참고하세요.
앱은 수신 URL에 인코딩된 client_id 및 redirect_uri 매개변수가 예상되는 Google 범용 링크와 일치하는지 확인합니다.
앱이 OAuth2 서버에 승인 코드를 요청합니다. 이 흐름이 끝나면 앱은 승인 코드 또는 오류를 Google 앱에 반환합니다. 이를 위해 승인 코드 또는 오류에 대한 매개변수가 추가된 Google의 범용 링크를 엽니다.
Google 앱은 수신되는 Google 범용 링크를 처리하고 나머지 흐름을 계속 진행합니다. 승인 코드가 제공되면 연결이 즉시 완료됩니다. 토큰 교환은 브라우저 기반 OAuth 연결 흐름과 동일한 방식으로 서버 간에 이루어집니다. 오류 코드가 반환되면 연결 흐름이 대체 옵션으로 계속됩니다.

앱 전환을 지원하도록 iOS 앱 수정

앱 전환을 지원하려면 iOS 앱을 다음과 같이 변경합니다.

앱 대리자에서 NSUserActivityTypeBrowsingWeb를 처리합니다.
나중에 사용할 수 있도록 URL에서 redirect_uri 및 state 매개변수를 캡처합니다.

redirect_uri가 다음 형식과 일치하는지 확인합니다.

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

클라이언트 ID가 예상 값과 일치하는지 확인합니다. 다음 코드 샘플을 사용합니다.

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
    }
}

승인이 완료되면 승인 코드를 사용하여 리디렉션 URI를 호출합니다. 다음 코드 샘플을 사용합니다.

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)
    }
}

오류가 발생하면 대신 리디렉션 URI에 오류 결과를 연결합니다. 다음 코드 샘플을 사용합니다.

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)
    }
}

앱의 범용 링크에 대한 쿼리 매개변수

Google 앱에서 열면 앱의 범용 링크에 다음 쿼리 매개변수가 포함됩니다.

client_id (String): 앱에 등록된 Google client_id입니다.
scope (List of String): 요청된 범위의 공백으로 구분된 목록입니다.
state (String): 승인 결과가 Google의 발신 요청에 대한 응답인지 확인하기 위해 Google에서 사용하는 nonce입니다.
redirect_uri (String): Google의 범용 링크입니다. Google 앱을 열고 결과를 전달하는 'flip' URI입니다.

Google 범용 링크의 쿼리 매개변수

승인 결과가 성공적으로 반환될 때 사용되는 매개변수:

code(String): 승인 코드 값입니다(사용 가능한 경우).
state (String): 수신되는 범용 링크에서 수신된 정확한 값입니다.

승인 결과가 실패로 반환될 때 사용되는 매개변수:

error (String) - 다음 값을 사용합니다.
- cancelled: 복구 가능한 오류입니다. Google 앱은 승인 URL을 사용하여 계정 연결을 시도합니다. 예를 들어 사용자가 로그인에 실패하거나 기기가 오프라인 상태이거나 연결 시간이 초과되는 경우가 있습니다.
- unrecoverable: 복구 불가 오류입니다. 예를 들어 사용자가 사용 중지된 계정에 연결하려고 하면 Google 앱에서 계정 연결을 중단합니다.
- invalid_request: 요청 매개변수가 잘못되었거나 누락되었습니다. 복구 가능한 오류입니다. Google 앱은 승인 URL을 사용하여 계정 연결을 시도합니다.
- access_denied: 사용자가 동의 요청을 거부합니다. 이는 복구할 수 없는 오류입니다. Google 앱에서 연결을 중단합니다.
error_description (String, 선택사항): 사용자 친화적인 오류 메시지입니다.

참고: 발생 가능한 오류 및 error_description 필드의 선택적 콘텐츠에 대한 자세한 내용은 OAuth 2.0 표준을 참조하세요.

모든 오류 유형의 경우 적절한 대체가 트리거되도록 응답 데이터를 지정된 REDIRECT_URI에 반환해야 합니다.

앱 전환을 지원하도록 승인 엔드포인트 수정

Google의 앱 전환 리디렉션 URL을 사용하여 요청을 수락하도록 플랫폼을 구성합니다.

Google Home 앱

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 어시스턴트 앱

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

Google Home app (GHA)의 경우 스마트 홈 계정 연결은 com.google.Chromecast 리디렉션 URL을 사용합니다. 승인 서버에서 이러한 리디렉션 URL을 허용하는지 확인하세요.

요청이 수신되면 client_id 및 redirect_uri 매개변수로 지정된 URL이 예상 값과 일치하는지 확인합니다. 클라이언트 확인에 실패하면 redirect_uri에 invalid_request 오류를 반환합니다.

기기에서 App Flip 테스트

클라우드 간 통합을 만들고 콘솔과 앱에서 앱 전환을 구성했으므로 이제 휴대기기에서 앱 전환을 테스트할 수 있습니다. Google Home 앱을 사용하여 앱 전환을 테스트할 수 있습니다.

Google Home 앱에서 App Flip를 테스트하려면 다음 단계를 따르세요.

Developer Console로 이동하여 프로젝트를 선택합니다.
Cloud-to-cloud > Test로 이동합니다.
Home 앱에서 계정 연결 흐름을 트리거합니다.

Google Home app (GHA)를 엽니다.
화면의 + 버튼을 클릭합니다.
장치 설정을 클릭하세요.
I have already set up my Google Ads account. How do I link it to my YouTube channel?
제공업체 목록에서 클라우드 간 통합을 선택합니다. 목록에서 '[test]'가 프리픽스로 추가됩니다. 목록에서 [테스트] 통합을 선택하면 앱이 열립니다.
앱이 실행되었는지 확인하고 승인 흐름 테스트를 시작합니다.

Android

식별 및 동기화