Browser SDK

A browser SDK based on Chromium (DIC) that provides fingerprint management and process control functions, suitable for browser automation and anti-detection scenarios.

🚀 Get started quickly

Installation

1. Unzip dic-browser-sdk.zip in the project root (or anywhere else you like) and modify the package.json:

  "dependencies": {
    "dic-browser-sdk": "file:./dic-browser-sdk"
  }

2. Dependencies required to install the SDK (executed in the root directory of your project)

npm install

3. Done

basic use

const { createSDK } = require('dic-browser-sdk');
const path = require('path');

async function main() {
  // 1. 创建SDK实例
  const sdk = createSDK();

  // 2. 初始化SDK
  await sdk.initialize({
    baseDir: path.join(__dirname, 'data'),
    chromiumPath: '/path/to/chromium.exe', // 指定浏览器内核路径
    logLevel: 'info'
  });

  // 3. 创建指纹配置
  const { instanceId, fingerprintConfig } = await sdk.createFingerprint({
    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
    proxy: {
      host: 'proxy.example.com',
      port: 8080,
      type: 'HTTP',
      username: 'user',
      password: 'pass'
    },
    fingerprint: {
      canvas: { type: 'noise' },
      rtc: { type: 'disable' }
    }
  });

  // 4. 启动浏览器实例
  const { id, wsUrl } = await sdk.launch({
    instanceId: instanceId,
    fingerprintConfig: fingerprintConfig.config
  });

  console.log(`浏览器启动成功: ${id}`);
  console.log(`WebSocket URL: ${wsUrl}`);

  // 5. 关闭实例
  await sdk.close(id);

  // 6. 清理资源
  await sdk.cleanup();
}

main().catch(console.error);

📚 Key features:

1. SDK initialization

await sdk.initialize({
  baseDir: './browser-data',           // 数据目录
  chromiumPath: '/path/to/browser',    // 浏览器路径
  logLevel: 'info'                     // 日志级别
});

2. Fingerprint configuration

Basic fingerprint configuration

const fingerprint = await sdk.createFingerprint({
  userAgent: 'Mozilla/5.0 ...',
  iconHintText: '1',
  proxy: {
    host: 'proxy.com',
    port: 8080,
    type: 'HTTP',
    username: 'user',
    password: 'pass',
	...,
    ipInfo: {
      timeZone: 'Asia/Shanghai',
      ip: '255.23.41.3',
      ...
    }
  }
});

Advanced fingerprint configuration

const fingerprint = await sdk.createFingerprint({
  userAgent: 'Mozilla/5.0 ...',
  fingerprint: {
    canvas: { type: 'noise' },          // Canvas指纹
    rtc: { type: 'disable' },           // WebRTC
    audio: { type: 'noise' },           // 音频指纹
    font: { type: 'auto' },             // 字体
    deviceMemory: {
      type: 'custom',
      value: '8'
    },
    hardwareConcurrency: {
      type: 'custom',
      value: '8'
    },
    ratio: {
      type: 'custom',
      value: { width: '1920', height: '1080' }
    }
  },
  advancedConfig: {
    restoreLast: 'enable',              // 恢复上次会话
  },
  accounts: [{                          // 账号信息
    platform: 'example.com',
    username: 'user123',
    password: 'pass123'
  }]
});

3. Browser instance management

Start the instance

const { id, wsUrl } = await sdk.launch({
  instanceId: 'my-instance',           // 可选，不提供则自动生成
  fingerprintConfig: fingerprint.config
});

Instance status query

// 获取单个实例信息
const instance = sdk.getInstance('instance-id');
console.log(instance.status); // running, stopped, error 等

// 获取所有实例
const allInstances = sdk.getAllInstances();

// 检查实例是否存活
const isAlive = sdk.isInstanceAlive('instance-id');

// 获取SDK状态
const status = sdk.getStatus();
console.log(status.totalInstances, status.runningInstances);

Close the instance

// 普通关闭
await sdk.close('instance-id');

🔧 Advanced usage

Agent configuration

// HTTP代理
proxy: {
  host: 'proxy.com',
  port: 8080,
  type: 'HTTP',
  username: 'user',
  password: 'pass'
}

// SOCKS5代理
proxy: {
  host: 'socks.com',
  port: 1080,
  type: 'SOCKS5',
  username: 'user',
  password: 'pass'
}

Event monitoring

sdk.on('instanceLaunched', (instance) => {
  console.log('实例启动:', instance.id);
});

sdk.on('instanceClosed', ({ instanceId }) => {
  console.log('实例关闭:', instanceId);
});

sdk.on('processExit', (data) => {
  console.log('进程退出:', data.pid);
});

Batch management

// 启动多个实例
const instances = [];
for (let i = 0; i < 5;="" i++)="" {="" const="" fingerprint="await" sdk.createfingerprint({="" useragent:="" `useragent-${i}`,="" ...="" 其他配置="" });="" const="" instance="await" sdk.launch({="" fingerprintconfig:="" fingerprint.config="" });="" instances.push(instance);="" }="" 批量关闭="" for="" (const="" instance="" of="" instances)="" {="" await="" sdk.close(instance.id);="">

🛠️ You need to prepare

• Node.js >= 18.0.0
• Windows/macOS
• Chromium kernel available

📖 Error handling

try {
  await sdk.launch(options);
} catch (error) {
  console.error('启动失败:', error.message);
  console.error('错误码:', error.code);
}

Common error code reference: ERROR_CODES.md
Fingerprint type definition: TYPE.md

🔍 Debugging.

Enable verbose logs:

await sdk.initialize({
  baseDir: './data',
  logLevel: 'debug'  // error, warn, info, debug
});

📄 Permit.

MIT License