Permissions API

Home API를 사용하기 전에 앱에 사용자의 홈에 있는 기기에 액세스할 권한이 있어야 합니다(API에서는 구조라고 함).

Home API는 OAuth 2.0을 사용하여 구조의 기기에 대한 액세스 권한을 부여합니다. OAuth를 사용하면 사용자가 로그인 사용자 인증 정보를 노출하지 않고도 앱 또는 서비스에 권한을 부여할 수 있습니다. Permissions API를 사용하면 사용자가 Google 계정을 사용하여 Home API 앱에 집에 있는 기기에 대한 액세스 권한을 부여할 수 있습니다.

Permissions API를 사용하려면 앱, Google Cloud, Google Home Developer Console에서 여러 단계를 거쳐야 합니다.

1. Google Cloud에서 OAuth 설정하기
   1. 앱 서명
   2. OAuth 동의 화면 설정
   3. 앱 등록 및 사용자 인증 정보 만들기
2. Permissions API 통합하기
   1. 권한 확인
   2. 권한 요청
3. 권한 부여
   1. 권한 변경
   2. 권한 취소

Google Cloud에서 OAuth 설정

이미 확인된 OAuth 클라이언트가 있는 경우 새 클라이언트를 설정하지 않고도 해당 클라이언트를 사용할 수 있습니다. 자세한 내용은 기존 OAuth 클라이언트가 있는 경우를 참고하세요.

앱 서명

1. Android Studio에서 앱을 실행하여 OAuth 키를 생성합니다. Android Studio에서 앱을 실행하거나 디버그하면 개발 및 디버깅을 위한 OAuth 키가 자동으로 생성됩니다. 자세한 설명은 Android 스튜디오: 디버그 빌드 서명을 참고하세요.

   휴대기기를 로컬 머신에 연결합니다. Android Studio에는 연결된 기기가 모델 번호별로 표시됩니다. 목록에서 기기를 선택한 다음 프로젝트 실행을 클릭합니다. 이렇게 하면 샘플 앱이 빌드되고 휴대기기에 설치됩니다.

   자세한 안내는 Android 개발자 사이트의 하드웨어 기기에서 앱 실행을 참고하세요.

   이제 실행 중인 앱을 중지합니다.

2. Google Cloud 콘솔 도움말 사이트의 OAuth 2.0 / 네이티브 애플리케이션/Android 설정에 자세히 설명된 안내에 따라 OAuth 인증서의 SHA-1 지문을 가져옵니다.

OAuth 동의 화면 설정

1. Google Cloud 콘솔에서 프로젝트 선택기 대시보드로 이동하여 OAuth 사용자 인증 정보를 만드는 데 사용할 프로젝트를 선택합니다.
2. API 및 서비스 페이지로 이동하여 탐색 메뉴에서 사용자 인증 정보를 클릭합니다.

3. 이 Google Cloud 프로젝트에 동의 화면을 아직 구성하지 않은 경우 동의 화면 구성 버튼이 표시됩니다. 이 경우 다음 절차에 따라 동의 화면을 구성합니다. 그렇지 않으면 다음 섹션으로 이동합니다.

   1. 동의 화면 구성을 클릭합니다. OAuth 동의 화면 페이지가 표시됩니다.
   2. 사용 사례에 따라 내부 또는 외부를 선택한 다음 만들기를 클릭합니다. OAuth 동의 화면 창이 표시됩니다.
   3. 화면에 표시된 안내에 따라 앱 정보 페이지에 정보를 입력한 다음 저장하고 계속하기를 클릭합니다. 범위 창이 표시됩니다.
   4. 범위를 추가할 필요가 없으므로 저장하고 계속하기를 클릭합니다. 테스트 사용자 창이 표시됩니다.
   5. 앱 액세스 권한을 테스트할 사용자를 추가하려면 사용자 추가를 클릭합니다. 사용자 추가 창이 표시됩니다. 테스트 사용자에게는 앱에서 권한을 부여할 권한이 있습니다.
   6. 빈 필드에 하나 이상의 Google 계정 이메일 주소를 추가한 다음 추가를 클릭합니다.
   7. 저장하고 계속하기를 클릭합니다. 요약 창이 표시됩니다.
   8. OAuth 동의 화면 정보를 검토한 다음 대시보드로 돌아가기를 클릭합니다.

자세한 내용은 Google Cloud 콘솔 도움말 사이트의 OAuth 동의 화면 설정을 참고하세요.

앱 등록 및 사용자 인증 정보 만들기

OAuth 2.0용 앱을 등록하고 OAuth 사용자 인증 정보를 만들려면 OAuth 2.0 설정에 제공된 안내를 따르세요. 앱 유형(네이티브/Android 앱)을 표시해야 합니다.

Google Cloud 콘솔 도움말 사이트의 OAuth 2.0 / 네이티브 애플리케이션 설정에 나온 안내에 따라 앱 서명에서 가져온 SHA-1 지문을 Google Cloud 콘솔에서 설정한 OAuth 클라이언트에 추가합니다.

휴대기기를 로컬 머신에 연결한 상태에서 목록에서 기기를 선택한 다음 프로젝트 실행을 다시 클릭하여 프로젝트를 실행합니다. 자세한 안내는 Android 개발자 사이트의 하드웨어 기기에서 앱 실행을 참고하세요.

Permissions API 통합

사용자가 지정된 구조 내의 기기에 액세스하려면 앱에 권한을 부여해야 합니다. 시작하려면 먼저 Home API를 초기화했는지 확인하세요. 이 단계의 homeManager 인스턴스는 여기의 모든 권한 예시에서 사용됩니다.

먼저 SDK에 ActivityResultCaller를 등록합니다. 예를 들어 샘플 앱은 다음과 같이 처리합니다.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

권한 확인

권한을 요청하기 전에 앱 사용자가 이미 동의했는지 확인하는 것이 좋습니다. 이렇게 하려면 Home 인스턴스의 hasPermissions() 메서드를 호출하여 PermissionsState 값의 Flow를 가져옵니다.

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

검사에서 NOT_GRANTED 또는 PERMISSIONS_STATE_UNAVAILABLE의 PermissionsState를 반환하면 권한을 요청해야 합니다. 검사에서 GRANTED의 PermissionsState를 반환했지만 후속 structures() 호출에서 구조체를 반환하지 않으면 사용자가 Google Home app (GHA) 설정 페이지를 통해 앱에 대한 액세스 권한을 취소한 것이므로 권한을 요청해야 합니다. 그러지 않으면 사용자에게 이미 액세스 권한이 있어야 합니다.

권한 요청

지정된 구조 내의 구조 및 기기에 액세스하려면 앱에 권한을 부여해야 합니다.

사용자가 아직 권한을 부여하지 않은 경우 Home 인스턴스의 requestPermissions() 메서드를 사용하여 권한 UI를 실행하고 결과를 처리합니다.

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

권한 UI가 제대로 실행되려면 앱에 이미 OAuth를 설정해야 합니다.

권한 부여

이제 앱을 실행하고 사용자가 권한을 부여할 수 있습니다. 권한을 부여할 수 있는 사용자 유형과 권한을 부여할 수 있는 기기 유형은 Developer Console에 앱을 등록했는지에 따라 다릅니다.

Home API를 사용하여 앱을 게시하려면 Developer Console 등록이 필요합니다. Home API를 테스트하고 사용할 필요는 없습니다. 콘솔 등록 기능에 액세스하려면 Google Technical Account Manager (TAM)에 문의하세요.

앱이 Developer Console에 등록되지 않은 경우 확인되지 않음 상태가 됩니다. Home API 사용을 테스트하는 경우 다음을 사용하는 것이 좋습니다.

• OAuth 콘솔에 테스트 사용자로 등록된 사용자만 앱에 권한을 부여할 수 있습니다. 확인되지 않은 앱의 경우 테스트 사용자는 100명으로 제한됩니다.

• 확인되지 않은 앱은 Home API용 OAuth에서 지원하는 모든 기기 유형 (Developer Console의 기기 유형 목록)의 기기에 액세스할 수 있습니다. 구조의 모든 기기에 권한이 부여됩니다.

앱이 Developer Console에 등록되어 있고 하나 이상의 기기 유형에 대한 액세스가 승인되었으며 OAuth에 대한 브랜드 인증이 완료된 경우 확인됨 상태가 됩니다. 프로덕션으로 앱을 출시하려면 이 상태가 필요합니다.

• 테스트 사용자 한도가 더 이상 적용되지 않습니다. 모든 사용자가 앱에 권한을 부여할 수 있습니다.
• 사용자는 Developer Console에서 승인된 기기 유형에만 권한을 부여할 수 있습니다.

이제 OAuth가 설정되었으므로 앱의 requestPermissions() 호출이 다음 대화상자를 트리거합니다.

1. 사용자에게 사용하려는 Google 계정을 선택하라는 메시지가 표시됩니다.
2. 앱에 액세스 권한을 부여할 구조를 선택하라는 메시지가 사용자에게 표시됩니다.
   1. 확인되지 않은 앱의 경우 Home API에서 지원하는 모든 기기 유형을 앱에서 사용할 수 있습니다.
   2. 인증된 앱의 경우 사용자는 Developer Console에서 승인된 기기 유형에만 권한을 부여할 수 있습니다.
   3. 앱이 관리 액세스 권한을 가진 민감한 기기 유형의 경우 사용자는 기기별로 액세스를 제한할 수 있습니다. 예를 들어 사용자에게 자물쇠가 3개 있는 경우 자물쇠 중 하나에 대해서만 액세스 권한을 부여할 수 있습니다.

권한이 부여되면 앱은 Home API를 사용하여 구조물의 기기 상태를 읽고 제어할 수 있습니다. 사용자가 특정 기기 유형 또는 민감한 기기에 대한 권한을 앱에 부여하지 않으면 앱에서 Home API를 사용하여 기기에 액세스, 제어 또는 자동화할 수 없습니다.

권한 변경

다른 구조의 기기에 액세스할 수 있는 권한을 부여하려면 계정 선택 도구를 실행하여 사용자가 전환할 Google 계정과 구조를 선택할 수 있도록 할 수 있습니다. 이 과정에서 이전에 동의한 경우에도 사용자에게 동의 화면이 다시 표시됩니다.

forceLaunch 플래그를 true로 설정하여 requestPermissions()를 다시 호출하면 됩니다.

homeManager.requestPermissions(forceLaunch=true)

권한 취소

사용자는 이전에 부여된 액세스 권한을 취소할 수 있습니다.

1. Google 내 계정 페이지 > 데이터 및 개인 정보 보호 > 서드 파티 앱 및 서비스를 통해 이렇게 하면 초기 동의가 부여될 때 발급된 OAuth 토큰이 취소되고 사용자가 모든 표시 경로(휴대전화)와 구조에서 사용 중인 앱 인스턴스에 대한 액세스가 취소됩니다.

2. GHA > 설정 > 연결된 앱 페이지를 통해 GHA에서 settings를 클릭하면 설정 페이지로 이동합니다. 여기에서 연결된 앱 카드를 클릭하면 동의 화면과 유사한 페이지로 이동합니다. 이 페이지에서 사용자는 앱에 대한 액세스 권한을 삭제할 수 있습니다. 사용자는 이 페이지에서 앱이 액세스할 수 있는 기기 유형 또는 특정 민감한 기기를 변경할 수 있습니다.

3. 웹에서 연결된 앱 페이지를 통해 직접

기존 OAuth 클라이언트가 있는 경우

게시된 앱에 대해 이미 확인된 OAuth 클라이언트가 있는 경우 기존 OAuth 클라이언트를 사용하여 Home API를 테스트할 수 있습니다.

Home API를 테스트하고 사용하기 위해 Developer Console 등록은 필요하지 않습니다. 하지만 다른 통합에서 확인된 OAuth 클라이언트가 있더라도 앱을 게시하려면 승인된 Developer Console 등록이 필요합니다.

다음 고려사항이 적용됩니다.

• 기존 OAuth 클라이언트를 사용하는 경우 사용자 한도가 100명입니다. 테스트 사용자를 추가하는 방법에 관한 자세한 내용은 OAuth 동의 화면 설정을 참고하세요. OAuth 인증과는 별도로 애플리케이션에 권한을 부여할 수 있는 사용자는 Home API에서 100명으로 제한합니다. 이 제한은 Developer Console 등록이 완료되면 해제됩니다.

• Home API로 앱을 업데이트하기 위해 OAuth를 통해 기기 유형 부여를 제한할 준비가 되면Developer Console 등록 을 승인받기 위해 전송해야 합니다.

아직 OAuth 인증이 대기 중인 Google Cloud 앱의 경우 인증이 완료될 때까지 사용자는 OAuth 흐름을 완료할 수 없습니다. 권한을 부여하려고 하면 다음 오류와 함께 실패합니다.

Access blocked: <Project Name> has not completed the Google verification process.

OkGoogle 권한

okGoogle 명령어는 구조 수준 명령어이며 구조의 모든 기기를 자동화하는 데 사용할 수 있습니다. 그러나 Home APIs 앱이 모든 기기에 액세스하지 못할 수도 있습니다. 다음 표에서는 이러한 경우에 권한이 적용되는 방식을 설명합니다.