Start Session
A session represents one test interaction period on an allocated device. Create a session after the allocation has assigned a device.
The session starts the Device Park/Appium runtime, but the SDK does not execute Appium commands. Use your normal Appium client after the session is ready.
Before You Begin
- Create an allocation and keep its allocationId.
- Wait until Device Park assigns a device to the allocation.
- Prepare the required user and company identifiers and names.
- Decide whether the session must be recorded.
- Use an Appium version supported by your Device Park environment, or leave it unset to use the environment default.
Allocation Relationship
allocationId connects the session to its reserved device.
One active allocation can be reused for multiple sessions. A common sequence is:
- Create one allocation.
- Start the first session with its allocationId.
- Run the test and stop the session.
- Start another session with the same allocationId.
- Release the allocation after the last session.
Do not release the allocation between sessions. Whether sessions may run concurrently depends on the Device Park environment; the safe default is to stop one session before starting the next.
You can create multiple sessions from one active allocation. Stop the current session before starting the next unless your Device Park administrator confirms concurrent-session support.
SDK Method
Java | Node.js |
|---|---|
client.sessions().start(request) | await client.sessions().start(request) |
Request Fields
Field | Required | Default | Description |
|---|---|---|---|
allocationId | Yes | - | Active allocation identifier |
userId | Yes | - | Unique user identifier |
userEmail | Yes | - | User email address |
companyId | Yes | - | Unique company identifier |
companyName | Yes | - | Non-blank company name |
videoRecording | No | false | Enables session recording |
appiumVersion | No | Environment default | Requested Appium version |
companyPoolId | No | - | Company pool context |
customVideoRecordingPath | No | - | Custom recording path |
Request Mapping
The SDK sends the built request as a JSON body. OAuth authorization and JSON content headers are managed by the SDK client.
{
"allocationId": "allocation-123",
"userId": 42,
"userEmail": "[email protected]",
"companyId": 7,
"companyName": "Example Company",
"videoRecording": true,
"appiumVersion": "2.5.0"
}sessionId is not a request field. Device Park generates it when the session starts and returns it in the response. Unset optional builder fields are omitted, and videoRecording defaults to false.
Java SDK 1.0.1 still exposes a legacy sessionId(...) builder method and does not validate every required field during build(). Do not set sessionId. Always provide allocationId, userId, userEmail, companyId and a non-blank companyName; Device Park validates these fields when the request is received.
Examples
Session session = client.sessions().start(
DeviceStartSessionRequest.builder()
.allocationId("allocation-123")
.userId(42L)
.userEmail("[email protected]")
.companyId(7L)
.companyName("Example Company")
.videoRecording(true)
.appiumVersion("2.5.0")
.build()
);
System.out.println(session.sessionId());Result
The method returns one Session. Store sessionId; it is required to stop the session, download the Appium log and list screen records.
Field group | Fields |
|---|---|
Identity | id, sessionId, allocationId, client |
Lifecycle | state, startDate, endDate, latestInteractionTime, createdAt, updatedAt, dataAccessEndDate |
Device | deviceSerial, deviceName, deviceModel, deviceManufacturer, devicePlatform, deviceVersion |
User/company | userId, userEmail, companyId, companyName |
Runtime/evidence | appiumVersion, videoRecording, videoRecordUrl |
{
"id": 1001,
"state": "ACTIVE",
"client": null,
"sessionId": "session-123",
"allocationId": "allocation-123",
"startDate": "2026-07-28T10:00:00Z",
"endDate": null,
"latestInteractionTime": "2026-07-28T10:00:00Z",
"userId": 42,
"userEmail": "[email protected]",
"companyId": 7,
"companyName": "Example Company",
"deviceSerial": "R58M123456A",
"deviceName": "Galaxy S23",
"deviceModel": "SM-S911B",
"deviceManufacturer": "Samsung",
"devicePlatform": "Android",
"deviceVersion": "14",
"videoRecording": true,
"videoRecordUrl": null,
"appiumVersion": "2.5.0",
"createdAt": "2026-07-28T10:00:00Z",
"updatedAt": "2026-07-28T10:00:00Z",
"dataAccessEndDate": null
}state is a server-provided string; see List Sessions for its documented values. Recording URLs can remain null until processing is complete.
Continue with your Appium test. When finished, call Stop Session.