SDK Overview
The Device Park SDK connects a test runner or CI pipeline to the Device Park resource lifecycle. It provides typed Java and Node.js methods for device discovery, reservation, managed sessions, evidence collection and application storage.
The SDK manages Device Park resources. Your Appium client remains responsible for creating Appium sessions and sending automation commands.
Resource Model
Resource | What it represents | Identifier used next |
|---|---|---|
Device | A visible physical or virtual mobile device | serial |
Pool | A managed group of devices | pool.id as devicePoolId |
Allocation | A temporary reservation or queued reservation request | allocationId |
Device Park session | A managed test interaction period on an allocation | sessionId |
Application | A stored APK or IPA revision | fileKey |
Screen record | Recording evidence generated for a session | fileKey or temporary downloadUrl |
Choose the Device Target
Use the least restrictive target that still satisfies the test:
Test requirement | Allocation input |
|---|---|
Run on one known device | serial |
Run on any device from a managed group | devicePoolId |
Run on any matching platform version | platform and platformVersion |
Restrict by hardware | manufacturer or model |
More specific criteria reduce the number of matching devices and can increase queue time.
Listing a pool does not return its devices. Use List Devices with DeviceFilter.POOL_ID, or allocate directly with devicePoolId when the test can use any device from the pool.
Allocation and Session Lifecycle
An allocation reserves access to the device. A Device Park session represents one managed test period on that reservation.
flowchart TD
select["Select device, pool or criteria"] --> allocate["Create allocation"]
allocate --> assigned{"deviceSerial assigned?"}
assigned -- "No" --> wait["Inspect the same allocation"]
wait --> assigned
assigned -- "Yes" --> start["Start Device Park session"]
start --> test["Run Appium automation"]
test --> stop["Stop Device Park session"]
stop --> more{"Another scenario?"}
more -- "Yes" --> start
more -- "No" --> artifacts["Collect logs and recordings"]
artifacts --> release["Release allocation"]Store both identifiers:
- allocationId connects sessions to the reserved device and is required for release.
- sessionId identifies one managed session and is required for stop, logs and recordings.
Stopping a session does not release the allocation. One active allocation can be reused for multiple sequential sessions. Release it only after the final session.
Queue and Expiration
Allocation creation can return before a device is assigned:
{
"allocationId": "allocation-123",
"deviceSerial": null,
"requestId": "request-456",
"position": 2,
"expiresAt": "2026-07-28T12:30:00Z"
}When deviceSerial is null, keep the same allocationId and inspect it with List Allocations. Apply an application-level deadline in the CI runner. Do not create another allocation for each status check.
expiresAt is the reservation expiration timestamp. Environment idle-timeout policies can also apply; ask the Device Park administrator for the configured duration.
Authentication and Client Lifetime
Both SDKs use OAuth2 client credentials.
- Create one DeviceParkApiClient.
- Reuse it throughout the test run.
- Let the SDK cache and renew the access token.
- Close the client during cleanup.
Java supports try-with-resources. Node.js uses await client.close().
Pagination, Filtering and Nullable Fields
List methods return PageDto<T>:
{
"size": 20,
"page": 0,
"totalPages": 1,
"totalElements": 1,
"data": []
}page is zero-based. Filter rules belong to the request builder and are evaluated by Device Park only when the SDK transmits them. Every list-method page documents the exact filter constants and Java/Node.js compatibility.
Some response fields can be null because a workflow has not reached that state:
- Allocation.deviceSerial while waiting for assignment
- Session.endDate while a session is active
- videoRecordUrl or recording downloadUrl while processing is incomplete
Validate identifiers before passing them to the next SDK method.