Visão geral da API Automation no Android

As automações são uma maneira de automatizar tarefas e configurações de dispositivos em uma casa. Elas estão disponíveis no ecossistema do Google Home como Rotinas no Google Home app (GHA) e pelo automation script editor no Google Home for web.

Agora, as automações no ecossistema do Google Home estão disponíveis nas APIs Home para Android. Elas usam os mesmos conceitos básicos usados em GHA Rotinas e o script editor, mas com recursos e funcionalidades aprimorados que só são possíveis pelas APIs Home, incluindo:

• Acesso a todos os recursos Matter padrão e smart home para um dispositivo, conforme apresentado nas APIs Home.
• Suporte a fluxos de execução sequenciais, paralelos e selecionados.

As automações são escritas usando a DSL de automação, uma linguagem específica de domínio projetada para criar automações em Kotlin.

Todos os recursos e tipos que você pretende usar no app com as APIs Device &Structure ou Automation precisam ser registrados na inicialização. Consulte Inicializar a casa no Android.

Orientação se o usuário revogar as permissões totais

Se o usuário revogar as permissões totais, todas as automações atuais vão parar de funcionar. Além disso, se o usuário revogar o acesso a dispositivos específicos, os acionadores, as condições e as ações associadas a esses dispositivos vão parar de funcionar.

Sempre que o app for iniciado, verifique se as permissões ainda estão em vigor. Se elas tiverem sido revogadas, remova todos os dados anteriores, incluindo os dados armazenados em cache no aplicativo.

Quando o acesso à estrutura é revogado, a StructureAccessRevokedEvent é entregue ao back-end da nuvem. Consulte Concessões de estrutura para o fluxo de trabalho de revogação de apps para dispositivos móveis e nuvem de parceiros de ponta a ponta.

Jornada do desenvolvedor

A API Automation é uma parte de uma jornada de desenvolvimento maior. Ela vem depois da integração das APIs Structure e Device para garantir que, quando um usuário quiser usar uma automação, ele possa fazer isso.

1. O desenvolvedor planeja a automação e a define usando a DSL de automação.
2. O desenvolvedor incorpora a definição de automação em um app Android Kotlin.
3. O app apresenta automações a um usuário com base em informações sobre os dispositivos dele, incluindo recursos, atributos, comandos e eventos, coletados usando a API Discovery ou a API Device.
   1. Com a API Discovery, o app pode gerar uma automação de rascunho personalizada para os tipos de dispositivos e recursos presentes na estrutura do usuário, com ou sem a entrada do usuário.
   2. A API Device pode fornecer a maioria das mesmas informações que a API Discovery, mas não é otimizada para casos de uso de automação. Consulte Comparar a API Device e a API Discovery para mais detalhes.
4. O app cria a automação real que é associada à estrutura selecionada.
5. A automação agora está disponível na estrutura do usuário e pode ser executada ou excluída usando métodos da API Structure.

O usuário pode criar novas instâncias da automação a qualquer momento, selecionando uma estrutura diferente ou, dependendo da lógica do app, talvez um conjunto diferente de dispositivos. Cada vez que isso acontece, o app gera uma nova instância da automação.

No cenário mais básico, você pode sugerir aos usuários uma automação predefinida que executa uma tarefa relativamente básica. Como alternativa, você pode apresentar um esqueleto de uma automação que o usuário personaliza para atender às necessidades dele. Ou você pode escrever um editor de automação aberto que permite ao usuário criar automações complexas usando todos os blocos de construção disponíveis na API Automation.

Sugestões de automação

As APIs Home podem sugerir automações para um Structure com base em fatores como os tipos de dispositivos presentes no espaço.

As sugestões de automação são representadas pela AutomationSuggestion classe.

A interface Structure abrange a HasSuggestions interface, que fornece a suggestions() função, que retorna uma coleção de sugestões de automação.

Os likeSuggestion() e dislikeSuggestion() métodos são destinados a controles de interface thumb_up e thumb_down que o usuário pode tocar para fornecer feedback.

Um terceiro método, clearSuggestionFeedback(), permite que o usuário remova o feedback de uma automação sugerida.

O feedback do usuário influencia as sugestões futuras.

Este exemplo demonstra como recuperar as sugestões de automação disponíveis para um Structure, extrair um ID de sugestão e registrar o feedback do usuário usando likeSuggestion(), clearSuggestionFeedback(), e dislikeSuggestion().

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.home.Structure
import kotlinx.coroutines.launch

class AutomationSuggestionsViewModel(private val structure: Structure) : ViewModel() {

  fun loadAndGiveFeedback() {
    viewModelScope.launch {
      // 1. Fetch suggestions from structure
      val suggestions = structure.suggestions()
      val firstSuggestion = suggestions.firstOrNull() ?: return@launch

      // Extract string suggestion ID
      val suggestionId: String = firstSuggestion.id.id

      // 2. Like the suggestion (thumbs up)
      val liked = structure.likeSuggestion(suggestionId)

      // 3. Clear previous feedback if the user toggled it off
      if (liked) {
        structure.clearSuggestionFeedback(suggestionId)
      }

      // 4. Dislike the suggestion (thumbs down)
      structure.dislikeSuggestion(suggestionId)
    }
  }
}

Parâmetros de comando dinâmicos

Os parâmetros de comando dinâmicos permitem que os desenvolvedores criem parâmetros de ação que são resolvidos dinamicamente no momento da execução, em vez de depender estritamente de valores estáticos e constantes. Isso permite dois recursos principais:

• Referências que transmitem o valor de uma propriedade de um acionador (como um payload de evento) ou um nó de leitor de estado ou de variáveis locais declaradas no fluxo de automação.
• Expressões que capturam valores dinâmicos de execução (como uma propriedade de evento ou um valor de estado) e transmitem o valor dinâmico diretamente para um parâmetro de comando.

Caso de uso

Vincule um interruptor rotativo físico que envia um evento de vários toques a uma luz regulável. A contagem de cliques é o valor dinâmico transmitido para um comando de etapa LevelControl no momento da execução.

Como os parâmetros dinâmicos funcionam

Na DSL de automação no Android, os parâmetros de comando aceitam Expression ou Reference instâncias diretamente no lugar de valores constantes estáticos. A DSL os encapsula em Parameter definições ao criar a automação.

Regras de validação

Os parâmetros de comando dinâmicos seguem estas restrições de validação:

• Os parâmetros dinâmicos são considerados estruturalmente válidos durante a descoberta porque as APIs Discovery só avaliam restrições de valor concretas para argumentos estáticos.
• Os nós de referência ou expressão precisam aparecer a montante no gráfico de automação antes de serem referenciados em uma ação de comando a jusante.

Usar parâmetros de comando dinâmicos no Android

Transmita expressões dinâmicas diretamente para parâmetros de comando:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val keypressAutomation = automation {
  name = "Dynamic command parameters example"
  description = "Pass starter event field directly to command"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountExpr,
        )
      )
    }
  }
}

Como alternativa, atribua uma expressão a uma declaração de variável local e faça referência à variável mais tarde no fluxo:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.automation.variable
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val myAutomationWithVariable = automation {
  name = "Dynamic command parameters with variables"
  description = "Declare a variable, assign value, and pass reference"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    val clickCountVar = variable<UInt>()
    clickCountVar.assign(clickCountExpr)

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountVar,
        )
      )
    }
  }
}

Restrições de tipo

Verifique se os tipos de variáveis e expressões estão alinhados com a definição de tipo de esquema exigida pelo parâmetro de comando de recebimentoMatter (como UShort, UByte ou UInt8).

Limites de recurso

Os limites a seguir se aplicam a automações nas APIs Home: