Android용 앱 플립

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

디자인 가이드라인

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

요구사항

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

권장사항

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

  1. Google 개인정보처리방침을 표시합니다. 동의 화면에 Google 개인정보처리방침 링크를 포함합니다.

  2. 공유할 데이터 명확하고 간결한 표현을 사용하여 Google에 필요한 사용자 데이터와 그 이유를 사용자에게 설명합니다.

  3. 연결 해제 기능 사용자가 연결을 해제할 수 있는 메커니즘을 제공합니다(예: 플랫폼의 계정 설정 URL). 또는 사용자가 연결된 계정을 관리할 수 있는 Google 계정 링크를 포함할 수 있습니다.

  4. 사용자 계정을 변경할 수 있습니다. 사용자가 계정을 전환할 수 있는 방법을 제안합니다. 이는 사용자가 계정을 여러 개 보유하는 경향이 있는 경우 특히 유용합니다.

    • 사용자가 계정을 전환하기 위해 동의 화면을 닫아야 하는 경우 사용자가 OAuth 연결 및 암시적 흐름으로 원하는 계정에 로그인할 수 있도록 복구 가능한 오류를 Google에 전송하세요.

  5. 로고를 포함합니다. 동의 화면에 회사 로고를 표시합니다. 스타일 가이드라인에 따라 로고를 배치합니다. Google 로고도 표시하려면 로고 및 상표를 참고하세요.

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

OAuth 기반 App Flip 설정

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

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

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

Play Console에서 앱 전환 구성

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

  1. 계정 연결에서 필수(*) 입력란을 모두 작성합니다. (앱 전환이 지원되지 않는 경우 일반 OAuth가 대체로 사용됩니다.)
  2. Cloud 처리 URL의 URL을 입력합니다. 클라우드 처리 URL은 스마트 홈 인텐트를 처리하는 데 사용됩니다. 로컬 처리를 선택합니다.
  3. 앱 전환 (선택사항)에서 Android 앱을 선택합니다.
  4. 다음 입력란을 작성합니다.
    • 애플리케이션 ID 애플리케이션 ID는 앱에 설정하는 고유 ID입니다.
    • 앱 서명. Android 앱은 설치하기 전에 공개 키 인증서로 '서명'해야 합니다. 앱 서명을 가져오는 방법에 관한 자세한 내용은 클라이언트 인증을 참고하세요.
    • 승인 인텐트 이 필드에 인텐트 작업을 지정하는 문자열을 입력합니다.
  5. 클라이언트를 선택적으로 구성하려면 범위를 추가하고 범위(선택사항)에서 범위 추가를 클릭합니다.
  6. 클라이언트에 필요한 경우 Google에서 HTTP 기본 인증 헤더를 통해 클라이언트 ID 및 보안 비밀번호를 전송하도록 설정을 선택합니다.

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

네이티브 앱에 App Flip 구현

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

OAuth 기반 앱 전환 연결 (앱 전환)은 Android 앱을 Google 계정 연결 흐름에 삽입합니다. 기존 계정 연결 흐름에서는 사용자가 브라우저에 사용자 인증 정보를 입력해야 합니다. 앱 전환을 사용하면 사용자 로그인이 Android 앱으로 지연되므로 기존 승인을 활용할 수 있습니다. 사용자가 앱에 로그인되어 있으면 계정을 연결하기 위해 사용자 인증 정보를 다시 입력할 필요가 없습니다. Android 앱에서 앱 전환을 구현하려면 최소한의 코드 변경이 필요합니다.

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

샘플 사용해 보기

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

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

작동 방식

앱 전환 통합을 실행하려면 다음 단계를 따라야 합니다.

  1. Google 앱은 패키지 이름을 사용하여 앱이 기기에 설치되어 있는지 확인합니다.
  2. Google 앱은 패키지 서명 검사를 사용하여 설치된 앱이 올바른 앱인지 확인합니다.
  3. Google 앱은 앱에서 지정된 활동을 시작하는 인텐트를 빌드합니다. 이 인텐트에는 연결에 필요한 추가 데이터가 포함됩니다. 또한 Android 프레임워크를 통해 이 인텐트를 확인하여 앱이 앱 전환을 지원하는지 확인합니다.
  4. 앱은 요청이 Google 앱에서 전송되었는지 확인합니다. 이를 위해 앱은 패키지 서명과 제공된 클라이언트 ID를 확인합니다.
  5. 앱이 OAuth 2.0 서버에서 승인 코드를 요청합니다. 이 흐름이 끝나면 승인 코드 또는 오류가 Google 앱에 반환됩니다.
  6. Google 앱은 결과를 가져오고 계정 연결을 계속합니다. 승인 코드가 제공되면 브라우저 기반 OAuth 연결 흐름과 동일한 방식으로 서버 간에 토큰 교환이 이루어집니다.

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

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

  1. 앱 전환 인텐트 필드에 입력한 값과 일치하는 작업 문자열을 사용하여 AndroidManifest.xml 파일에 <intent-filter>를 추가합니다.

    <activity android:name="AuthActivity">
  <!-- Handle the app flip intent -->
  <intent-filter>
    <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
    <category android:name="android.intent.category.DEFAULT"/>
  </intent-filter>
</activity>

  2. 호출 앱의 서명을 검증합니다.

    사용자가 계정 연결에 사용할 수 있는 모든 Google 앱의 패키지 이름과 서명을 일치시켜야 합니다. 예를 들어 Google Home 및 Google 검색 앱과 연결하려면 패키지 이름과 서명을 추가합니다.

    • Package name: com.google.android.apps.chromecast.app
    • 원본 SHA-256 계보 인증서: 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
    • 순환된 Play 앱 서명 SHA-256 인증서: 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

    및

    • Package name: com.google.android.googlequicksearchbox
    • 서명: F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83

    스마트 홈 연결 요청은 Google Home app (GHA)에서 직접 시작됩니다. 애플리케이션에서 호출자를 제한하고 이전에 Google 검색 앱만 허용한 경우 앱 전환이 계속 작동하도록 com.google.android.apps.chromecast.app 및 SHA-256 인증서를 허용 목록에 추가해야 합니다.

    private fun verifyFingerprint(
    expectedPackage: String,
    expectedFingerprints: List<String>
): Boolean {
    val callingPackage = callingActivity?.packageName ?: return false
    if (callingPackage != expectedPackage) return false
    return expectedFingerprints.any { hex ->
        val sha256Bytes =
            hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
        packageManager.hasSigningCertificate(
            callingPackage,
            sha256Bytes,
            PackageManager.CERT_INPUT_SHA256
        )
    }
}

  3. 인텐트 매개변수에서 클라이언트 ID를 추출하고 클라이언트 ID가 예상 값과 일치하는지 확인합니다.

    private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
// Original lineage certificate (3D:7A...) and active rotated
// Play App Signing certificate (5A:AD...)
private val EXPECTED_FINGERPRINTS = listOf(
    "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
    "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
)
...

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val clientId = intent.getStringExtra("CLIENT_ID")

    if (clientId == EXPECTED_CLIENT &&
        verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {

        // ...authorize the user...
    }
}

  4. 승인이 완료되면 결과 승인 코드를 Google에 반환합니다.

    // Successful result
val data = Intent().apply {
    putExtra("AUTHORIZATION_CODE", authCode)
}
setResult(Activity.RESULT_OK, data)
finish()

  5. 오류가 발생하면 오류 결과를 반환합니다.

    // Error result
val error = Intent().apply {
    putExtra("ERROR_TYPE", 1)
    putExtra("ERROR_CODE", 1)
    putExtra("ERROR_DESCRIPTION", "Invalid Request")
}
setResult(-2, error)
finish()

실행 인텐트의 콘텐츠

앱을 실행하는 Android 인텐트에는 다음 필드가 포함됩니다.

  • CLIENT_ID (String): 앱에 등록된 Google client_id입니다.
  • SCOPE (String[]): 요청된 범위 목록입니다.
  • REDIRECT_URI (String): 리디렉션 URL입니다.

응답 데이터의 콘텐츠

Google 앱에 반환되는 데이터는 setResult()를 호출하여 앱에서 설정됩니다. 이 데이터에는 다음이 포함됩니다.

  • AUTHORIZATION_CODE (String): 승인 코드 값입니다.
  • resultCode (int): 프로세스의 성공 또는 실패를 전달하고 다음 값 중 하나를 사용합니다.
    • Activity.RESULT_OK: 성공을 나타내며 승인 코드가 반환됩니다.
    • Activity.RESULT_CANCELLED: 복구 가능한 오류입니다. 사용자가 프로세스를 취소했음을 알립니다. 이 경우 Google 앱은 승인 URL을 사용하여 계정 연결을 다시 시도합니다.
    • -2: 오류가 발생했음을 나타냅니다. 다양한 유형의 오류는 아래에 설명되어 있습니다.
  • ERROR_TYPE (int): 오류 유형으로, 다음 값 중 하나를 사용합니다.
    • 1: 복구 가능한 오류: Google 앱이 승인 URL을 사용하여 계정 연결을 시도합니다.
    • 2: 복구 불가 오류: Google 앱에서 계정 연결을 중단합니다.
    • 3: 요청 매개변수가 잘못되었거나 누락되었습니다.
  • ERROR_CODE (int): 오류의 성격을 나타내는 정수입니다. 각 오류 코드의 의미를 확인하려면 오류 코드 표를 참조하세요.

  • ERROR_DESCRIPTION (String, 선택사항): 오류를 설명하는 인간이 읽을 수 있는 상태 메시지입니다.

resultCode == Activity.RESULT_OK인 경우 AUTHORIZATION_CODE 값이 필요합니다. 다른 모든 경우에는 AUTHORIZATION_CODE 값이 비어 있어야 합니다. resultCode == -2인 경우 ERROR_TYPE 값이 채워질 것으로 예상됩니다.

오류 코드 표

아래 표에는 다양한 오류 코드와 각 오류가 복구 가능한 오류인지 복구 불가능한 오류인지가 나와 있습니다.

오류 코드 의미 복구 가능 Unrecoverable
1 INVALID_REQUEST ✔
2 NO_INTERNET_CONNECTION ✔
3 OFFLINE_MODE_ACTIVE ✔
4 CONNECTION_TIMEOUT ✔
5 INTERNAL_ERROR ✔
6 AUTHENTICATION_SERVICE_UNAVAILABLE ✔
8 CLIENT_VERIFICATION_FAILED ✔
9 INVALID_CLIENT ✔
10 INVALID_APP_ID ✔
11 INVALID_REQUEST ✔
12 AUTHENTICATION_SERVICE_UNKNOWN_ERROR ✔
13 AUTHENTICATION_DENIED_BY_USER ✔
14 CANCELLED_BY_USER ✔
15 FAILURE_OTHER ✔
16 USER_AUTHENTICATION_FAILED ✔

모든 오류 코드의 경우 적절한 대체가 트리거되도록 setResult를 통해 오류 결과를 반환해야 합니다.

기기에서 App Flip 테스트

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

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

  1. Developer Console로 이동하여 프로젝트를 선택합니다.
  2. Cloud-to-cloud > Test로 이동합니다.
  3. Home 앱에서 계정 연결 흐름을 트리거합니다.
    1. Google Home app (GHA)를 엽니다.
    2. 화면의 + 버튼을 클릭합니다.
    3. 장치 설정을 클릭하세요.
    4. I have already set up my Google Ads account. How do I link it to my YouTube channel?
    5. 제공업체 목록에서 클라우드 간 통합을 선택합니다. 목록에서 '[test]'가 프리픽스로 추가됩니다. 목록에서 [테스트] 통합을 선택하면 앱이 열립니다.
    6. 앱이 실행되었는지 확인하고 승인 흐름 테스트를 시작합니다.
이전
클라우드 간 통합 만들기
다음
iOS