### Basic GoLogin Setup and Start

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

Initialize the GoLogin SDK with your API token and profile ID, start a browser instance, and retrieve its debugger URL. Remember to replace placeholders with your actual credentials. The browser should be stopped when no longer needed.

```python
from gologin import GoLogin

# Get your API token from https://app.gologin.com/#/personalArea/TokenApi
gl = GoLogin({
    "token": "your_api_token",
    "profile_id": "your_profile_id"
})

# Start browser and get debugger URL
ws_url = gl.start()
print(f"Browser running at: {ws_url}")

# Use the browser with Selenium, Puppeteer, Playwright, etc.

# Stop when done
gl.stop()
```

--------------------------------

### Start Browser and Get WebSocket URL

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/01-gologin-class.md

Initiate the browser process for a given profile using the start() method. This method prepares the profile data, launches the browser, and returns the WebSocket URL required for connecting debugging tools.

```python
gl = GoLogin({"token": "token", "profile_id": "profile_id"})
ws_url = gl.start()
print(f"Connect your tool to: {ws_url}")
```

--------------------------------

### Usage Example for BrowserManager

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/03-browser-manager.md

Demonstrates how to create a BrowserManager instance, get the path to a specific browser executable, and use it to initialize GoLogin.

```python
from gologin.browserManager import BrowserManager

# Create manager
manager = BrowserManager()

# Get path to Chromium 132 executable
# Automatically downloads if not cached
executable_path = manager.get_orbita_path(132)

# Use in GoLogin
from gologin import GoLogin
gl = GoLogin({
    "token": "your_token",
    "profile_id": "your_profile_id",
    "executable_path": executable_path
})

ws_url = gl.start()
```

--------------------------------

### start

Source: https://github.com/gologinapp/pygologin/blob/main/README.md

Prepares the profile, starts the browser, and returns the WebSocket URL for controlling the browser.

```APIDOC
## start

### Description
Prepares the specified profile, launches the browser, and returns a WebSocket URL that can be used to control the browser instance.

### Method
`start() -> str`

### Parameters
This method does not take any direct parameters. The profile ID should be configured during GoLogin object initialization.

### Request Example
```python
gl = GoLogin({
	"token": "your token",
    "profile_id": "some_profile_id"
	})

wsUrl = gl.start()
```

### Response
- **wsUrl** (string) - The WebSocket URL for browser control.
```

--------------------------------

### Get Help on a Specific Method

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/INDEX.md

Retrieve help documentation for a specific method of the GoLogin class, such as 'start'. This helps in understanding method parameters and return values.

```python
help(GoLogin.start)
```

--------------------------------

### Run GoLogin Profile with Selenium

Source: https://github.com/gologinapp/pygologin/blob/main/README.md

This example demonstrates how to start a GoLogin profile, retrieve its debugger address, and connect it to a Selenium WebDriver instance. It also shows how to add a GoLogin proxy and manage the browser and profile lifecycle.

```python
import time
from gologin import GoLogin
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager
profile_id = "Your profile id"

# Initialize GoLogin
gl = GoLogin({
	"token": "Your token",
	"profile_id": profile_id
	})

# Start Browser and get websocket url
debugger_address = gl.start()

# Get Chromium version for webdriver
chromium_version = gl.get_chromium_version()

# Add proxy to profile
gl.addGologinProxyToProfile(profile_id, "us")

# Install webdriver
service = Service(ChromeDriverManager(driver_version=chromium_version).install())

chrome_options = webdriver.ChromeOptions()
chrome_options.add_experimental_option("debuggerAddress", debugger_address)

driver = webdriver.Chrome(service=service, options=chrome_options)

# Give command to Selenium to open the page
driver.get("http://www.python.org")

time.sleep(30)
driver.quit()
time.sleep(10)
gl.stop()

```

--------------------------------

### Initialize and Start GoLogin Browser

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/README.md

This snippet shows the basic workflow for initializing the GoLogin class with a token and profile ID, starting the browser, and stopping it when done. The `start()` method returns the WebSocket URL for connecting automation tools.

```python
from gologin import GoLogin

# 1. Initialize with your token
gl = GoLogin({
    "token": "your_api_token",
    "profile_id": "your_profile_id"
})

# 2. Start the browser
ws_url = gl.start()
# Returns: "http://127.0.0.1:9222"

# 3. Connect your automation tool
# (Selenium, Playwright, Puppeteer, etc.)

# 4. Stop when done
gl.stop()
```

--------------------------------

### start()

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/01-gologin-class.md

Prepares the profile, downloads/creates profile data, starts the browser, and returns the debugger WebSocket URL. This method is essential for initiating a browser session.

```APIDOC
## start()

### Description
Prepares the profile, downloads/creates profile data, starts the browser, and returns the debugger WebSocket URL.

### Returns
- `str` — WebSocket URL for the remote debugging protocol (e.g., `http://127.0.0.1:9222`)

### Raises
- `Exception`: If profile setup or browser spawning fails

### Example
```python
gl = GoLogin({"token": "token", "profile_id": "profile_id"})
ws_url = gl.start()
print(f"Connect your tool to: {ws_url}")
```
```

--------------------------------

### Example Bookmark Configuration

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/02-types.md

An example of how to structure bookmark data for a GoLogin profile. This dictionary can be included in the custom profile creation options.

```python
bookmarks = {
    "favorites": {
        "name": "Favorites",
        "children": [
            {"name": "Example", "url": "https://example.com"},
            {"name": "Python", "url": "https://python.org"}
        ]
    }
}
```

--------------------------------

### Complete GoLogin Configuration Example

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

A comprehensive example demonstrating the initialization of GoLogin with all available configuration options, covering required, browser, cookie, cleanup, Chrome, cloud, and debug settings.

```python
from gologin import GoLogin

gl = GoLogin({
    # Required
    "token": "your_api_token",
    "profile_id": "your_profile_id",
    
    # Browser behavior
    "tmpdir": "/tmp/gologin",
    "address": "127.0.0.1",
    "port": 9222,
    "executable_path": "",  # Auto-download
    "extra_params": ["--disable-plugins"],
    "local": False,
    "spawn_browser": True,
    
    # Cookies
    "uploadCookiesToServer": True,
    "writeCookiesFromServer": True,
    
    # Cleanup
    "cleaningLocalCookies": False,
    "restore_last_session": True,
    
    # Chrome settings
    "credentials_enable_service": False,
    
    # Cloud
    "is_cloud_headless": True,
    "is_new_cloud_browser": True,
    
    # Debug
    "debug": False
})

ws_url = gl.start()
```

--------------------------------

### Start Browser Session

Source: https://github.com/gologinapp/pygologin/blob/main/README.md

Prepares a profile, starts the browser, and returns the websocket URL. Requires a token and profile ID.

```python
gl = GoLogin({
	"token": "your token",
    "profile_id": "some_profile_id"
	})

wsUrl = gl.start()
```

--------------------------------

### Making a Simple GET Request

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/06-http-client.md

Example of performing a simple GET request to the GoLogin API with an authorization header. This is a common use case for fetching profile information.

```python
from gologin.http_client import make_request

# Simple GET request
response = make_request(
    'GET',
    'https://api.gologin.com/browser/features/profile_id/info-for-run',
    headers={'Authorization': 'Bearer token'}
)
profile_data = response.json()
```

--------------------------------

### Example Proxy Configuration

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/02-types.md

An example of how to define a proxy configuration dictionary. This can be passed to GoLogin functions to set up proxy settings for a profile.

```python
proxy = {
    "mode": "http",
    "host": "proxy.example.com",
    "port": 8080,
    "username": "user",
    "password": "pass"
}
gl.changeProfileProxy("profile_id", proxy)
```

--------------------------------

### Start Cloud Browser

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Starts a specified profile on GoLogin cloud servers, providing a remote URL for access.

```APIDOC
## POST /browser/{profile_id}/web

### Description
Starts a profile on GoLogin cloud servers.

### Method
POST

### Endpoint
/browser/{profile_id}/web

### Parameters
#### Path Parameters
- **profile_id** (string) - Required - The ID of the profile to start.

#### Request Body
- **isNewCloudBrowser** (boolean) - Required - Set to true to start a new cloud browser session.
- **isHeadless** (boolean) - Required - Set to true to run the browser in headless mode.

### Request Example
```json
{
  "isNewCloudBrowser": true,
  "isHeadless": true
}
```

### Response
#### Success Response (200)
- **remoteOrbitaUrl** (string) - The URL to access the remote cloud browser session.

### Response Example
```json
{
  "remoteOrbitaUrl": "https://profile_id.orbita.gologin.com"
}
```
```

--------------------------------

### Install PyGoLogin SDK

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/README.md

Install the PyGoLogin SDK using pip. This command fetches and installs the latest version of the library and its dependencies.

```bash
pip install gologin
```

--------------------------------

### Python SDK Authentication Example

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Example of setting up headers for API requests using the Python SDK, including the Authorization token and a User-Agent.

```python
headers = {
    'Authorization': 'Bearer your_token',
    'User-Agent': 'gologin-api'
}
```

--------------------------------

### startRemote

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/01-gologin-class.md

Starts a profile on GoLogin cloud servers and waits for the remote debugging URL to become available.

```APIDOC
## startRemote

### Description
Starts the profile on GoLogin cloud servers and waits for the remote debugging URL to be ready.

### Method
`startRemote(self, delay_s: int = 3) -> dict`

### Parameters
#### Path Parameters
- **delay_s** (int) - Optional - Default: 3 - Delay in seconds between polling attempts

### Returns
`dict` — Response with keys 'status' ('success' or 'failure') and 'wsUrl' (WebSocket URL)

### Example
```python
result = gl.startRemote()
if result['status'] == 'success':
    ws_url = result['wsUrl']
```
```

--------------------------------

### Add Cookies to Profile and Start Browser

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/04-cookies-manager.md

Initializes GoLogin, defines cookies in standard format, and adds them to a profile before starting the browser. Ensure the profile ID and token are correctly set.

```python
from gologin import GoLogin
from gologin.cookiesManager import CookiesManager

gl = GoLogin({
    "token": "your_token",
    "profile_id": "your_profile_id"
})

cookies = [
    {
        "name": "user_session",
        "value": "session_token_value",
        "domain": "example.com",
        "path": "/",
        "expirationDate": 1719161018,
        "secure": True,
        "httpOnly": True,
        "sameSite": "lax"
    }
]

# Add to profile before starting
gl.addCookiesToProfile("profile_id", cookies)

# Start browser with cookies
gl.start()
```

--------------------------------

### Start Cloud Browser Session

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Starts a browser profile on GoLogin cloud servers. Returns the remote Orbita URL if successful. The `delay_s` parameter can be used to set a startup delay.

```Python
result = gl.startRemote(delay_s=3)
if result['status'] == 'success':
    ws_url = result['wsUrl']
```

--------------------------------

### Scrape with Fingerprint Refresh

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

This example demonstrates how to create a random fingerprint profile, start a browser session, and periodically refresh the fingerprint while scraping a website. It includes profile creation, browser automation with Selenium, and profile deletion.

```python
from gologin import GoLogin
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager
import time

# Create profile
gl = GoLogin({"token": "your_token"})
profile = gl.createProfileRandomFingerprint({
    "os": "lin",
    "name": "Scraper Bot"
})
profile_id = profile['id']

try:
    # Refresh fingerprint every 10 requests
    for i in range(5):
        gl.setProfileId(profile_id)
        
        if i % 10 == 0:
            gl.refreshProfilesFingerprint([profile_id])
            print(f"Refreshed fingerprint")
        
        # Start browser
        debugger_address = gl.start()
        
        # Set up Selenium
        options = webdriver.ChromeOptions()
        options.add_experimental_option("debuggerAddress", debugger_address)
        service = Service(ChromeDriverManager(
            driver_version=gl.get_chromium_version()
        ).install())
        driver = webdriver.Chrome(service=service, options=options)
        
        # Scrape
        driver.get("https://example.com")
        print(f"Request {i}: {driver.title}")
        
        driver.quit()
        gl.stop()
        
        time.sleep(1)

finally:
    gl.delete(profile_id)
    print("Profile deleted")
```

--------------------------------

### Low-Level API: HTTP Client

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/README.md

Access the low-level API for direct HTTP requests to the GoLogin API. This example demonstrates making a GET request to retrieve browser information.

```python
from gologin.http_client import make_request
response = make_request('GET', 'https://api.gologin.com/browser/v2', headers={...})
```

--------------------------------

### Manual GoLogin Initialization and Cleanup

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

Shows the equivalent of the context manager pattern using a try-finally block for manual initialization, starting the browser, and ensuring cleanup with gl.stop().

```python
gl = GoLogin({
    "token": "token",
    "profile_id": "profile_id"
})
try:
    ws_url = gl.start()
    # ... use browser ...
finally:
    gl.stop()
```

--------------------------------

### Start Remote Browser Session

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/01-gologin-class.md

Starts the profile on GoLogin cloud servers and waits for the remote debugging URL to be ready. It polls periodically based on the specified delay. Useful for running browser instances in the cloud.

```python
def startRemote(self, delay_s: int = 3) -> dict
```

```python
result = gl.startRemote()
if result['status'] == 'success':
    ws_url = result['wsUrl']
```

--------------------------------

### Check PyGoLogin Version

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/INDEX.md

Print the installed version of the PyGoLogin library. This is useful for verifying the installation and checking compatibility.

```python
from gologin import GoLogin
print(GoLogin.__version__)
```

--------------------------------

### Get Help on GoLogin Class

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/INDEX.md

Use the built-in help() function to get detailed information about the GoLogin class. This is useful for understanding its methods, attributes, and usage.

```python
from gologin import GoLogin
help(GoLogin)
```

--------------------------------

### Configure GoLogin with Browser Command-Line Flags

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

Initializes GoLogin with specific browser command-line flags. This example demonstrates setting headless mode, disabling GPU, and disabling sync.

```python
gl = GoLogin({
    "token": "token",
    "profile_id": "profile_id",
    "extra_params": [
        "--headless",
        "--disable-gpu",
        "--disable-sync"
    ]
})
```

--------------------------------

### Example Custom Browser Profile Creation

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/02-types.md

Demonstrates creating a profile with custom options, including navigator properties and proxy settings. Use this to configure detailed browser fingerprints.

```python
options = {
    "name": "Custom Windows Profile",
    "os": "win",
    "navigator": {
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)வுகளை",
        "resolution": "1920x1080",
        "language": "en-US",
        "platform": "Win32",
        "hardwareConcurrency": 8,
        "deviceMemory": 8,
        "maxTouchPoints": 0
    },
    "proxy": {
        "mode": "socks5",
        "host": "proxy.example.com",
        "port": 1080,
        "username": "user",
        "password": "pass"
    },
    "canvas": {"mode": "noise"},
    "webRTC": {"mode": "public", "enabled": True}
}
profile_id = gl.createProfileWithCustomParams(options)
```

--------------------------------

### Load Extensions in a GoLogin Profile

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/05-extensions-manager.md

Demonstrates how to initialize GoLogin, create an ExtensionsManager, and load extensions into a profile. It includes examples for automatically managed extensions and manual downloads of custom user extensions.

```python
from gologin import GoLogin
from gologin.extensionsManager import ExtensionsManager

gl = GoLogin({
    "token": "your_token",
    "profile_id": "your_profile_id"
})

# The profile already has extension IDs configured
# This happens automatically in loadExtensions()

manager = ExtensionsManager()

# Manual download if needed
version = manager.downloadExt("cjpalhdlnbpafiamejdnhcphjbkeiagm")
print(f"Downloaded uBlock Origin v{version}")

# Custom extensions
manager.downloadUserChromeExt(
    profile_id="your_profile_id",
    extensions_to_download=["my_custom_ext"],
    access_token="your_token"
)

# Start the browser with extensions loaded
ws_url = gl.start()
```

--------------------------------

### download_and_install(major_version)

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/03-browser-manager.md

Downloads and installs the Orbita browser for the specified Chromium version. This method handles platform-specific archives and uses file-level locking to prevent concurrent downloads.

```APIDOC
## download_and_install(major_version)

### Description
Downloads and installs the Orbita browser for the specified Chromium version. Uses platform-specific download URLs and implements file-level locking to prevent concurrent downloads of the same version.

### Method
download_and_install

### Parameters
#### Path Parameters
- **major_version** (int) - Required - Chromium major version to download

### Download URLs
- **Linux**: `https://orbita-browser-linux.gologin.com/orbita-browser-latest-{version}.tar.gz`
- **macOS (Intel)**: `https://orbita-browser-mac.gologin.com/orbita-browser-latest-{version}.tar.gz`
- **macOS (ARM/M-series)**: `https://orbita-browser-mac-arm.gologin.com/orbita-browser-latest-{version}.tar.gz`
- **Windows**: `https://orbita-browser-windows.gologin.com/orbita-browser-latest-{version}.zip`

### Behavior
1. Acquires an exclusive lock at `~/.gologin/browser/orbita-download-lock-{version}.lock`
2. Checks if version is already installed; returns immediately if found
3. Downloads the appropriate archive (tar.gz for Unix, zip for Windows)
4. Extracts to `~/.gologin/browser/orbita-browser-{version}/`
5. Releases the lock
6. Waits up to 300 seconds for another process's lock to release before proceeding

### Raises
- `requests.HTTPError` — If download fails
- `subprocess.CalledProcessError` — If extraction fails

### Request Example
```python
manager = BrowserManager()
manager.download_and_install(132)
executable = manager.get_orbita_path(132)
```
```

--------------------------------

### Use GoLogin with Context Manager

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

Initializes GoLogin using a context manager for automatic cleanup. The browser is started, used, and then automatically stopped upon exiting the 'with' block.

```python
with GoLogin({
    "token": "token",
    "profile_id": "profile_id"
}) as gl:
    ws_url = gl.start()
    # ... use browser ...
    # gl.stop() is called automatically on exit
```

--------------------------------

### Get All Profiles

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Lists all available profiles for the authenticated user.

```APIDOC
## GET /browser/v2

### Description
Lists all profiles for the authenticated user.

### Method
GET

### Endpoint
`/browser/v2`

### Response
#### Success Response (200)
- **id** (string) - Profile ID
- **name** (string) - Profile Name
- **os** (string) - Operating System type

### Response Example
```json
[
  {
    "id": "profile_id_1",
    "name": "Profile 1",
    "os": "lin"
  },
  {
    "id": "profile_id_2",
    "name": "Profile 2",
    "os": "win"
  }
]
```
```

--------------------------------

### Download and Install Orbita Browser

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/03-browser-manager.md

Downloads and installs the Orbita browser for a given Chromium major version. This method handles platform-specific archives and uses file locking to prevent concurrent downloads.

```python
manager = BrowserManager()
manager.download_and_install(132)
executable = manager.get_orbita_path(132)
```

--------------------------------

### Get Help on Types

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/INDEX.md

Access help documentation for custom types defined within the library, like CreateCustomBrowserOptions. This is essential for correctly defining browser configurations.

```python
from gologin.golgoin_types import CreateCustomBrowserOptions
help(CreateCustomBrowserOptions)
```

--------------------------------

### Time Format Conversion Example

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/04-cookies-manager.md

Demonstrates the conversion between Unix timestamps and Chrome's Windows FILETIME format for cookie expiration and access times.

```python
import time
unix_time = time.time()  # Current Unix timestamp
chrome_time = (unix_time + 11644473600) * 10_000_000
unix_time_back = (chrome_time / 10_000_000) - 11644473600
```

--------------------------------

### Integrate GoLogin with Puppeteer (Pyppeteer, Async)

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

Connect GoLogin with Pyppeteer for asynchronous browser automation. Start the browser using GoLogin, then establish a WebSocket connection to the debugger URL using Pyppeteer's `connect` method. Ensure proper cleanup of browser and GoLogin resources.

```python
from gologin import GoLogin
import asyncio

async def main():
    gl = GoLogin({
        "token": "your_token",
        "profile_id": "your_profile_id"
    })
    
    debugger_url = gl.start()
    
    import pyppeteer
    
    browser = await pyppeteer.connect(
        browserWSEndpoint=f"ws://{debugger_url}"
    )
    
    page = await browser.newPage()
    await page.goto("https://example.com")
    title = await page.title()
    print(title)
    
    await browser.close()
    gl.stop()

asyncio.run(main())
```

--------------------------------

### Configure GoLogin with Optional Cookie Options

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

Manage cookie synchronization by enabling or disabling uploading cookies to the server on profile stop and writing cookies from the server on profile start.

```python
gl = GoLogin({
    "token": "token",
    "profile_id": "profile_id",
    "uploadCookiesToServer": True,  # Save cookies on stop
    "writeCookiesFromServer": True  # Load cookies on start
})
```

--------------------------------

### Get All Profiles (Python SDK)

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Lists all available profiles for the authenticated user. This is useful for managing multiple browser profiles.

```python
all_profiles = gl.profiles()
```

--------------------------------

### Start Headless Browser Session

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

Initiate a browser session in headless mode. This is useful for automated tasks where a visible browser window is not required. Ensure the '--headless' extra parameter is included.

```python
from gologin import GoLogin

gl = GoLogin({
    "token": "your_token",
    "profile_id": "your_profile_id",
    "extra_params": ["--headless"]  # Run headless
})

ws_url = gl.start()
```

--------------------------------

### Using the Module-Level make_request Function

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/06-http-client.md

Example of calling the module-level `make_request` function to fetch data from an API endpoint. This is a straightforward way to initiate HTTP requests.

```python
from gologin.http_client import make_request

response = make_request(
    'GET',
    'https://api.gologin.com/browser/v2',
    headers={'Authorization': 'Bearer token'}
)
```

--------------------------------

### GoLogin Context Manager

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/01-gologin-class.md

The GoLogin class supports the context manager protocol, enabling automatic management of the browser lifecycle. The browser is automatically started upon entering the context and stopped upon exiting.

```APIDOC
## Context Manager Support

### Description
The `GoLogin` class implements the context manager protocol (`__enter__` and `__exit__`), allowing automatic browser lifecycle management.

### Example
```python
with GoLogin({
    "token": "your_token",
    "profile_id": "your_profile_id"
}) as gl:
    ws_url = gl.start()
    # Browser is running
    # gl.stop() is called automatically on exit
```
```

--------------------------------

### Integrate GoLogin with Selenium

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

Connect GoLogin with Selenium by starting the browser via GoLogin and then configuring the Selenium WebDriver to connect to the debugger address. Ensure you have the correct Chromium version for compatibility. The driver and GoLogin instance should be cleaned up after use.

```python
from gologin import GoLogin
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

gl = GoLogin({
    "token": "your_token",
    "profile_id": "your_profile_id"
})

# Start browser
debugger_address = gl.start()

# Get Chromium version
chromium_version = gl.get_chromium_version()

# Set up Selenium driver
options = webdriver.ChromeOptions()
options.add_experimental_option("debuggerAddress", debugger_address)
service = Service(ChromeDriverManager(driver_version=chromium_version).install())

driver = webdriver.Chrome(service=service, options=options)

# Use driver
driver.get("https://example.com")
print(driver.title)

# Cleanup
driver.quit()
gl.stop()
```

--------------------------------

### Integrate GoLogin with Playwright (Async)

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

Use GoLogin with Playwright in an asynchronous context. Start the browser via GoLogin, then use Playwright's `connect_over_cdp` to connect to the debugger URL. Remember to close the browser and stop GoLogin when finished.

```python
from gologin import GoLogin
import asyncio

async def main():
    gl = GoLogin({
        "token": "your_token",
        "profile_id": "your_profile_id"
    })
    
    debugger_url = gl.start()
    
    from playwright.async_api import async_playwright
    
    async with async_playwright() as p:
        # Connect to existing browser
        browser = await p.chromium.connect_over_cdp(f"http://{debugger_url}")
        page = await browser.new_page()
        
        await page.goto("https://example.com")
        print(await page.title())
        
        await browser.close()
    
    gl.stop()

asyncio.run(main())
```

--------------------------------

### Get Profile Info (Python SDK)

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Retrieves the complete configuration for a specific profile, including fingerprinting, proxy, and browser settings. You can specify a profile ID or use the default.

```python
profile = gl.getProfile()
# or specify profile ID
profile = gl.getProfile(profile_id="other_profile_id")
```

--------------------------------

### Add Cookies to a Profile Before Starting

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

Pre-load cookies into a specific profile before launching the browser. This is useful for logging into websites automatically. The cookies must be provided as a list of dictionaries, each conforming to the expected cookie structure. The profile ID must be specified when adding cookies.

```python
from gologin import GoLogin

gl = GoLogin({
    "token": "your_token",
    "profile_id": "your_profile_id"
})

# Add cookies before starting
cookies = [
    {
        "name": "session_id",
        "value": "abc123",
        "domain": "example.com",
        "path": "/",
        "secure": True,
        "httpOnly": True
    }
]

gl.addCookiesToProfile("your_profile_id", cookies)

# Now start browser with cookies
gl.start()
# ... browser has cookies ...
gl.stop()
```

--------------------------------

### Initialize GoLogin with Extra Parameters

Source: https://github.com/gologinapp/pygologin/blob/main/README.md

Demonstrates initializing GoLogin with a token, profile ID, and additional browser launch parameters like headless mode and loading extensions.

```python
gl = GoLogin({
	"token": "your token",
	"profile_id": "your profile id",
    "extra_params": ["--headless", "--load-extentions=path/to/extension"]
	})
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

Enable detailed debug logging for the GoLogin SDK. This is helpful for troubleshooting issues during profile setup and browser startup. Set the 'debug' parameter to True.

```python
from gologin import GoLogin

gl = GoLogin({
    "token": "your_token",
    "profile_id": "your_profile_id",
    "debug": True  # Enable debug logging
})

gl.start()
# See detailed logs for profile setup, browser startup, etc.
```

--------------------------------

### Create Profile with Random Fingerprint (Python SDK)

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Creates a new profile with an automatically generated random fingerprint. This is a quick way to get a new, unique profile.

```python
profile = gl.createProfileRandomFingerprint({
    "os": "lin",
    "name": "Random Profile"
})
```

--------------------------------

### Get Orbita Executable Path

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/03-browser-manager.md

Retrieves the absolute path to the Orbita executable for a specified Chromium major version. If the browser is not cached, it will be automatically downloaded and installed.

```python
manager = BrowserManager()
executable = manager.get_orbita_path(132)
print(f"Orbita path: {executable}")
```

--------------------------------

### Handle GoLogin Errors Gracefully

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/11-quick-start.md

Implement error handling for potential issues like invalid profile IDs or network problems. Use a try-except block to catch exceptions during GoLogin initialization or session start.

```python
from gologin import GoLogin

try:
    gl = GoLogin({
        "token": "your_token",
        "profile_id": "invalid_profile_id"
    })
    ws_url = gl.start()
except Exception as e:
    print(f"Error: {e}")
    # Handle error - profile doesn't exist, token invalid, network error, etc.
```

--------------------------------

### Mid-Level API: Browser Manager

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/README.md

Utilize the mid-level API for advanced browser management. This example shows how to get the path for a specific Orbita browser version using the BrowserManager.

```python
from gologin.browserManager import BrowserManager
from gologin.extensionsManager import ExtensionsManager
from gologin.cookiesManager import CookiesManager

manager = BrowserManager()
path = manager.get_orbita_path(132)
```

--------------------------------

### GET Profile Information

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/06-http-client.md

Retrieves detailed profile information using a GET request to the API. Requires Authorization header.

```python
response = make_request(
    'GET',
    'https://api.gologin.com/browser/features/profile_id/info-for-run',
    headers={
        'Authorization': 'Bearer your_token',
        'User-Agent': 'gologin-api'
    }
)
profile = response.json()
# {
#   "id": "profile_id",
#   "name": "Profile Name",
#   "os": "lin",
#   "navigator": {...},
#   ...
# }
```

--------------------------------

### Initialize GoLogin with Required Options

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

Instantiate GoLogin with the mandatory token and profile_id. Ensure your API token and profile ID are correctly obtained from the GoLogin platform.

```python
from gologin import GoLogin

gl = GoLogin({
    "token": "your_api_token",
    "profile_id": "your_profile_id"
})
```

--------------------------------

### Initialize GoLogin Instance

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/01-gologin-class.md

Instantiate the GoLogin class with essential parameters like API token and profile ID. Optional parameters can configure browser behavior, temporary directories, and network settings.

```python
from gologin import GoLogin

gl = GoLogin({
    "token": "your_api_token",
    "profile_id": "your_profile_id",
    "extra_params": ["--headless"],
    "uploadCookiesToServer": True
})
```

--------------------------------

### Initialize GoLogin with Placeholder Token (Raises Exception)

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

Demonstrates an invalid GoLogin initialization where a placeholder token is used, which will raise an Exception.

```python
# Raises Exception: Token is required
gl = GoLogin({
    "token": "Your token",  # Placeholder value
    "profile_id": "profile_id"
})
```

--------------------------------

### Configure GoLogin with Cloud Browser Options

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

Configure settings for cloud-based browsers, including enabling headless mode and selecting the cloud browser version.

```python
gl = GoLogin({
    "token": "token",
    "profile_id": "profile_id",
    "is_cloud_headless": True,   # Run headless in cloud
    "is_new_cloud_browser": True # Use new version
})
```

--------------------------------

### BrowserManager Constructor

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/03-browser-manager.md

Initializes the BrowserManager. This will create the browser cache directory at `~/.gologin/browser/` if it doesn't exist.

```APIDOC
## BrowserManager Constructor

### Description
Initializes the BrowserManager and creates the browser cache directory at `~/.gologin/browser/`.

### Method
__init__

### Parameters
None

### Request Example
```python
from gologin.browserManager import BrowserManager

manager = BrowserManager()
```
```

--------------------------------

### addCookiesToProfile

Source: https://github.com/gologinapp/pygologin/blob/main/README.md

Allows you to pass cookies to a profile. The browser will import these cookies before starting.

```APIDOC
## addCookiesToProfile

### Description
Passes cookies to a specified profile. The browser will import these cookies before starting.

### Method
`addCookiesToProfile(profile_id: str, cookies: list)`

### Parameters
#### Path Parameters
- **profile_id** (string) - Required - The ID of the profile to which cookies will be added.

#### Request Body
- **cookies** (list) - Required - A list of cookie objects. Each object should have at least 'name' and 'value' fields. Optional fields include 'domain', 'path', 'expirationDate', 'httpOnly', 'secure', and 'sameSite'.

### Request Example
```python
gl.addCookiesToProfile("profileId", [
    {
        "name": "session_id",
        "value": "abc123",
        "domain": "example.com",
        "path": "/",
        "expirationDate": 1719161018.307793,
        "httpOnly": True,
        "secure": True
    },
    {
        "name": "user_preferences",
        "value": "dark_mode",
        "domain": "example.com",
        "path": "/settings",
        "sameSite": "lax"
    }
])
```
```

--------------------------------

### Geolocation Information

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/INDEX.md

Endpoint to get the user's public IP address and geolocation.

```APIDOC
## GET /geo.myip.link/json

### Description
Retrieves the public IP address and geolocation information.

### Method
GET

### Endpoint
/geo.myip.link/json

### Response
#### Success Response (200)
- **ip** (string) - The public IP address.
- **country** (string) - The country of the IP address.
- **city** (string) - The city of the IP address.

### Response Example
{
  "ip": "192.0.2.1",
  "country": "Exampleland",
  "city": "Exampleville"
}
```

--------------------------------

### Get Default Cookies File Path

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/04-cookies-manager.md

Returns the standard path to the cookies database for the profile.

```python
path = manager.get_cookies_file_path()
print(path)  # /tmp/gologin_profile_id/Network/Cookies
```

--------------------------------

### ExtensionsManager Constructor

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/05-extensions-manager.md

Initializes the ExtensionsManager, setting up the extensions cache directory at `~/.gologin/extensions/`.

```APIDOC
## ExtensionsManager Constructor

### Description
Initializes the ExtensionsManager. Sets up the extensions cache directory at `~/.gologin/extensions/`.

### Method
```python
def __init__(self) -> ExtensionsManager
```

### Example
```python
manager = ExtensionsManager()
```
```

--------------------------------

### Stop Browser Session

Source: https://github.com/gologinapp/pygologin/blob/main/README.md

Stops the browser, saves the profile, and uploads it to storage. This should be called after starting a session.

```python
gl = GoLogin({
	"token": "your token",
    "profile_id": "some_profile_id"
	})

wsUrl = gl.start()
gl.stop()
```

--------------------------------

### Get Random Fingerprint

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Retrieves a random fingerprint for a specified operating system without creating a profile.

```APIDOC
## GET /browser/fingerprint

### Description
Gets a random fingerprint for the specified OS without creating a profile.

### Method
GET

### Endpoint
`/browser/fingerprint`

### Parameters
#### Query Parameters
- **os** (string) - Required - OS type: `lin`, `mac`, `win`, `android`

### Response
#### Success Response (200)
- **navigator** (object) - Navigator properties
- **canvas** (object) - Canvas fingerprint details
- **webRTC** (object) - WebRTC fingerprint details

### Response Example
```json
{
  "navigator": {
    "userAgent": "Mozilla/5.0...",
    "resolution": "1920x1080",
    "language": "en-US",
    "platform": "Linux x86_64",
    "hardwareConcurrency": 8,
    "deviceMemory": 8,
    "maxTouchPoints": 0
  },
  "canvas": {},
  "webRTC": {}
}
```
```

--------------------------------

### GET Geolocation and Timezone Data

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/06-http-client.md

Fetches geolocation and timezone information from geo.myip.link. Handles potential ProxyCheckFailedError.

```python
try:
    response = make_request('GET', 'https://geo.myip.link/json')
    geo_data = response.json()
    # {
    #   "ip": "1.2.3.4",
    #   "country": "US",
    #   "timezone": "America/New_York",
    #   "latitude": 40.7128,
    #   "longitude": -74.0060,
    #   ...
    # }
except ProxyCheckFailedError:
    print("Cannot determine geolocation - proxy may be down")
```

--------------------------------

### Initialize ExtensionsManager

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/05-extensions-manager.md

Initializes the ExtensionsManager. This sets up the necessary cache directories for extensions.

```python
manager = ExtensionsManager()
```

--------------------------------

### Add Cookies

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Adds cookies to a specified profile before the browser starts. Cookies should be provided in a JSON array format.

```APIDOC
## POST /browser/{profile_id}/cookies?fromUser=true

### Description
Adds cookies to a profile before browser startup.

### Method
POST

### Endpoint
/browser/{profile_id}/cookies

### Parameters
#### Path Parameters
- **profile_id** (string) - Required - The ID of the profile to add cookies to.

#### Query Parameters
- **fromUser** (boolean) - Required - Set to true to indicate cookies are from the user.

#### Request Body
- (array of cookie objects)
  - **name** (string) - Required - The name of the cookie.
  - **value** (string) - Required - The value of the cookie.
  - **domain** (string) - Optional - The domain the cookie is associated with.
  - **path** (string) - Optional - The path the cookie is valid for.
  - **expirationDate** (integer) - Optional - The expiration date of the cookie as a Unix timestamp.
  - **httpOnly** (boolean) - Optional - Whether the cookie is HTTP-only.
  - **secure** (boolean) - Optional - Whether the cookie is secure.
  - **sameSite** (string) - Optional - The SameSite attribute of the cookie (e.g., "lax", "strict", "none").

### Request Example
```json
[
  {
    "name": "session_id",
    "value": "abc123",
    "domain": "example.com",
    "path": "/",
    "expirationDate": 1719161018,
    "httpOnly": true,
    "secure": true,
    "sameSite": "lax"
  }
]
```

### Response
#### Success Response (200)
- (HTTP status code indicates success)

```

--------------------------------

### GoLogin Constructor

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/01-gologin-class.md

Initializes a GoLogin instance with API token, profile ID, and optional browser configuration. It supports various parameters to customize browser behavior and profile management.

```APIDOC
## GoLogin Constructor

### Description
Initializes a GoLogin instance with the required API token and profile ID, plus optional browser configuration.

### Parameters
- **token** (str) - Required - GoLogin API token from your account
- **profile_id** (str) - Required - The ID of the profile to manage (NOT the profile name)
- **tmpdir** (str) - Optional - Temporary directory for profile data storage (Defaults to `tempfile.gettempdir()`)
- **address** (str) - Optional - Local address to bind the browser debugger (Defaults to `'127.0.0.1'`)
- **port** (int) - Optional - Port for the browser's remote debugging protocol (Defaults to Random 1000-35000)
- **extra_params** (list[str]) - Optional - Additional browser flags (e.g., `['--headless']`) (Defaults to `[]`)
- **local** (bool) - Optional - If True, profile is not uploaded to server after stopping (Defaults to `False`)
- **spawn_browser** (bool) - Optional - Whether to automatically spawn the browser process (Defaults to `True`)
- **uploadCookiesToServer** (bool) - Optional - Upload cookies to server when profile stops (Defaults to `False`)
- **writeCookiesFromServer** (bool) - Optional - Import predefined cookies from server on start (Defaults to `True`)
- **restore_last_session** (bool) - Optional - Restore the previous browser session (Defaults to `True`)
- **executable_path** (str) - Optional - Path to Orbita executable (auto-downloaded if empty) (Defaults to `''`)
- **is_cloud_headless** (bool) - Optional - Enable headless mode for cloud browser (Defaults to `True`)
- **is_new_cloud_browser** (bool) - Optional - Use new cloud browser version (Defaults to `True`)
- **credentials_enable_service** (bool) - Optional - Enable password manager service (Defaults to `None`)
- **cleaningLocalCookies** (bool) - Optional - Clear local cookies when sanitizing profile (Defaults to `False`)
- **debug** (bool) - Optional - Enable debug logging (Defaults to `False`)

### Exceptions
- `Exception`: Raised if `token` is `'Your token'` or `profile_id` is `'Your profile id'` (placeholder values)

### Example
```python
from gologin import GoLogin

gl = GoLogin({
    "token": "your_api_token",
    "profile_id": "your_profile_id",
    "extra_params": ["--headless"],
    "uploadCookiesToServer": True
})
```
```

--------------------------------

### Add Cookies to Profile

Source: https://github.com/gologinapp/pygologin/blob/main/README.md

Pass cookies to a profile. The browser will import them before starting. Ensure the profile ID is correct.

```python
gl = GoLogin({
	"token": "your token",
	})

gl.addCookiesToProfile("profileId", [
    {
        "name": "session_id",
        "value": "abc123",
        "domain": "example.com",
        "path": "/",
        "expirationDate": 1719161018.307793,
        "httpOnly": True,
        "secure": True
    },
    {
        "name": "user_preferences",
        "value": "dark_mode",
        "domain": "example.com",
        "path": "/settings",
        "sameSite": "lax"
    }
])
```

--------------------------------

### Configure GoLogin with Optional Browser Settings

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/09-configuration.md

Customize browser behavior by specifying temporary directory, remote debugging address and port, additional command-line flags, Orbita executable path, and local/spawn settings.

```python
gl = GoLogin({
    "token": "token",
    "profile_id": "profile_id",
    "tmpdir": "/custom/tmp",
    "address": "192.168.1.100",
    "port": 9222,
    "extra_params": ["--headless", "--disable-gpu"],
    "executable_path": "/home/user/.gologin/browser/orbita-browser-132/chrome",
    "local": False,
    "spawn_browser": True
})
```

--------------------------------

### Get Profile Info

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Retrieves the complete configuration for a specific profile, including fingerprinting, proxy, and browser settings.

```APIDOC
## GET /browser/features/{profile_id}/info-for-run

### Description
Retrieves complete profile configuration including fingerprinting, proxy, cookies, and browser settings.

### Method
GET

### Endpoint
`/browser/features/{profile_id}/info-for-run`

### Parameters
#### Path Parameters
- **profile_id** (string) - Required - Profile ID

### Response
#### Success Response (200)
- **id** (string) - Profile ID
- **name** (string) - Profile Name
- **os** (string) - Operating System type
- **navigator** (object) - Navigator properties
- **proxy** (object) - Proxy configuration
- **timezone** (object) - Timezone settings
- **geolocation** (object) - Geolocation settings
- **cookies** (object) - Cookie settings
- **chromeExtensions** (array) - Chrome extensions list
- **userChromeExtensions** (array) - User Chrome extensions list
- **s3Path** (string) - S3 path for profile data
- **storageInfo** (object) - Storage information

### Response Example
```json
{
  "id": "profile_id",
  "name": "Profile Name",
  "os": "lin",
  "navigator": {
    "userAgent": "Mozilla/5.0...",
    "resolution": "1920x1080",
    "language": "en-US",
    "platform": "Linux x86_64",
    "hardwareConcurrency": 8,
    "deviceMemory": 8,
    "maxTouchPoints": 0
  },
  "proxy": {
    "mode": "http",
    "host": "proxy.example.com",
    "port": 8080,
    "username": "user",
    "password": "pass"
  },
  "timezone": {
    "enabled": true,
    "timezone": "America/New_York"
  },
  "geolocation": {
    "mode": "allow",
    "latitude": 40.7128,
    "longitude": -74.0060
  },
  "cookies": {
    "userCookies": true,
    "cookies": []
  },
  "chromeExtensions": [],
  "userChromeExtensions": [],
  "s3Path": "...",
  "storageInfo": {
    "isNewProfile": false
  }
}
```
```

--------------------------------

### Create Profile (Python SDK)

Source: https://github.com/gologinapp/pygologin/blob/main/_autodocs/10-gologin-api-reference.md

Creates a new browser profile with basic specified options like name and OS. The API returns the ID of the newly created profile.

```python
profile_id = gl.create({
    "name": "My Profile",
    "os": "lin"
})
```