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.

1、 Get started quickly

1.1 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

1.2 basic use

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

async function main() {
  // 1. create SDK instance
  const sdk = createSDK();

  // 2. init SDK
  await sdk.initialize({
    baseDir: path.join(__dirname, 'data'),
    chromiumPath: '/path/to/chromium.exe',
    logLevel: 'info'
  });

  // 3. create finger config
  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. luanch instance
  const { id, wsUrl } = await sdk.launch({
    instanceId: instanceId,
    fingerprintConfig: fingerprintConfig.config
  });

  console.log(`launch success: ${id}`);
  console.log(`WebSocket URL: ${wsUrl}`);

  // 5. close instance
  await sdk.close(id);

  // 6. clean resource
  await sdk.cleanup();
}

main().catch(console.error);

2、 Key features:

2.1 SDK initialization

await sdk.initialize({
  baseDir: './browser-data',           // data directory
  chromiumPath: '/path/to/browser',    // browser path
  logLevel: 'info'                     // log level
});

2.2 Fingerprint configuration

2.2.1 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',
      ...
    }
  }
});

2.2.2 Advanced fingerprint configuration

const fingerprint = await sdk.createFingerprint({
  userAgent: 'Mozilla/5.0 ...',
  fingerprint: {
    canvas: { type: 'noise' },          // Canvas
    rtc: { type: 'disable' },           // WebRTC
    audio: { type: 'noise' },           // audio
    font: { type: 'auto' },             // font
    deviceMemory: {
      type: 'custom',
      value: '8'
    },
    hardwareConcurrency: {
      type: 'custom',
      value: '8'
    },
    ratio: {
      type: 'custom',
      value: { width: '1920', height: '1080' }
    }
  },
  advancedConfig: {
    restoreLast: 'enable',              // restore last
  },
  accounts: [{                          // account
    platform: 'example.com',
    username: 'user123',
    password: 'pass123'
  }]
});

2.3 Browser instance management

2.3.1 Start the instance

const { id, wsUrl } = await sdk.launch({
  instanceId: 'my-instance',           // options
  fingerprintConfig: fingerprint.config
});

2.3.2 Instance status query

const instance = sdk.getInstance('instance-id');
console.log(instance.status); // running, stopped, error

// get all instance
const allInstances = sdk.getAllInstances();

// check instance is live
const isAlive = sdk.isInstanceAlive('instance-id');

// get SDK status
const status = sdk.getStatus();
console.log(status.totalInstances, status.runningInstances);

2.3.3 Close the instance

// clase
await sdk.close('instance-id');

3、 Advanced usage

3.1 Agent configuration

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

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

3.2 Event monitoring

sdk.on('instanceLaunched', (instance) => {
  console.log('launch:', instance.id);
});

sdk.on('instanceClosed', ({ instanceId }) => {
  console.log('close:', instanceId);
});

sdk.on('processExit', (data) => {
  console.log('quit:', data.pid);
});

3.3 Batch management

// luanch multi instance
const instances = [];
for (let i = 0; i < 5;="" i++)="" {="" const="" fingerprint="await" sdk.createfingerprint({="" useragent:="" `useragent-${i}`,="" ...="" other config="" });="" const="" instance="await" sdk.launch({="" fingerprintconfig:="" fingerprint.config="" });="" instances.push(instance);="" }="" batch close="" for="" (const="" instance="" of="" instances)="" {="" await="" sdk.close(instance.id);="">

4、 You need to prepare

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

5、 Error handling

try {
  await sdk.launch(options);
} catch (error) {
  console.error('luanch fail:', error.message);
  console.error('error code:', error.code);
}

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

6、 Debugging.

Enable verbose logs:

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

7、 Permit.

MIT License