Device groups
About device groups
Our device groups feature allows end-users to share a single server-side FaceMap across multiple devices.
This eliminates the need for end-users to re-activate the authentication method on each new device, simplifying the user experience and reducing onboarding friction.
By linking an end-user's devices together, you can provide a more seamless and secure cross-device experience.
When to use device groups
The primary benefit of device groups currently is to enable a single server-side FaceMap to be shared across multiple devices. This means that your end-users can avoid going through the activation process for the authentication method on every new phone or tablet.
If you are not using our face authentication feature (meaning that DEVICE_SERVER_SIDE_FACE is not an allowed authentication method in your application configuration), then you will not see any immediate functional benefits from using device groups currently.
Device groups lay the foundation for more powerful cross-device features in the future.
How to implement device groups
To use device groups, you do not need to configure anything specific in your application configuration. However, you must ensure that all devices belong to the same application configuration. This is because a device group is constrained to a single application configuration.
To experience the full benefit with dynamic activation of the DEVICE_SERVER_SIDE_FACE authentication method, then the devices need to be upgraded to SDK version 3.22 or later.
To learn more about the expected behaviour between versions, see the table below:
| SDK version | Behaviour |
|---|---|
| SDK version 3.22 or later | These devices can recognise and immediately use an existing FaceMap available in the group without needing to re-activate the face authentication method. |
| SDK versions older than 3.22 | These devices are unaware of the device group and shared FaceMap. This means that they will need to activate face authentication again, even if a FaceMap already exists in the group. Note: Any face authentication activation performed by these older devices is added to the group and can be immediately used by other devices running SDK 3.22 or later. |
Adding devices to a group
A device group is identified by a unique group_id, which is a UUID. All devices in a group share this identifier.
Devices can be added to a group in several ways:
- Implicit creation: A device group is created implicitly when an end-user activates face authentication method
DEVICE_SERVER_SIDE_FACEfor the first time. This device then becomes the first member of this group. - During registration: By providing an existing
group_idwhen starting a new registration. - After registration: By using the device group endpoints to link an existing device to a group.
Dynamic activation on new devices
When a new device running SDK version 3.22 or later is added to a device group with face authentication already activated, the DEVICE_SERVER_SIDE_FACE authentication method is dynamically activated on that device.
This allows immediate use of face authentication without requiring the end-user to reactivate the face authentication method.
Group lifecycle and cleanup
The lifecycle of a device group is managed automatically:
- Implicit deletion: If a device is removed from a group and it was the last device in that group, then the group and its associated FaceMap are implicitly deleted.
- No empty groups: A group cannot exist without at least one associated device. This ensures that resources like FaceMaps are cleaned up when no longer needed.
API integration
We provide endpoints for device groups that allow you to integrate with the Encap REST API.
With these endpoints, you can carry out operations such as:
- Manage device groups.
- Link devices to groups
- List group details.
- Manage the lifecycle of the group.
Get group for a device
To get information about the device group for a specific device, you can use the following endpoint.
GET /api/smart-device/v1/devices/{deviceId}/group
{
"group_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"ref": "/groups/a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
Create new group for a device
To create a new device group and add the device to that group, you can use the following endpoint.
This operation is only possible if the device does not already have a group.
POST /api/smart-device/v1/devices/{deviceId}/group
{
"group_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
Update group for a device
To update or set the device group for a device, you can use the following endpoint.
You can use this endpoint to move a device to a different group.
PUT /api/smart-device/v1/devices/{deviceId}/group
{
"group_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
Remove device from a group
To remove a device from its device group, you can use the following endpoint.
If this operation results in there being no devices left in the device group, then the device group and its associated FaceMap are implicitly deleted.
DELETE /api/smart-device/v1/devices/{deviceId}/group
Get group details
To get detailed information about a specific device group, you can use the following endpoint:
Detailed information includes:
- The status of face authentication.
- A list of devices in the device group.
GET /api/smart-device/v1/groups/{groupId}
{
"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"server_side_face": {
"status": "ACTIVE"
},
"devices": [
{
"device_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
"current_client_api_version": "3.22.0"
},
{
"device_id": "01234567-89ab-cdef-0123-456789abcdef",
"current_client_api_version": "3.22.0"
}
]
}
Start device registration with group
To assign a device to a device group during the registration process, you can use the following endpoint.
This is possible because when you start a device registration, you have the option to provide an existing group_id to immediately link the new device to that device group.
POST /api/smart-device/v1/registrations
{
// ... other device registration fields
// Optionally assign device registration to an existing group:
"group_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}