Home APIs Tips & Tricks

Key Concepts

• Home APIs documentation (Android & iOS)
• Device API (Device Types & Traits)
• Google Home Playground (Virtual Devices)
• Automation API
• Trait Support & Blocked Actions
• Assistant Fulfillment Trait (OK, Google command)
• Case Studies Hub
• Smart Home Developer Forum
• Stack Overflow
• Issue Tracker

Home APIs Documentation

• The Google Home Developer Center hosts the Home APIs documentation.
• Access via QR code or navigating to Docs > Home APIs.
• Android and iOS documentation are separate and do not overlap. Switch between them using the tab drop-down, left navigation, or Get Started page.
• The Develop tab contains the full end-to-end process and all API guides.
• The Reference tab contains the API reference.
• The Support tab provides support resources.

Device API

• The Home APIs data model is based on the Matter protocol and Google Homes Cloud-to-Cloud smart home integrations.
• Extensive device capabilities: 90 device types and over 120 traits.
• Full list of supported device types is in the Home API section of the Developer Center under API Guides > Device API > Supported Device Types.
• Traits are listed in the reference, grouped by Google or Matter.

Google Home Playground

• A tool to create virtual devices for exploring device types and capabilities.
• Devices created in the Playground can be accessed in the Google Home app and through the Home APIs.
• To use:
  1. Set up a home in the Google Home app.
  2. Link Google Home Playground in the Works With Google Services tab.
  3. Sign in to the Playground web app with the same account as the Google Home app.
  4. Click Add Device, select the device type, and give it a name.
  5. Edit Device Traits to add more capabilities.
• Playground devices are Cloud-to-Cloud based, so traits are translated between the Playground and Home APIs data models.

Testing Device Types and Traits

• For device types not covered in samples, adapt code from sample apps by swapping out device type or trait identifiers.
• Use the reference to find new attributes and commands for the updated trait.
• Autocomplete in Android Studio or Xcode suggests valid properties or methods.

Device Functionality

• Not all devices of the same device type are rendered the same way in the Home APIs.
• Device appearance depends on the features implemented by the device manufacturer.
• Apps should not assume that all devices of the same device type support the same functionality.
• Best practice: Check what functionality is supported by a device using supports functions at the trait level.
  • Android: Two supports functions, one for attributes and one for commands.
  • iOS: Each individual command has its own supports function. For attributes, use the isSupported method in each traits property wrapper.
• Tailor app logic based on supported functionality and handle situations where devices have different capabilities.

Automation API

• Diagram the automation logic on paper before coding.
• Implement the automation using the Google Home app or the Script Editor in Google Home for Web (home.google.com) before using the Home APIs.
• The Script Editor uses YAML format and allows immediate testing.

Restrictions

• Not all device capabilities are available for use in an automation for safety and security reasons.
• Blocked actions are listed on the blocked actions page (QR code provided).
• Check the Trait Support page (QR code provided) to ensure the desired action is available.
• The Discovery API handles these restrictions automatically.

Assistant Fulfillment Trait

• Use the OK, Google command of the Assistant Fulfillment trait to trigger actions not directly available in automations.
• Send a natural language query to the APIs, equivalent to speaking to Google Assistant.
• Example: Use the OK, Google command to send a query of "play rain sound" to Nest hubs when a light is turned on.

Automation Examples

• A catalog of automation examples is available on the Developer Center (example automations page, QR codes provided for Android and iOS versions).

Inspiration and Support

• Case Studies Hub: Accessible through Resources > Business Resources on the Developer Center. Read how other developers have used the Home APIs.
• Smart Home Developer Forum: The primary avenue for help. The Google Home Team actively monitors the forum.
• Stack Overflow: Other Home APIs developers may have encountered the same problems.
• Issue Tracker: File bugs encountered when working with the Home APIs. Include all information listed on the support page.

Conclusion

The video provides practical tips and tricks for developers working with the Google Home APIs. It emphasizes the importance of understanding the documentation, exploring device capabilities using the Google Home Playground, and leveraging the Automation API effectively. The video also highlights the importance of checking device functionality, using the Assistant Fulfillment trait for advanced automations, and utilizing available support resources. The key takeaway is to approach Home APIs development systematically, starting with planning and testing, and to leverage the available tools and resources to overcome challenges.