App-managed automations for iOS

App-managed automations are automations that are constructed programmatically by a partner app using the Automation API.

Such automations are suppressed from appearing in the Google Home app (GHA) automations list.

The information written to the Home APIs activity feed when an app-managed automation is triggered can be customized, or suppressed entirely. For example, if a partner offers a branded service called "Arctic" that's implemented using app-managed automations, the partner could specify that when their app-managed automations run, the Arctic service is referenced in the activity feed instead of the actual automation name.

Create an app-managed automation

To create an app-managed automation, use the following procedure.

1. Build the automation's logic graph.

2. Optional If you want your automation's activity to appear in the activity feed, you can populate an AppManagedAutomationConfig instance with the localized message that you want to appear in the feed in place of the automation name. This can be the localized names of an app or service, or any other message you want. If you don't provide any localized strings, the automation executions are logged like those of any other automation. Google recommends you set these localized strings to ensure the best user experience.

   let automationConfig = AppManagedAutomationConfig(
       managingAppDisplayNames: [
         LocalizedText(text: "My Custom SmartApp", locale: "en-US"),
         LocalizedText(text: "Mi aplicación personalizada", locale: "es-MX")
       ]
   )
   

3. Create the automation instance using Automation.Builder.

   1. Set the name of the automation.
   2. Set the client_feature_group to either "APP_MANAGED_EXECUTION_REPORTED" if you want the automation's execution history appear in the Activity tab in GHA, or "APP_MANAGED_EXECUTION_UNREPORTED" if you don't want the automation's execution history to appear.
   3. Set the automationGraph.
   4. Optional Set the automation's appManagedAutomationConfig (see Step 2).

4. Finally, call build() to build the Automation instance.

This example shows the entire procedure:

import GoogleHomeSDK
import GoogleHomeTypes

let devices = try await home.devices().list()
let mySensor: HomeDevice = devices.first(where: {
    $0.types.contains(OccupancySensorDeviceType.self) &&
    $0.structureID == structure.id
})

let myLight: HomeDevice = devices.first(
  where: {
    $0.types.contains(OnOffLightDeviceType.self) &&
    $0.structureID == structure.id
  }
)

// 1. Create logic graph
let starterNode = StarterNode(
    device: mySensor,
    trait: Matter.OccupancySensingTrait.self
)

let actionNode = ActionNode(
    device: myLight,
    command: Matter.OnOffTrait.on()
)

// Bundle nodes into a sequential graph
let automationGraph = SequentialFlow(
    nodes: [starterNode, actionNode]
)

// 2. Build the AppManagedAutomationConfig with the localized app names
let automationConfig = AppManagedAutomationConfig(
    managingAppDisplayNames: [
      LocalizedText(text: "My Custom SmartApp", locale: "en-US"),
      LocalizedText(text: "Mi aplicación personalizada", locale: "es-MX")
    ]
)

// 3. Build the Automation with both configuration and the graph
let myFunctionalAutomation = try AutomationBuilder()
    .setName("Motion Activated Light")                         // a. Set the name
    .setClientFeatureGroup("APP_MANAGED_EXECUTION_UNREPORTED") // b. set the clientFeatureGroup
    .setAutomationGraph(automationGraph)                       // c. Attach the logic graph
    .setAppManagedAutomationConfig(automationConfig)           // d. Set the automationConfig
    .build() // 4. build the automation