GoLogin Node.js SDK

You can use the provided docker-compose.yml to set up a containerized environment for running GoLogin browser tests. The setup uses a node:18-bullseye base image and installs a comprehensive list of Linux dependencies required for browser automation (such as libnss3, libatk-bridge2.0-0, and libgbm1).

Key configuration details:

• Environment Variables: Set GL_API_TOKEN to your GoLogin API token.
• Ports: The container exposes port 9222 (typically used for remote debugging).
• Volumes: The current directory is mounted to /app, and a named volume node_modules_cache is used to persist node_modules.
• Execution: The default command updates the package manager, installs system dependencies, runs npm install, and finally executes npm run test:e2e.

version: '3.8'

services:
  gologin-browser:
    image: node:18-bullseye
    platform: linux/amd64
    container_name: gologin-browser
    working_dir: /app
    volumes:
      - .:/app
      - node_modules_cache:/app/node_modules
    environment:
      - GL_API_TOKEN=your_token_here
      - NODE_ENV=development
    ports:
      - "9222:9222"
    command: >
      sh -c "
        apt-get update &&
        apt-get install -y libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1 libxss1 libasound2 fonts-liberation libcups2 libxcomposite1 libxdamage1 libxrandr2 libxfixes3 libxtst6 libxi6 libx11-xcb1 libx11-6 libxcb1 libxext6 libxrender1 libcairo2 libglib2.0-0 libgtk-3-0 libgdk-pixbuf2.0-0 libpango-1.0-0 libpangocairo-1.0-0 libatk1.0-0 libcairo-gobject2 libgconf-2-4 libxshmfence1 libgl1-mesa-glx libgl1-mesa-dri libegl1-mesa libxau6 libxdmcp6 libappindicator3-1 xdg-utils &&
        npm install &&
        npm run test:e2e
      "
    networks:
      - gologin-network

volumes:
  node_modules_cache:

networks:
  gologin-network:
    driver: bridge

Add GoLogin Proxy

Add high-quality GoLogin proxies to a profile using a country code (e.g., 'us'). await GL.addGologinProxyToProfile(profileId, 'us')

Set Custom Proxy

Manually set a proxy for a profile using an object containing mode, host, port, username, and password. await GL.changeProfileProxy(profileId, { mode: 'http', host: '...', ... })

Add Cookies

Import cookies into a profile before starting the browser. The array should contain objects with name, value, domain, path, expirationDate, httpOnly, and secure fields.

Update User Agent

Keep user agents up to date across multiple profiles. await GL.updateUserAgentToLatestBrowser([profileId1, profileId2], 'workspaceId')

// Add GoLogin Proxy
await GL.addGologinProxyToProfile("profileId", "us");

// Add Custom Cookies
await GL.addCookiesToProfile("profileId", [
    {
        "name": "session_id",
        "value": "abc123",
        "domain": "example.com",
        "path": "/",
        "expirationDate": 1719161018.307793,
        "httpOnly": true,
        "secure": true
    }
]);

// Change to a specific proxy
await GL.changeProfileProxy("profileId", {
    "mode": "http",
    "host": "somehost.com",
    "port": 109,
    "username": "someusername",
    "password": "somepassword"
});

Use GologinApi or new GoLogin() to initialize the client. You must provide your API token.

Required Options:

• token (string): Your GoLogin API token.

Optional Options:

• profile_id (string): Specific profile ID. If not specified, one will be generated.
• executablePath (string): Path to the Orbita executable. Automatically downloaded if omitted.
• extra_params (string[]): Additional browser flags (e.g., --headless, --load-extensions=path/to/extension).
• uploadCookiesToServer (boolean): If true, uploads cookies to the server after the profile stops (default: false).
• writeCookesFromServer (boolean): If true, imports predefined cookies from the server (default: true).
• tmpdir (string): Absolute path for the user-data-dir. Defaults to a system temp folder.
• vncPort (integer): Port for the VNC server.

import { GologinApi } from 'gologin';

const GL = GologinApi({
  token: 'your token',
});

// Or using the constructor pattern
const GL = new GoLogin({
    token: 'your token',
    profile_id: 'profile id',
    extra_params: ["--headless"]
});

You can create profiles using either a random fingerprint or custom parameters.

Random Fingerprint: Use createProfileRandomFingerprint(name) to generate a new profile with a random fingerprint. Note: The documentation mentions passing OS ('lin', 'win', 'mac'), though the example shows only the name.

Custom Parameters: Use createProfileWithCustomParams(params) to define specific browser attributes like User Agent, resolution, language, and hardware specs. Refer to the official GoLogin API docs for the full parameter list.

// Create with random fingerprint
const profile = await GL.createProfileRandomFingerprint('some name');
const profileId = profile.id;

// Create with custom parameters
const profile = await GL.createProfileWithCustomParams({
    "os": "lin",
    "name": "some name",
    "navigator": {
        "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36",
        "resolution": "1920x1080",
        "language": "en-US",
        "platform": "Linux x86_64",
        "hardwareConcurrency": 8,
        "deviceMemory": 8,
        "maxTouchPoints": 0
    }
});
const profileId = profile.id;

The GoLoginOptions object allows fine-grained control over the browser environment, proxy settings, and session behavior.

Commonly used keys:

• token: Your GoLogin API token.
• profile_id: The ID of the profile to use.
• password: Profile password if required.
• executablePath: Path to a specific browser executable.
• args: Array of command-line arguments to pass to the browser.
• timezone: Object to spoof location, including timezone, country, city, ip, ll (latitude/longitude), accuracy, stateProv, and languages.
• isCloudHeadless: Boolean to run in cloud headless mode.
• proxyCheckTimeout / proxyCheckAttempts: Settings for validating proxies.

const options: GoLoginOptions = {
  token: 'YOUR_TOKEN',
  profile_id: 'PROFILE_ID',
  timezone: {
    timezone: 'America/New_York',
    country: 'US',
    city: 'New York',
    ll: [40.7128, -74.0060]
  },
  args: ['--disable-web-security']
};