Displaying Device Health

You can display the health status of your end users’ devices in your app.

To display the health—that is, the online/offline status—of your end users’ devices in your app, you can use the following Seam mechanisms:

• Use the properties.online property of the device object.
• Use the device.connected and device.disconnected events.

Get Device Status Using Device Properties

Seam polls connected devices and accounts every ten minutes and updates the Boolean device.properties.online property accordingly. Use a Get Device request to retrieve the current online/offline status of a device. Then, display the device status in your app.

You can also use the prebuilt device details Seam Component, which includes a device status display.

JavaScript

Request:

const device = await seam.devices.get({
  device_id: '36cf1a96-196d-41b0-9804-88154387f1f9',
})
console.log('Online:', device.properties.online)

Response:

Online: true

cURL

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/devices/get' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9"
}' | jq -r '"Online: " + (.device.properties.online | tostring)'

Response:

Online: true

Python

Request:

device = seam.devices.get("36cf1a96-196d-41b0-9804-88154387f1f9")
pprint("Online: " + str(device.properties.online))

Response:

'Online: True'

Ruby

Request:

device = client.devices.get(device_id: "36cf1a96-196d-41b0-9804-88154387f1f9")
puts "Online: " + device.properties.online.to_s

Response:

Online: true

PHP

Request:

$device = $seam->devices->get(device_id: "36cf1a96-196d-41b0-9804-88154387f1f9");
if ($device->properties->online === true) {
  echo "Online: true\n";
} else {
  echo "Online: false\n";
}

Response:

Online: true

C#

Request:

var device = seam.Devices.Get(deviceId: "36cf1a96-196d-41b0-9804-88154387f1f9");
Console.WriteLine("Online: " + device.Properties.Online);

Response:

Online: True

Get Device Status Using Connection-Related Events

When a device connection or disconnection occurs, Seam generates a device.connected or device.disconnected event, respectively. You can retrieve these events using a List Events request or through webhooks and then display the corresponding status in your app.

To help you test your app against events—like device disconnection or removal—that are difficult to orchestrate in a QA environment using real devices, Seam provides a suite of simulate endpoints that you can use in a sandbox workspace. See Testing Your App Against Device Disconnection and Removal.

Get Connection-Related Events Using a List Events Request

When issuing a List Events request to retrieve device.connected or device.disconnected events for a specific device, include the following parameters:

Parameter	Type	Description
device_id	String (UUID)	ID of the device for which you want to retrieve device.connected or device.disconnected events
event_type	String	Event type that you want to retrieve, that is, device.connected or device.disconnected
since	String	Desired starting event generation date and time You must include since or between.
between	Set of two strings	Desired starting and ending event generation dates and times For example: [“2024-01-01T00:00:00Z”, “2024-02-01T00:00:00Z”] You must include between or since.

The following example uses the List Events request to retrieve all device.connected events for a specific device since January 1, 2024:

JavaScript

Request:

const device_connected_events = await seam.events.list({
  device_id: '36cf1a96-196d-41b0-9804-88154387f1f9',
  event_type: 'device.connected',
  since: '2024-01-01T00:00:00Z',
})
console.log(device_connected_events)

Response:

[
  {
    "event_id": "ca3114b2-088d-43f9-bb5e-ded5d19ad053",
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.connected",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "created_at": "2024-02-04T21:55:09.681Z",
    "occurred_at": "2024-02-04T21:55:09.681Z",
    "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
  },
  {
    "event_id": "39fcb512-82a4-431d-969f-3935eeba8929",
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.connected",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "created_at": "2024-02-03T04:54:39.744Z",
    "occurred_at": "2024-02-03T04:54:39.744Z",
    "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
  }
]

cURL

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/events/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
  "event_type": "device.connected",
  "since": "2024-01-01T00:00:00Z"
}'

Response:

{
  "events": [
    {
      "event_id": "ca3114b2-088d-43f9-bb5e-ded5d19ad053",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.connected",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-02-04T21:55:09.681Z",
      "occurred_at": "2024-02-04T21:55:09.681Z",
      "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
    },
    {
      "event_id": "39fcb512-82a4-431d-969f-3935eeba8929",
      "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
      "event_type": "device.connected",
      "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
      "created_at": "2024-02-03T04:54:39.744Z",
      "occurred_at": "2024-02-03T04:54:39.744Z",
      "connected_account_id": "c1413928-f527-4e12-abf9-d5e18d92dd33"
    }
  ],
  "ok": true
}

Python

Request:

device_connected_events = seam.events.list(
    device_id = "36cf1a96-196d-41b0-9804-88154387f1f9",
    event_type = "device.connected",
    since = "2024-01-01T00:00:00Z"
)
pprint(device_connected_events)

Response:

[{'connected_account_id': 'c1413928-f527-4e12-abf9-d5e18d92dd33',
  'created_at': '2024-02-04T21:55:09.681Z',
  'device_id': '36cf1a96-196d-41b0-9804-88154387f1f9',
  'event_id': 'ca3114b2-088d-43f9-bb5e-ded5d19ad053',
  'event_type': 'device.connected',
  'occurred_at': '2024-02-04T21:55:09.681Z',
  'workspace_id': '398d80b7-3f96-47c2-b85a-6f8ba21d07be'},
 {'connected_account_id': 'c1413928-f527-4e12-abf9-d5e18d92dd33',
  'created_at': '2024-02-03T04:54:39.744Z',
  'device_id': '36cf1a96-196d-41b0-9804-88154387f1f9',
  'event_id': '39fcb512-82a4-431d-969f-3935eeba8929',
  'event_type': 'device.connected',
  'occurred_at': '2024-02-03T04:54:39.744Z',
  'workspace_id': '398d80b7-3f96-47c2-b85a-6f8ba21d07be'}]

Ruby

Request:

device_connected_events = client.events.list(
  device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
  event_type: "device.connected",
  since: "2024-01-01T00:00:00Z"
)
puts device_connected_events.inspect

Response:

[<Seam::Event:0x00438
  event_id="ca3114b2-088d-43f9-bb5e-ded5d19ad053"
  device_id="36cf1a96-196d-41b0-9804-88154387f1f9"
  event_type="device.connected"
  workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
  created_at=2024-02-04 21:55:09.681 UTC>, <Seam::Event:0x00460
  event_id="39fcb512-82a4-431d-969f-3935eeba8929"
  device_id="36cf1a96-196d-41b0-9804-88154387f1f9"
  event_type="device.connected"
  workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
  created_at=2024-02-03 04:54:39.744 UTC>]

PHP

Request:

$device_connected_events = $seam->events->list(
  device_id: "36cf1a96-196d-41b0-9804-88154387f1f9",
  event_type: "device.connected",
  since: "2024-01-01T00:00:00Z"
);
echo json_encode($device_connected_events), "\n";

Response:

[
  {
    "event_id": "ca3114b2-088d-43f9-bb5e-ded5d19ad053",
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.connected",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "created_at": "2024-02-04T21:55:09.681Z",
    "occurred_at": "2024-02-04T21:55:09.681Z"
  },
  {
    "event_id": "39fcb512-82a4-431d-969f-3935eeba8929",
    "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
    "event_type": "device.connected",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "created_at": "2024-02-03T04:54:39.744Z",
    "occurred_at": "2024-02-03T04:54:39.744Z"
  }
]

C#

Request:

var device_connected_events = seam.Events.List(
    deviceId: "36cf1a96-196d-41b0-9804-88154387f1f9",
    eventType: Seam.Api.Events.ListRequest.EventTypeEnum.DeviceConnected,
    since: "2024-01-01T00:00:00Z"
);
foreach (var device_connected_event in device_connected_events)
{
  Console.WriteLine(device_connected_event);
}

Response:

{
  "event_id": "ca3114b2-088d-43f9-bb5e-ded5d19ad053",
  "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
  "event_type": "device.connected",
  "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
  "created_at": "2024-02-04T21:55:09.681Z",
  "occurred_at": "2024-02-04T21:55:09.681Z"
}
{
  "event_id": "39fcb512-82a4-431d-969f-3935eeba8929",
  "device_id": "36cf1a96-196d-41b0-9804-88154387f1f9",
  "event_type": "device.connected",
  "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
  "created_at": "2024-02-03T04:54:39.744Z",
  "occurred_at": "2024-02-03T04:54:39.744Z"
}

Receive Connection-Related Events Using a Webhook

You can set up webhook endpoints to receive device.connected and device.disconnected events. Then, you can use the receipt of these events to display the corresponding device status in your app. For more information about configuring webhooks, see Webhooks.