broswer-automation/examples/background-page-navigation.md

Background Page Navigation Examples

This document demonstrates how to use the new backgroundPage parameter to open URLs in background pages using minimized windows.

Overview

The backgroundPage parameter allows you to open URLs without interrupting the user's current workflow. When set to true, it creates a minimized window that runs in the background instead of opening a new tab or focused window.

Usage Examples

1. Basic Background Page Navigation

{
  "name": "chrome_navigate",
  "arguments": {
    "url": "https://example.com",
    "backgroundPage": true
  }
}

This will:

1. Create a new window with the specified URL
2. Immediately minimize the window to keep it in the background
3. Return window and tab information for reference

2. Natural Language Background Navigation

{
  "name": "chrome_navigate_natural",
  "arguments": {
    "query": "open google",
    "backgroundPage": true
  }
}

This will:

1. Process the natural language query ("open google" → "https://www.google.com")
2. Create a minimized window with the processed URL
3. Keep the window running in the background

3. Background Page with Custom Dimensions

{
  "name": "chrome_navigate",
  "arguments": {
    "url": "https://example.com",
    "backgroundPage": true,
    "width": 1920,
    "height": 1080
  }
}

The window will be created with the specified dimensions before being minimized.

4. Parameter Precedence

When both newWindow and backgroundPage are specified:

{
  "name": "chrome_navigate",
  "arguments": {
    "url": "https://example.com",
    "newWindow": true,
    "backgroundPage": true
  }
}

The backgroundPage parameter takes precedence, and the URL will be opened in a minimized window.

Use Cases

1. Background Data Loading

Open data-heavy pages in the background while continuing to work:

{
  "name": "chrome_navigate",
  "arguments": {
    "url": "https://dashboard.example.com/reports",
    "backgroundPage": true
  }
}

2. Preloading Content

Preload content that will be needed later:

{
  "name": "chrome_navigate_natural",
  "arguments": {
    "query": "youtube trending",
    "backgroundPage": true
  }
}

3. Background Monitoring

Open monitoring or status pages in the background:

{
  "name": "chrome_navigate",
  "arguments": {
    "url": "https://status.example.com",
    "backgroundPage": true
  }
}

Response Format

When using backgroundPage: true, the response will include:

{
  "success": true,
  "message": "Opened URL in background page (minimized window)",
  "windowId": 123,
  "tabs": [
    {
      "tabId": 456,
      "url": "https://example.com"
    }
  ]
}

Implementation Details

The background page functionality:

1. Creates a new window using chrome.windows.create() with full dimensions
2. Sets focused: false to avoid stealing focus
3. Sets state: 'normal' to ensure proper initial window state
4. Waits 1 second for page load and proper dimension establishment
5. Calls chrome.windows.update() with state: 'minimized' to move to background
6. Returns window and tab information for future reference

This approach ensures web automation tools can properly interact with the page even when minimized, as the window maintains its proper dimensions and DOM accessibility.

Comparison with Regular Navigation

Parameter	Behavior
backgroundPage: false (default)	Opens in new tab or focused window
backgroundPage: true	Opens full-size window, then minimizes (automation-compatible background)
newWindow: true	Opens in new focused window
newWindow: true, backgroundPage: true	Opens full-size window, then minimizes (backgroundPage wins)

Browser Compatibility

This feature requires:

• Chrome extension with windows permission
• Chrome browser (Chromium-based browsers)
• The chrome.windows.WindowState.MINIMIZED API support