Cloud-to-cloud and Matter device deduplication

When converting a device currently using (Cloud-to-cloud) to Matter, you must ensure that the device uses the same ID on Matter that it uses when connected using the non-Matter APIs. Doing so ensures that the device shows just once on the user's Google Home Graph. Cloud-to-cloud devices can only be deduplicated when they are associated with a particular structure (home) in the Google Home app (GHA).

SYNC requirements

To avoid duplicates appearing on the Home Graph, the partner's cloud must send three new string fields for each device in the SYNC response to Google. These fields must match attributes defined in the Basic Information Cluster for the Matter device. Additionally, SYNC responses must contain roomHint:

1. matterUniqueId — The UniqueId attribute in string format.
2. matterOriginalVendorId — The VendorId attribute, in hexadecimal string format.
3. matterOriginalProductId — The ProductId attribute, in hexadecimal string format.
4. roomHint - The room where this device resides.

Documentation on intents such as SYNC may be found in the Cloud-to-Cloud primer.

The example SYNC response below shows the use of the three new fields as well as roomHint:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting",
        ],
        "willReportState": true,
        "roomHint": "office",
        "deviceInfo": { ... },
        "matterUniqueId": "00112233aabbccddeeff",
        "matterOriginalVendorId": "0xfff1",
        "matterOriginalProductId": "0x1234",
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id",
          }
        ]
      }
    ]
  }
}

When a device that had previously been operating on a user's home network using a partner's cloud is converted to a Matter device, the partner's cloud must immediately send a REQUEST SYNC to Google to update these fields as quickly as possible to avoid late deduplication.

These strings should never change once they are provided for a given device. The Unique ID should only change on a factory reset, which makes the device appear to all integrations as an entirely new device.

Automatic structure association

Cloud-to-cloud devices are not guaranteed to be automatically associated with a particular structure. In situations where automatic structure association is not possible, the relevant Cloud-to-cloud devices will appear in a dedicated section of the GHA's main screen, under a section titled Linked to you, outside of any rooms. Such devices will not be deduplicated. Devices will not be automatically placed in a structure when the user has more than one structure (home) in the GHA. Devices may fail to be structured for other reasons.

If a user moves a Cloud-to-cloud device which failed automatic structure association into a structure manually, deduplication may take place on the next SYNC so long as SYNC responses conform to the requirements noted in SYNC requirements.