스마트 홈 FAQ

일반

Q: Actions on Google 처리 인프라를 어디에 어떤 언어로 구현해야 하나요?

A: 최신 SSL (TLS) 및 OAuth 2.0을 지원하기만 하면 원하는 플랫폼과 언어로 인프라를 구현할 수 있습니다. 안정성을 개선하고 실제 사용자 기기에 대한 실행 지연 시간을 줄이기 위해 인프라의 나머지 부분에 최대한 가깝게 배포하는 것이 좋습니다.

Q: 기기 ID는 고유해야 하나요?

A: ID는 고유해야 합니다. 서비스 전반에 고유 ID가 없는 경우 ID는 적어도 사용자별로 고유해야 합니다. 집이 여러 개 있고 두 집이 모두 동일한 사용자로 통합되는 사용자를 상상해 보세요. 한 집에서 조명을 켜 달라고 요청해도 ID가 같은 조명이 다른 집에 켜지면 안 됩니다.

Q: 기기 이름은 고유해야 하나요?

A: 이름은 고유해야 할 필요는 없지만, 시간이 지남에 따라 더 나은 사용자 환경을 위해 설정 후 잘못된 이름을 개선하는 것이 좋습니다.

다음은 간단한 이름 지정 가이드입니다.

  • 이름은 사람들이 실제로 말할 수 있는 것이어야 합니다.
  • Google에서는 문자열의 하위 집합을 인식하므로 'acme 색상 조명'이 있는 경우 'acme 조명'에도 응답합니다.
  • 제품을 설명하는 이름과 사용자가 정의한 하나 이상의 이름을 모두 사용하는 것이 좋습니다.
  • 조명에 방 이름을 지정할 필요가 없기 때문에 사용자가 조명에 방 이름을 지정할 필요가 없습니다. 방마다 고유한 이름이 있어야 하지만 항상 복수형을 사용하여 모든 것을 명령할 수 있습니다. 예를 들어 사무실 벽면의 전구 두 개는 '북쪽 조명'과 '동쪽 조명'이지만 '조명'으로만 명령할 수 있습니다.

Q: 기기 상태는 얼마나 자주 업데이트되나요?

A: 임시 상태는 사용자가 시작한 작업인 QUERY 또는 EXECUTE에 따라 검색됩니다. 사용자가 '표시등이 켜져 있나요?'라고 묻거나 조명을 밝히고 싶다면 쿼리를 실행하여 현재 상태를 파악해야 합니다.

Q: 기기의 현재 상태로 Home Graph를 직접 업데이트할 수 있나요?

A: 예, Report State API 호출을 사용합니다.

계정 연결 및 OAuth

A: 예. 사용자의 기기를 제공업체의 클라우드 서비스에 연결하려면 계정 연결이 필요합니다.

Q: OAuth의 경우 15.213시간마다 액세스 토큰이 만료되나요?

A: 예, 하지만 테스트 기간이 상당히 짧은 편(10~20분)으로 테스트하세요. OAuth 클라이언트는 필요에 따라 토큰을 새로고침해야 하며, 만료 시간을 짧게 테스트하면 제대로 작동하는 것을 확인할 수 있습니다.

인텐트

Q: 동기화는 언제 실행되나요?

A: OAuth가 완료된 직후와 동기화 요청이 호출된 직후에 SYNC가 발생합니다.

Q: SYNC가 작동하지 않는 이유는 무엇인가요?

A: 이 작업이 실패하는 데는 여러 가지 일반적인 이유가 있습니다.

  • 잘못된 기기 유형을 전송하고 있습니다.

    • 예를 들어 action.devices.types.LIGHT가 예상되지만 action.devices.types.Light를 전송합니다.

  • 지원되지 않는 기기 유형을 전송하려고 합니다.

    • 예를 들어 action.devices.types.FLASHLIGHT를 전송합니다. 이는 Google에서 지원하지 않습니다.

  • 잘못되었거나 지원되지 않는 필드를 전송 중입니다.

    • 예를 들어 버전 필드 또는 사양에 없는 다른 필드가 있습니다.

  • SYNC 응답에 다른 형식 문제가 있습니다.

    • 대괄호를 확인하세요.

  • 계정 연결 문제가 발생했습니다.

    • SYNC 요청의 인증 헤더에 유효한 액세스 토큰이 수신되었는지 확인하세요.

  • SYNC 요청에 응답하는 데 너무 오래 걸립니다.

    • 5초 이내에 SYNC 요청에 응답하는지 확인하세요.

Q: '대기 중'으로 응답해도 괜찮나요?

A: 기기를 실시간으로 사용할 수 있는 경우 대기 중이 아닌 성공/실패 응답을 사용하는 것이 좋습니다. '대기 중' 응답이 필요한 경우 Google에 문의해 주세요. 일부 저전력 비실시간 기기에서는 대기 중인 응답 및 비동기 실행 모델이 필요할 수 있습니다.

테스트 및 제출

Q: 스테이징 환경을 설정할 수 있나요?

A: 예. 별도의 프로젝트를 만든 후 해당 프로젝트의 설정을 실행하세요. 개발 프로세스 및 인프라에 매핑하기 위해 필요한 만큼의 프로젝트를 만들 수 있습니다.

Q: 프로젝트 초안을 얼마나 자주 업데이트해야 하나요?

A: 프로젝트 초안은 3일마다 새로고침되어야 합니다. 3일이 지나면 테스트 에이전트가 모바일 HomeControl 설정에서 사라집니다. 이 경우 Actions on Google Console에서 프로젝트의 테스트 초안 버튼을 클릭합니다.

Q: 한 번에 2개 이상의 기기에서 테스트할 수 있나요?

A: Actions on Google는 '기기에서 시도' AP를 한 번에 하나만 지원합니다. 먼저 'ap1' 및 동기화 기기에서 테스트 초안을 사용한 다음 ap1 연결을 해제하지 않고 TEST DRAFT 'ap2'를 직접 실행하면 'ap1'이 mobile-HomeControl-settings에서 사라집니다. 이 문제를 해결하려면 'ap1'에서 테스트 초안을 다시 실행하고 설정에서 'ap1'을 연결 해제할 수 있습니다.

이 단일 작업 패키지는 사용자의 모든 Google Assistant 기기에서 사용할 수 있습니다. 예를 들어 음성인식 스피커와 Android 모두에서 새 하드웨어 통합을 테스트할 수 있습니다.

Q: 작업 프로젝트 제출이 이름이나 발음으로 인해 거부되었습니다. 무엇을 변경해야 하나요?

A: 이름 발음을 확인하여 향후 다른 작업에서 이 발음 이름을 사용하지 않으며 표시 이름과 일치하는지 확인합니다. 이는 향후 이름 등록에 영향을 미치는 불일치를 방지하기 위해서입니다.

같은 이름을 계속 사용하려면 지원팀에 문의하여 음성팀에서 표시 이름을 Assistant에 추가해 달라고 요청하세요.

Q: Google Home 앱의 홈 컨트롤 섹션에 내 작업이 표시되지 않습니다. 어떻게 된 건가요?

A: 다음 중 한 가지 문제일 수 있습니다.

  • Actions Console에서 프로젝트의 초안 테스트 버튼을 클릭하지 않았습니다.
  • '기기 테스트'에서는 한 번에 하나의 작업만 사용할 수 있습니다.
  • Actions Console에서 작업 프로젝트의 시뮬레이터 탭으로 이동하여 활성/비활성 전환을 비활성으로 전환했다가 다시 활성으로 전환합니다.
  • 나와 공유된 작업인 경우 모든 공유 안내를 따랐는지 확인하세요.
  • 기기 테스트는 3일 후에 만료됩니다. Actions Console에서 프로젝트의 테스트 초안 버튼을 클릭합니다.

Q: 시뮬레이터에서 'talk to <my agent name>'를 입력하면 오류가 발생하는 이유는 무엇인가요?

A: 스마트 홈 작업은 호출 이름을 사용하지 않습니다. 시뮬레이터에서 테스트하려면 Google Home app (GHA)가 설치된 Android 또는 iOS 휴대전화에서 계정 연결을 통해 실행해야 합니다. 계정 연결을 실행하기 전에 계정과 연결된 기기도 있어야 합니다.

Q: 시뮬레이터를 사용하려고 할 때 오류가 발생하는 이유는 무엇인가요?

A: 시뮬레이터를 사용하여 배포된 smart home 작업을 테스트할 수 없습니다. 프로덕션에 있는 홈 자동화 프로젝트에 시뮬레이터를 사용하려면 테스트 목적으로 새 프로젝트를 만들어야 합니다.

보고서 상태

Q: 보고서 상태를 구현하기 위한 전제 조건이 있나요?

A: 프로젝트는 Smart Home API를 사용하고 OAuth2를 지원해야 하며 보고할 상태가 있는 특성이 있어야 합니다.

Q: 기기에서 상태를 얼마나 자주 보고해야 하나요?

A: Google은 전환 및 최종 상태에 관심이 있지만 단기간에 상태 변경이 여러 개인 경우 (예: 사용자가 1분에 냉장고를 3번 열고 닫거나 조광기로 슬라이드) 보고되는 최종 상태만 필요합니다.

Q: Report State를 호출할 때 전체 기기 상태를 전송해야 하나요?

A: 부분 상태 업데이트는 지원되지 않으므로 Report State 호출에는 항상 업데이트된 특정 특성의 모든 데이터가 포함되어야 합니다. 두 특성으로 인해 불일치가 발생할 경우 함께 다시 보고해야 합니다.

Q: Google에서 내 기기를 쿼리하여 상태 (즉, 기기 폴링)를 가져올 수 있나요?

A: 이는 권장되지 않는 대체 메커니즘입니다. 이러한 사용자를 위해 기기를 자주 폴링해야 하는 경우 추가 부하가 얼마인지 보장할 수 없습니다. 새로운 시각적 표면이 필요합니다. 또한 알려지지 않은 로드 문제 외에도 사용자 환경이 저하됩니다. Google에서는 Report State가 플랫폼에 매우 중요하다고 생각합니다.

Q: 현재 보고서 상태를 지원하는 특성은 무엇인가요?

A: 상태가 연결된 모든 공개 특성이 지원됩니다. 기기의 온라인 상태 변경사항도 보고해야 합니다.

장면에는 상태가 없습니다. 하지만 기기 상태가 변경될 수도 있습니다. Google Home Graph에 있는 기기 중 하나에 변경 상태가 있는 경우 이를 다시 보고해야 합니다.

Q: 보고서 상태에서 타임스탬프를 전송해야 하나요?

A: 타임스탬프는 필요하지 않습니다. 마지막으로 전송된 상태가 이전 호출을 재정의합니다.

Q: 쿼리 또는 실행에서 이미 상태를 전송하고 있는 경우 상태를 별도로 보고해야 하나요?

A: Home Graph는 Report State를 통해 전송된 상태만 저장합니다. EXECUTE 및 QUERY 인텐트에 대한 응답으로 반환되는 상태는 사용자에게 보내는 음성 응답에만 사용되며 저장되지 않습니다. 따라서 기기의 새 상태가 EXECUTE 또는 QUERY 인텐트에 대한 응답으로 이미 반환된 경우에도 Report State가 호출되어야 합니다.

Q: 지정된 기한 내에 보고서 상태를 완전히 구현하지 않으면 어떤 결과가 발생하나요?

A: 이로 인해 GHA 및 시각적 표시 경로와 같은 사용자 환경이 저하됩니다. 이는 상태 폴링을 위해 많은 QUERY 인텐트가 전송된다는 의미이며, 파트너 클라우드의 추가 부하에 상응하는 것을 보장할 수 없습니다.

Q: 보고서 상태 구현을 테스트하려면 어떻게 해야 하나요?

A: Home Graph에 저장된 현재 기기 상태를 보여주는 셀프 서비스 테스트 도구인 Home Graph Viewer를 사용합니다.

Q: 보고서 상태에 임의 requestId를 사용할 수 있나요?

A: EXECUTE 요청에 의해 Report State가 트리거되는 경우 파트너는 EXECUTE 요청에서 수신한 동일한 requestId를 사용하는 것이 좋습니다. 그렇지 않으면 임의의 requestId를 사용할 수 있습니다.

Q: 사용자가 여러 기기를 보유하고 있고 그 중 하나의 상태가 변경되면 모든 기기의 최신 상태를 보고해야 하나요?

A: 아니요. 특정 기기의 상태만 보고하면 됩니다.

권장사항

Q: 어떤 종류의 지연 시간이 허용되나요?

A: 200ms 미만이 이상적이며 2~5초 사이가 좋습니다. 지연 시간이 5초 정도 지속된다면 Google에 문의하세요.

Q: 음성인식 스피커가 오프라인일 때 제대로 응답하도록 하려면 어떻게 해야 하나요?

A: 오프라인 기기의 오프라인 상태를 반환합니다. 이 오류에는 '현재 사용할 수 없음'이 TTS로 반환됩니다. 자세한 내용은 오류 및 예외를 참조하세요.