Content
# BroSDK Browser Control SDK
[English](README_EN.md) |
BroSDK encapsulates multiple versions of browser kernels such as Chrome and Firefox, adapts to operating systems like Windows, macOS, and Linux, and provides integrated proxy IP, cookie management, and session persistence capabilities.
This repository provides C/C++ APIs, header files, and platform dynamic libraries for creating independent browser environments, launching browser instances, maintaining Cookie/Storage states, reusing session contexts, and collaborating with CDP, Playwright, Puppeteer, or MCP Server for automation.
## Function Overview
- Create an independent browser environment and manage subsequent launches, updates, and destruction using environment IDs.
- Launch and close browser instances, obtain browser running states, and SDK information.
- Manage cookies, storage states, and session persistence, enabling the reuse of login states and business contexts in the same environment.
- Associate environment IDs, account IPs, cookie/storage states with account, user, or task models in business systems.
- Integrate browser environment management, browser control, callbacks, and error code handling in C/C++ programs.
- Combine with CDP, Playwright, Puppeteer, or MCP Server to hand over browser tasks to scripts, testing systems, or AI Agents for execution.
## Core Functions
### Environment Management
BroSDK abstracts environments as its core. Each environment can save independent browser configurations, fingerprint parameters, cookie/storage states, and session contexts.
| API | Description |
|-----|-------------|
| `sdk_env_create` | Create browser environment configuration |
| `sdk_env_update` | Update environment parameters |
| `sdk_env_page` | Execute page-level operations |
| `sdk_env_destroy` | Destroy environment |
### Browser Control
Launch browser instances through SDK and close them after tasks are completed. Suitable for desktop clients, automation tasks, testing tasks, and background services.
| API | Description |
|-----|-------------|
| `sdk_browser_open` | Launch browser instance |
| `sdk_browser_close` | Close browser |
| `sdk_browser_info` | Get browser running state |
### Cookie and Session Persistence
SDK provides cookie persistence callbacks for business systems to save and restore browser session states. Upper-layer systems can bind login states, storage states, and environment IDs to their own user, store, customer, or task models.
| API | Description |
|-----|-------------|
| `sdk_register_cookies_storage_cb` | Register cookie persistence callback |
| `sdk_register_result_cb` | Register operation result callback |
### Authentication and Lifecycle
SDK supports runtime updates of authentication tokens and provides shutdown interfaces for long-running services or clients to handle authentication refreshes and resource releases.
| API | Description |
|-----|-------------|
| `sdk_token_update` | Update authentication token |
| `sdk_shutdown` | Securely shut down SDK |
### Tool Functions and Error Codes
All APIs return `int32_t` status codes, which can be judged as successful, errors, warnings, completions, and event states through tool functions.
| API | Description |
|-----|-------------|
| `sdk_info` | Get SDK information |
| `sdk_error_name` | Get error code name |
| `sdk_error_string` | Get error code description |
| `sdk_is_ok` | Determine if operation is successful |
| `sdk_is_error` | Determine if an error occurred |
| `sdk_is_warn` | Determine if it's a warning |
| `sdk_is_done` | Determine if operation is completed |
| `sdk_is_event` | Determine if it's an event |
## Applicable Scenarios
- **Multi-account Operation SaaS**: Maintain independent fingerprint environments, account IPs, cookies, and storage states for each business account.
- **ERP / CRM / Internal Systems**: Integrate browser environment capabilities into enterprise internal systems, open and manage account environments through a unified workstation.
- **Automation Testing and Monitoring**: Used for authorized testing, page inspections, account health checks, and process monitoring tasks.
- **AI Agent Browser Tasks**: Combine with MCP Server, CDP, Playwright, or Puppeteer to let AI Agents call SDK to open environments and execute browser tasks.
## Related Repositories and Module Relationships
BroSDK consists of multiple repositories. The current repository `brosdk` is the native SDK entrance, providing C/C++ header files, dynamic libraries, and basic calling methods; other repositories cover browser kernels, documentation, multi-language access, example projects, and AI Agent integration.
| Repository | Module | Description |
|------------|--------|-------------|
| [brosdk](https://github.com/browsersdk/brosdk) | Native SDK | C/C++ API, header files, and platform dynamic libraries |
| [brosdk-core](https://github.com/browsersdk/brosdk-core) | Browser Core | Browser kernel, version, and runtime dependencies |
| [brosdk-docs](https://github.com/browsersdk/brosdk-docs) | Documentation | SDK documentation, API instructions, and access guides |
| [brosdk-typescript](https://github.com/browsersdk/brosdk-typescript) | TypeScript SDK | Node.js, front-end toolchain, and automation script access |
| [brosdk-python](https://github.com/browsersdk/brosdk-python) | Python SDK | Python automation, testing, and AI workflow access |
| [brosdk-rust](https://github.com/browsersdk/brosdk-rust) | Rust SDK | Rust service, CLI, and high-performance task access |
| [brosdk-server-go](https://github.com/browsersdk/brosdk-server-go) | Go Server | Encapsulate BroSDK as server capability or internal HTTP API |
| [browser-demo](https://github.com/browsersdk/browser-demo) | Demo | Environment creation, browser launch, and session reuse examples |
| [browser-cpp-demo](https://github.com/browsersdk/browser-cpp-demo) | C++ Demo | C++ project linking and native SDK call examples |
| [brosdk-mcp](https://github.com/browsersdk/brosdk-mcp) | MCP Server | AI Agent calls browser environment capabilities through MCP |
| [chrome-devtools-mcp](https://github.com/browsersdk/chrome-devtools-mcp) | CDP MCP | Chrome DevTools Protocol-based MCP browser operation module |
Recommended reading order:
1. Read the current repository to understand BroSDK's native capabilities and API boundaries.
2. View [browser-demo](https://github.com/browsersdk/browser-demo) or [browser-cpp-demo](https://github.com/browsersdk/browser-cpp-demo) and run through the first browser environment.
3. Choose TypeScript, Python, Rust, or Go access modules according to the technical stack.
4. If you need to access AI Agent, view [brosdk-mcp](https://github.com/browsersdk/brosdk-mcp) and [chrome-devtools-mcp](https://github.com/browsersdk/chrome-devtools-mcp).
5. To confirm browser version and kernel support, view [brosdk-core](https://github.com/browsersdk/brosdk-core).
## Supported Platforms
BroSDK adapts to Windows, macOS, and Linux. The current repository already contains the following platform dynamic libraries:
| Platform | Dynamic Library |
|----------|------------------|
| Windows x64 | `windows/brosdk.dll` |
| macOS ARM64 | `arm64-osx/libbrosdk.dylib` |
## Supported Browser Kernels
Visit https://github.com/browsersdk/brosdk-core for browser kernel and version support.
## Quick Start
### C Language Call
```c
#include <stdio.h>
#include "brosdk.h"
int main() {
sdk_handle_t handle = NULL;
char *out_data = NULL;
size_t out_len = 0;
int32_t ret = sdk_init(&handle, NULL, 0, &out_data, &out_len);
if (!sdk_is_ok(ret)) {
printf("SDK initialization failed: %s - %s\n", sdk_error_name(ret), sdk_error_string(ret));
return ret;
}
printf("SDK initialization successful\n");
sdk_info(&out_data, &out_len);
printf("SDK Info: %.*s\n", (int)out_len, out_data);
sdk_free(out_data);
sdk_shutdown();
return 0;
}
```
### C++ Call
```cpp
#include "brosdk.h"
// After implementing the ISDK interface, you can call environment management, browser control, and callback capabilities in C++ projects.
```
## Compilation and Linking
### Windows
```bash
gcc -o app app.c -L./windows -lbrosdk
```
### macOS
```bash
gcc -o app app.c -L./arm64-osx -lbrosdk
```
## Directory Structure
```text
sdk/
├── brosdk.h # Header file
├── windows/ # Windows dynamic library
│ └── brosdk.dll
└── arm64-osx/ # macOS ARM64 dynamic library
└── libbrosdk.dylib
```
