User Agent Control

The User-Agent request header is a characteristic string that identifies your browser's application, operating system, vendor, and version to websites. Setting a realistic user agent helps with proper page rendering and basic bot detection avoidance.

Many sites use this information to render the site differently for each user, and sometimes even for rudimentary bot detection. If you run chrome headless and want to take a screenshot of a page, it's a good idea to set a user agent so that web fonts load properly.

Why Set User Agents?

• Font Rendering: Headless browsers need proper user agents for web fonts to load correctly
• Site Compatibility: Some sites serve different content based on user agent detection
• Basic Bot Detection: Avoid obvious automation signatures that trigger simple bot detection

tip

For advanced bot detection bypass, try BrowserQL which handles user agents automatically.

There are essentially couple of ways to set the user agent, like doing it directly via the library or using the session api.

You can use Library Code when you're building automation scripts or need fine-grained control over your browser sessions. This method is ideal for most development scenarios. Or else, use REST API when you need to make simple one-off requests or integrate with existing API workflows. Perfect for quick screenshots, content extraction, or PDF generation.

Using Library Code (Recommended)

Set the user agent directly in your automation code. This method gives you the most control and is ideal for most automation scenarios.

Puppeteer

import puppeteer from "puppeteer";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE`,
});
const page = await browser.newPage();
await page.setUserAgent(
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
);

Playwright

Javascript

import { chromium } from "playwright-core";

(async () => {
  const browser = await chromium.connectOverCDP(
    `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE`
  );

  const context = browser.contexts()[0] || (await browser.newContext());
  const page = await context.newPage();

  // Set User-Agent
  await context.setDefaultUserAgent(
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
  );
})();

Python

import asyncio
from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(
            "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"
        )

        context = browser.contexts[0] if browser.contexts else await browser.new_context()
        page = await context.new_page()

        # Set User-Agent
        await context.set_default_user_agent(
            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
        )

asyncio.run(main())

Java

import com.microsoft.playwright.*;

public class PlaywrightExample {
    public static void main(String[] args) {
        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().connectOverCDP(
                "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"
            );

            BrowserContext context = browser.contexts().isEmpty()
                ? browser.newContext()
                : browser.contexts().get(0);

            // Set User-Agent
            context.setDefaultUserAgent(
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
            );
        }
    }
}

C#

using System;
using System.Threading.Tasks;
using Microsoft.Playwright;

class Program
{
    static async Task Main(string[] args)
    {
        var playwright = await Playwright.CreateAsync();
        var browser = await playwright.Chromium.ConnectOverCDPAsync(
            "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"
        );

        var context = browser.Contexts.Count > 0
            ? browser.Contexts[0]
            : await browser.NewContextAsync();

        // Set User-Agent
        await context.SetDefaultUserAgentAsync(
            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
        );
    }
}

Using REST API

Include userAgent in your API request body when using endpoints like /screenshot, /content, /pdf, or /scrape. This method is perfect for simple one-off requests.

{
  "url": "https://example.com/",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3_1) AppleWebKit/605.1.15"
}

Common User Agent Strings

Chrome Desktop:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36

Safari Desktop:

Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3_1) AppleWebKit/605.1.15

Mobile Chrome:

Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15

Next Steps

Ready to take your browser automation to the next level? Explore these essential areas:

CAPTCHA Solutions

Automatically solve captchas and other challenge-response systems with advanced AI

Human-in-Loop Automation

Combine automated scripts with human intervention for complex workflows and debugging

Recording with LiveURL

Record and replay browser sessions with live URL access for debugging and analysis