Esta página foi traduzida pela API Cloud Translation.

Solução de problemas

App de exemplo

Se você tiver problemas ao usar as APIs Home, colete registros para depuração adicional. Para coletar registros do dispositivo móvel, é necessário o Android Debug Bridge (adb). Se você precisar de ajuda do Google, colete os registros dos dispositivos Android e do hub e abra um tíquete no rastreador de problemas com as informações e os registros relevantes associados a ele.

Coletar registros do Android

Seu dispositivo móvel deve estar conectado ao seu computador local para todas as etapas envolvendo adb.

Instale o adb

Caso ainda não o tenha feito, configure o Android Debug Bridge em sua máquina local:

Instale o "adb" no seu computador.
Ative as Opções do desenvolvedor e a Depuração USB no seu telefone Android.

Plug-in do Google Home para o Android Studio

O Google Home Plugin for Android Studio é uma ferramenta útil para coletar e analisar logs e foi criado especificamente para desenvolvedores do Google Home platform. Esse plug-in dá acesso ao Google Assistant Simulator, ao Cloud Logging e a outras ferramentas para simplificar o processo de desenvolvimento do smart home.

Use essa ferramenta com adb para analisar ainda mais os registros de dispositivos Matter.

Para saber mais e obter a ferramenta, consulteGoogle Home Plugin for Android Studio.

Informações da versão

Recomendamos que você reúna todas as informações de versão relacionadas à sua configuração sempre que decidir coletar registros. Isso é necessário caso precise compartilhar problemas com o Google.

Obtenha o ID do seu dispositivo móvel:

adb devices

List of devices attached
device-id    device

Armazene esse valor em uma variável chamada phoneid:
```
phoneid=device-id
```

Salve várias informações do dispositivo em variáveis:

containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true);
homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true);
optionalhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true);
policyhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true);
threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true);
ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true);
enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true);
androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true);
androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true)

Salve todas as variáveis em um arquivo chamado _versions.txt:

Expanda para exibir os comandos para salvar variáveis em um arquivo.

Todo o bloco pode ser copiado e colado em um terminal de uma só vez.

versionfile=$logtimestamp"_versions.txt"
echo "Saving version info to $versionfile"

echo "Container version:" >> $versionfile
echo $containerinfo >> $versionfile
echo "" >> $versionfile

echo "Home Module version:" >> $versionfile
echo $homemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Optional Home Module version:" >> $versionfile
echo $optionalhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Policy Home Module version:" >> $versionfile
echo $policyhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Thread Module version:" >> $versionfile
echo $threadinfo >> $versionfile
echo "" >> $versionfile

echo "GHA version:" >> $versionfile
echo $ghainfo >> $versionfile
echo "" >> $versionfile

echo "Android version: " >> $versionfile
echo $androidversion >> $versionfile
echo "" >> $versionfile

echo "Android API version: " >> $versionfile
echo $androidapiversion >> $versionfile
echo "" >> $versionfile

echo "Found enabled features (blank if missing):" >> $versionfile
echo $enabledfeatures >> $versionfile
echo "" >> $versionfile

Verifique o conteúdo de _versions.txt:

cat _versions.txt

Expanda para exibir um exemplo de saída do arquivo.

Container version:
versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)

Home Module version:
com.google.android.gms.home [v230508900]

Optional Home Module version:


Policy Home Module version:
com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]

Thread Module version:
com.google.android.gms.threadnetwork [v231912000]

GHA version:
versionName=3.2.32.1

Android version:
13

Android API version:
33

Found enabled features (blank if missing):

Esse arquivo pode ser fornecido ao Google conforme necessário para a solução de problemas.

Coletar registros

Para coletar registros, feche todos os aplicativos que estão em execução no dispositivo móvel. Em seguida:

Abra uma janela de terminal e limpe os registros de dispositivos existentes:
```
adb logcat -b all -c
```
Inicie o processo de coleta de logs:
```
adb logcat >> _logs.txt
```
Mantenha esse terminal aberto. Isso coletará registros do seu dispositivo enquanto o processo estiver em execução.
Execute o app de exemplo e capture todas as ações da interface do usuário. Quando terminar, pressione Ctrl+C (ou Cmd+C no Mac) para interromper o processo logcat em execução no terminal.
Os registros desta sessão são salvos em um arquivo chamado _logs.txt.

Você pode analisar as informações deste arquivo de várias maneiras, incluindo a busca por palavras-chave como error, exception ou crash.

Scripts de registro

Para sua conveniência, o aplicativo de exemplo fornece scripts para obter os registros relevantes e os compila em um arquivo de texto. Para proporcionar a melhor experiência de depuração, esses registros devem ser anexados a quaisquer bugs relatados para facilitar a análise da causa raiz pelo Google.

Esses registros estão localizados no diretório scripts na árvore de origem do app de exemplo. Execute os seguintes passos a partir do diretório raiz do projeto:

Obtenha o ID do seu dispositivo móvel:

adb devices -l

List of devices attached
device-id device

Execute o script get_logs.sh:

 ./scripts/get_logs.sh device-id

Cleared previous logs from device.
Saving version information to home_api_sample_logs_20240605233243.txt...
Saving logs to home_api_sample_logs_20240605233243.txt...
(Press CTRL+C to stop the script)

Reproduza o problema.
Pressione CTRL+C para interromper o script.

O script vai gerar um arquivo de registro com carimbo de data/hora que contém todas as informações relevantes. Anexe esses arquivos aos relatórios de bugs que você encontrar.

Registros do dispositivo hub do Cast

Você pode visualizar os registros do seu hub Google Nest usando este método, que é compatível com os seguintes modelos:

Google Home
Google Nest Audio
Google Nest Hub
Google Nest Mini

Para habilitar um hub Cast para recuperação de logs locais:

Configure o Android Debug Bridge.
Consiga o endereço IP do hub:
- A partir do hub, se houver uma tela:
  1. Deslize de cima para baixo na tela.
  2. Toque no ícone Configurações
  3. Encontre o endereço IP do dispositivo: Em um Nest Hub (2nd gen), acesse Informações do dispositivo > Informações técnicas > Endereço IP
- De GHA no seu telefone:
  1. Toque no dispositivo para abrir a página de detalhes do dispositivo.
  2. Toque no ícone Configurações para abrir a página de configurações.
  3. Encontre o endereço IP do dispositivo: acesse Informações do dispositivo > Informações técnicas > Endereço IP
Em um computador conectado à mesma rede Wi-Fi que o dispositivo:
```
  adb connect ip-address
  adb logcat
```
Para fornecer registros a alguém, execute a operação com falha e envie a saída para um arquivo de texto:
```
  adb logcat -d > platform-logs.txt
```

Automações

Detecção de bordas

Automações no ecossistema do Google Homedetecção de bordas, que é uma lógica que verifica se um iniciador só é ativado quando há uma mudança real de estado, em oposição a uma atualização de estado que simplesmente repete o estado anterior do dispositivo.

Por exemplo, se acender uma lâmpada for um evento iniciador, a detecção de borda verifica se o evento só é ativado se o dispositivo de iluminação passar de desligado para ligado, e não de ligado para ligado (sem alteração).

A automação não está se comportando como esperado.

Depois de considerar a detecção de bordas, se uma automação não se comportar como esperado:

Verifique cada dispositivo para garantir que esteja funcionando corretamente, independentemente da sua automação.
Confira o gráfico de automação e compare com a DSL para revelar possíveis suposições incorretas da sua parte.
Observe o estado do dispositivo no aplicativo Google Home durante a execução da sua automação.
Verifique se todos os dispositivos referenciados pela automação estão presentes na estrutura onde você espera encontrá-los. A exclusão de um dispositivo do qual uma automação depende pode ter consequências indesejadas. Consulte Impacto da exclusão do dispositivo nas automações.

A automação é executada quando não deveria.

Se a automação for executada quando não deveria, examine os critérios de ativação. Pode ser necessário adicionar lógica adicional para garantir que uma mudança de estado seja capturada apenas uma vez e acione a automação apenas uma vez.

A automação não compila

Certifique-se de que seu aplicativo contenha todas as importações necessárias, incluindo cada classe correspondente aos diferentes tipos de nós, bem como as características às quais você está fazendo referência.

A criação da automação falha na validação.

Se a criação da automação não passar na validação, uma mensagem de aviso ou erro vai fornecer informações sobre o problema. Para mais informações, consulte a referência de ValidationIssueType.

A função List lança exceções.

Ao chamar a função "List" da API Automation, os manipuladores de leitura podem gerar exceções devido à falta de recursos da API. Para mitigar esse problema, exclua a automação afetada.

Para fazer isto:

Verifique se o adb instalado está instalado. Veja Instalar adb.

Recupere o ID da automação nos registros do Android invocando:

adb logcat -s GhpNative

Exemplos de registros:

adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse

INTERACTION RESPONSE -> SendCommandsResponse:
1 {
1: "automation@global"
3 {
  1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
  2:
  5 {
    1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
    1 {
        1: "1111-2222-3333-44444-55555" // Automation ID to delete
        2: "structure@2222-3333-4444-5555-6666"
...

Se for necessário excluir vários IDs de automação, você pode usar o pager do terminal para controlar a saída:

adb logcat -s GhpNative level:debug | less

Exclua a automação usando o ID dela:

structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

A API Discovery registra um aviso quando um traço é cancelado.

Se a API Discovery registrar um aviso para Trait not found, isso significa que a API está tentando usar a característica para candidatos da API Discovery, mas não vai conseguir porque a característica não foi registrada durante a inicialização. Exemplo:

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

O identificador de traço é home.matter.6006.clusters.fc43, que corresponde a RelativeHumidityControl. Para determinar o nome de um traço com base em um ID, consulte o Índice de traços.

Neste exemplo, RelativeHumidityControl precisa ser registrado durante a inicialização do app. Consulte Registrando características para adicionar sua característica ao registro.

OAuth

Se você já possui um cliente OAuth

Se você já tiver um cliente OAuth verificado para um app publicado, use esse cliente para testar as APIs Home.

Não é necessário registrar o Google Home Developer Console para testar e usar as APIs Home. No entanto, você ainda vai precisar de um registro de Developer Console aprovado para publicar seu app, mesmo que tenha um cliente OAuth verificado de outra integração.

As seguintes considerações se aplicam:

Há um limite de 100 usuários ao usar um cliente OAuth atual. Para informações sobre como adicionar usuários de teste, consulte Configure a tela de consentimento do OAuth. . Independente da verificação do OAuth, há um limite imposto pelas APIs Home de 100 usuários que podem conceder permissões ao seu aplicativo. Essa limitação é removida após a conclusão do registro do Developer Console.
ODeveloper Console registro deve ser enviado para aprovação quando você estiver pronto para restringir as concessões de tipo de dispositivo pelo OAuth em preparação para atualizar seu app com as APIs Home.

Importante: O Console do Desenvolvedor do Google Home ainda não está disponível para registro.

Para apps Google Cloud que ainda estão pendentes de verificação do OAuth, os usuários não podem concluir o fluxo do OAuth até que a verificação seja concluída. As tentativas de conceder permissões vão falhar com o seguinte erro:

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