Advanced configuration reference
Advanced configuration reference
Most administrators should use AIQ. The following reference is for standalone nodes and integration tooling. DSServer validates known keys and keeps its existing ownership boundaries; generic BrowserStack capabilities are not arbitrary pass-through settings.
Standalone global.json example and editing
procedure
-
Stop the affected DSServer with its normal service/launcher controls and back up the active configuration.
-
Locate <installation>/NetworkProxy/config/global.json (development run: distribution/config/global.json).
-
Merge the root browserStack object alongside existing root sections. Preserve all other configuration. The example deliberately disables accessibility for an initial functional smoke test; enable it when the account and target are ready.
-
Replace the credential placeholders privately. The profiles array replaces the existing list; these names match known starter profiles whose internal fields are filled by the loader.
-
Start DSServer, inspect configuration logs, and verify the profile list and one short run.
{
"browserStack": {
"enabled": true,
"username": "<BROWSERSTACK_USERNAME>",
"accessKey": "<BROWSERSTACK_ACCESS_KEY>",
"localBinary": "./browserstack-local",
"maxSessions": 1,
"defaults": {
"projectName": "CustomerPortal-QA",
"accessibility": false
},
"profiles": [
{
"name": "BrowserStack-Chrome-Latest-Windows11",
"enabled": true,
"target": {
"browser": "chrome",
"browser_version": "latest",
"os": "Windows",
"os_version": "11"
}
},
{
"name": "BrowserStack-Safari-iPhone16-iOS18",
"enabled": true,
"target": {
"browser": "iphone",
"os": "ios",
"os_version": "18",
"device": "iPhone 16",
"real_mobile": true
}
}
]
}
}
The active file contains the access key in plain text. Restrict filesystem access and keep it out of source control, support bundles and shared folders. Shipped templates contain blank credentials. For custom targets, add through AIQ’s catalog or preserve the complete profile structure described below.
Account, endpoints and browser policy
| Setting | Default | Meaning |
|---|---|---|
| enabled | false | Opt-in integration switch. |
| username, accessKey | Blank | BrowserStack account credentials. |
| localBinary | ./browserstack-local | Bundled directory or explicit executable path. |
| maxSessions | 1 | Per-node cloud-session limit. |
| revision | local | AIQ sets a new saved revision; a running session retains its launch configuration. |
| endpoints.webdriver | https://hub-cloud.browserstack.com/wd/hub | Session creation and commands. |
| endpoints.api | https://api.browserstack.com | Plan validation and uncertain-allocation reconciliation. |
| endpoints.testhub | https://collector-observability.browserstack.com | Accessibility registration/events/finalization. |
| endpoints.accessibilityApi | https://api-accessibility.browserstack.com | Final report reads. Use the account’s documented regional endpoint if region restrictions apply. |
Endpoints must use HTTPS and contain no URL credentials; only localhost test endpoints may use HTTP.
Policy precedence: defaults → matching familyDefaults (Chromium, Firefox, Safari) → iosDefaults for real iOS → the profile’s overrides. Later layers override earlier ones.
| Policy key | Default | Meaning |
|---|---|---|
| seleniumVersion | 4.45.0 | Requested provider Selenium version. |
| idleTimeoutSeconds | 90 | Provider idle timeout. |
| nativeProtocol | auto | auto, webdriver, cdp or bidi. Explicit CDP/BiDi fails startup if attachment is unavailable. |
| acceptInsecureCerts | true | Certificate policy; insufficient by itself for the measured Safari trust path. |
| networkLogs | False; true for Safari/iOS | Provider network proxy/logging used by the Safari HTTPS path. |
| captureNetworkContent | false | Response-body capture. |
| projectName | Blank | Stable BrowserStack grouping/report project. |
| buildNameMode | perRun | Build naming: perRun (unique per run), perDay (AIQ-YYYY-MM-DD, node-local date) or static (AIQ-Executions). AIQ's Build name sets it. |
| buildNameSuffix | Blank | Added after a dash to every build name in any mode. Up to 64 letters, digits, ., _ or -; other text rejects the configuration. Blank adds nothing and clears an earlier suffix. AIQ's Build name suffix (optional) sets it (17 Nov 2026). |
| accessibility | true | Enable integrated scans when eligible. |
| accessibilityOptions | WCAG 2.1 AA; auto scanning true | wcagVersion: wcag2a, wcag2aa, wcag2aaa, wcag21a, wcag21aa, wcag21aaa, wcag22a, wcag22aa, wcag22aaa; or rgaaVersion: "rgaa". Issue-type booleans: needsReview, experimental, advanced, bestPractice. |
| Advanced accessibility scope | Unset | includeTagsInTestingScope and excludeTagsInTestingScope are accepted lists. There is no AIQ field for them; end-to-end tag-based selection was not verified in this documentation review. |
Profile schema, timeouts and Local overrides
| Profile field | Rule |
|---|---|
| name | Unique; begins BrowserStack-; remaining characters use letters, digits, dots, underscores or hyphens. Preserve referenced names. |
| enabled | Controls availability in selectors. |
| target | Browser, OS and OS version required; desktop also needs browser version. Real mobile needs device and real_mobile=true. Use exact catalog values. |
| ManagerClass | com.appvance.platform.browserstack.BrowserStackBrowserManager. |
| browserFamily, groupName, isMobile | Match the target and desktop/mobile grouping. No local executable or container-pool configuration. |
| options | Keep session-routing: owned. Desktop Safari uses browser-message-transport: http. |
| overrides | Per-profile browser policy, for example {"accessibility":false}. |
| Section | Default values in milliseconds |
|---|---|
| timeouts | connectMs=10000; createSessionMs=90000; commandMs=30000; deleteSessionMs=10000; localStartMs=60000; localStopMs=2000; accessibilityReportMs=240000 (used only by the final playback step, which is turned off). |
| polling | inventoryMs=2000; healthMs=15000. |
| validation | refreshIntervalMs=60000; connectTimeoutMs=1000; readTimeoutMs=1500. |
| localUpdates | enabled=true; blank cacheDirectory; connectTimeoutMs=4000; readTimeoutMs=8000; downloadTimeoutMs=45000; lockTimeoutMs=60000; versionTimeoutMs=5000. |
Configured timing values must be between 1 and 3,600,000 milliseconds. Accessibility final-report polling is fixed at 30-second intervals with a 10-minute deadline.
-
BROWSERSTACK_LOCAL_BINARY: override the delivered executable path.
-
BROWSERSTACK_LOCAL_BUNDLE_DIR or -Dds.browserstack.local.bundleDir: override the bundled folder.
-
BROWSERSTACK_LOCAL_CACHE_DIR or -Dds.browserstack.local.cacheDir: choose the managed cache.
HTTP configuration for tools
Use POST /ds/dyn/platform/configureBrowserStack with form field configuration containing the JSON browserStack section itself. It merges, saves to the active file and applies immediately. Readback returns revision/profiles/availability without credentials.
Object merges do not delete omitted keys. Send explicit replacements to reset settings; a supplied profiles array replaces the saved array. To switch from RGAA back to WCAG, send rgaaVersion: "" with the chosen wcagVersion. Keep the credentials in the protected request body; never put them into URL parameters or command history. AIQ’s Apply button handles this transfer.