Set the device and viewport
The device options set a session's window size, make the browser look like a phone, hide the window, or remove the browser's toolbars. Without them, a session is a desktop browser with a visible window of 1920 by 1080 pixels. Set them when you create the session. You cannot change them on a live session.
Which options you need depends on what reads the page. A computer-use model that clicks by coordinates needs the window size that it expects. An agent that reads a site's mobile version needs a mobile device.
Before you begin
Put your Steel API key in the STEEL_API_KEY environment variable. Then install the Steel SDK and Playwright.
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightIn Go and Rust, install only the SDK, as the Go and Rust SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.
Set the viewport
Pass dimensions with a width and a height in pixels. The largest window is 1920 by 1080. Steel reduces a larger value to that size. The session reserves room for the browser's toolbars, as a desktop browser does, so the page sees a viewport a little smaller than dimensions: 8 pixels narrower and 91 pixels shorter. For a viewport of 1280 by 720, pass 1288 by 811. At the largest size, the window is 1919 by 1079, so a session of 1920 by 1080 gives the page a viewport of 1911 by 988. In a headless session, the viewport is as wide as dimensions and 87 pixels shorter.
This program creates a session with a window of 1280 by 800, connects Playwright, prints the size of the page's viewport, and releases the session.
import Steel from "steel-sdk";
import { chromium } from "playwright";
const client = new Steel();
const session = await client.sessions.create({
dimensions: { width: 1280, height: 800 },
});
try {
const browser = await chromium.connectOverCDP(session.websocketUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
const [width, height] = await page.evaluate(() => [window.innerWidth, window.innerHeight]);
console.log(width, height);
await browser.close();
} finally {
await client.sessions.release(session.id);
}from playwright.sync_api import sync_playwright
from steel import Steel
client = Steel()
session = client.sessions.create(
dimensions={"width": 1280, "height": 800},
)
try:
with sync_playwright() as playwright:
browser = playwright.chromium.connect_over_cdp(session.websocket_url)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
width, height = page.evaluate("[window.innerWidth, window.innerHeight]")
print(width, height)
browser.close()
finally:
client.sessions.release(session.id)Run the program:
npx tsx dimensions.mtspython dimensions.pyThe viewport is 8 pixels narrower and 91 pixels shorter than dimensions:
1272 709Emulate a mobile device
Set deviceConfig.device to "mobile". The browser then presents itself as a phone: a mobile user agent, a mobile viewport, touch input, and a mobile fingerprint that matches them. Many sites serve a simpler mobile version, with fewer menus and a smaller page, which an agent can find easier to use.
const session = await client.sessions.create({
deviceConfig: { device: "mobile" },
});session = client.sessions.create(
device_config={"device": "mobile"},
)session, err := client.Sessions.New(ctx, steel.SessionNewParams{
DeviceConfig: steel.F(steel.SessionNewParamsDeviceConfig{
Device: steel.F(steel.SessionNewParamsDeviceConfigDeviceMobile),
}),
})
if err != nil {
return err
}let session = client
.sessions()
.create(steel_rs::SessionCreateParams {
device_config: Some(steel_rs::SessionCreateParamsDeviceConfig {
device: Some(steel_rs::SessionCreateParamsDeviceConfigDevice::Mobile),
}),
..Default::default()
})
.await?;Without dimensions, a mobile session is 508 by 1074 pixels. That is also the smallest size for a mobile session. A smaller dimensions fails with 400, and no session is created:
Mobile sessions require dimensions of at least 508x1074, but received 390x844. Increase 'dimensions' to meet the minimum, or omit them to use the mobile defaults.The device sets the browser's fingerprint, not the session's location. To choose a country, use a proxy.
To look like a phone, use deviceConfig instead of a mobile user agent, which changes only that string and turns off Steel's fingerprint.
Run headless
A headless session runs the browser without a visible window. It shows the older live view, made from screen captures of the page, and it records page events instead of a video. Use it when your app needs those, for example to replay the events with rrweb-player, as Fetch the recording shows. Sessions are headful by default. A headful session streams the live view as video and records a video.
Set headless to true when you create the session:
const session = await client.sessions.create({ headless: true });session = client.sessions.create(headless=True)session, err := client.Sessions.New(ctx, steel.SessionNewParams{
Headless: steel.F(true),
})
if err != nil {
return err
}let session = client
.sessions()
.create(steel_rs::SessionCreateParams {
headless: Some(true),
..Default::default()
})
.await?;Run fullscreen
Set fullscreen to true to launch the browser over the whole screen, with no address bar, no tabs and no toolbars. The page gets all 1920 by 1080 pixels, and screenshots and recordings show only the page.
const session = await client.sessions.create({ fullscreen: true });session = client.sessions.create(fullscreen=True)session, err := client.Sessions.New(ctx, steel.SessionNewParams{
Fullscreen: steel.F(true),
})
if err != nil {
return err
}let session = client
.sessions()
.create(steel_rs::SessionCreateParams {
fullscreen: Some(true),
..Default::default()
})
.await?;A fullscreen session is always 1920 by 1080, and it ignores dimensions. Use dimensions for a given size, or fullscreen for the whole screen, not both.
Click coordinates that you saved from a session without fullscreen do not match a fullscreen session, because the viewport changes from 1911 by 988 to 1920 by 1080. The live view's fullscreen button is different: it enlarges the view on your screen and does not change the browser.
Check that it worked
Read the viewport in the page, as the program in Set the viewport does. A window of 1280 by 800 gives 1272 709, and a fullscreen session gives 1920 1080. In a mobile session, read navigator.userAgent in the page as well. It is a phone's user agent, with Mobile in it.
Next steps
- Computer actions: Click and type at coordinates in the viewport that you set.