references/smartbrowz-basics.md
# Catalyst SmartBrowz — Browser Automation & Document Generation Basics
Catalyst SmartBrowz is a cloud-based browser service that enables headless browser automation, visual document generation, and parallel browser operations. All remote browsers run securely in Catalyst's cloud environment.
---
## What is Catalyst SmartBrowz?
SmartBrowz provides 6 independent components in a unified platform:
1. **Headless** — Connect to remote Chrome/Firefox with Puppeteer, Playwright, or Selenium
2. **Browser Logic** — Serverless functions for browser automation (Java/Node.js)
3. **PDF & Screenshot** — Generate visual documents from webpages
4. **Templates** — Design and store templates for dynamic content
5. **Browser Grid** (Early Access) — Parallel headless browsers with auto-scaling
6. **Dataverse** — Data scraping APIs
**Current browser support:**
- **Headless & Browser Logic**: Chrome only
- **Browser Grid**: Chrome (v137.0.7151.55) and Firefox (v136.0.4)
---
## Component 1: Headless
Connect to a remote browser in Catalyst cloud environment using popular automation libraries.
### Supported Automation Libraries
- **Puppeteer** — Node.js library for Chrome DevTools Protocol
- **Playwright** — Cross-browser automation (connects via CDP)
- **Selenium** — WebDriver-based automation
### Setup Steps
1. **Console → SmartBrowz → Headless**
2. **Configure Remote Browser Options:**
- **Memory**: Select memory allocation for remote browser
- **Browser Version**: Chrome version (currently only Chrome supported)
3. **Copy Endpoints:**
- **CDP Endpoint** (for Puppeteer/Playwright)
- **Webdriver Endpoint** (for Selenium)
4. **Copy API Key** from "View Key" option
5. **Copy Code Snippets** in Java, Node.js, or Python
### Connection Code Snippets
#### Puppeteer (Node.js)
```javascript
const puppeteer = require('puppeteer-core');
(async () => {
// Connect using only the CDP endpoint — no api-key header needed
const browser = await puppeteer.connect({
browserWSEndpoint: 'YOUR_CDP_ENDPOINT'
});
const page = await browser.newPage();
await page.goto('https://example.com');
// Your automation logic here
await browser.disconnect();
})();
```
#### Playwright (Node.js)
```javascript
const pw = require('playwright-core');
(async () => {
// Connect using only the CDP endpoint — no api-key needed
const browser = await pw.chromium.connectOverCDP('YOUR_CDP_ENDPOINT');
const context = browser.contexts().length ? browser.contexts()[0] : await browser.newContext();
const page = await context.newPage();
await page.goto('https://example.com');
// Your automation logic here
await browser.close();
})();
```
#### Selenium (Java)
```java
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;
ChromeOptions options = new ChromeOptions();
options.addArguments("--no-sandbox");
options.addArguments("--headless");
// Connect using only the Webdriver endpoint — no api-key capability needed
RemoteWebDriver driver = new RemoteWebDriver(
new URL("YOUR_WEBDRIVER_ENDPOINT"),
options
);
driver.get("https://example.com");
// Your automation logic here
driver.quit();
```
### Code Recipes
Console provides pre-built **Code Recipes** for testing automation libraries. Access them in Console → SmartBrowz → Headless → Code Recipes.
**Example recipes:**
- Web page navigation
- Form filling
- Screenshot capture
- Element interaction
- Data extraction
---
## Component 2: Browser Logic
Browser Logic is a **Serverless Function type** for browser automation tasks. Unlike regular functions, Browser Logic functions are created via CLI and contain a specialized structure for browser operations.
### Supported Languages
- Java
- Node.js
**NOT Python** — Browser Logic currently does not support Python.
### Creating Browser Logic Functions
**Via CLI (required for initial creation):**
```bash
# Initialize project
catalyst init
# Create Browser Logic function
catalyst functions:create
# Select: Browser Logic
# Enter function name
# Select runtime: Java or Node.js
# Function structure is auto-generated
```
**Function Structure (Node.js — Puppeteer):**
```javascript
// index.js — boilerplate generated by CLI
// 'page' is the Puppeteer Page object injected by SmartBrowz — do NOT connect manually
module.exports.puppeteer = async (request, response, page) => {
await page.goto('https://example.com/', { waitUntil: 'domcontentloaded' });
const pageTitle = await page.title();
response.setHeader('Content-Type', 'application/json');
response.write(JSON.stringify({ output: pageTitle }));
response.end();
};
```
**Function Structure (Java — Selenium):**
```java
// Boilerplate generated by CLI for Java + Selenium
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.openqa.selenium.chrome.ChromeDriver;
import com.catalyst.browserlogic.SeleniumHandler;
import org.json.simple.JSONObject;
public class BrowserLogicExample implements SeleniumHandler {
@Override
public void runner(HttpServletRequest request, HttpServletResponse response,
ChromeDriver driver) throws Exception {
JSONObject responseData = new JSONObject();
driver.get("https://www.example.com");
responseData.put("message", "Title: " + driver.getTitle());
response.setContentType("application/json");
response.getWriter().write(responseData.toString());
response.setStatus(200);
}
}
```
> The `page` (Node.js) and `ChromeDriver driver` (Java) are injected by SmartBrowz — you do not connect to the browser manually inside Browser Logic functions.
### Deploying Browser Logic Functions
**From CLI:**
```bash
# Test locally
catalyst serve
# Deploy to console
catalyst deploy --only functions:browser_logic_function_name
```
**From Console:**
You can also **upload** a Browser Logic function directly to Console → SmartBrowz → Browser Logic → Upload Function.
### Browser Logic vs Regular Functions
| Feature | Browser Logic | Regular Function |
|---------|---------------|------------------|
| Creation method | CLI required | Console or CLI |
| Purpose | Browser automation | General serverless tasks |
| Specialized structure | Yes (browser-specific) | No |
| Logging | Console → DevOps → Logs | Console → DevOps → Logs |
| Languages | Java, Node.js only | Java, Node.js, Python |
---
## Component 3: PDF & Screenshot
Generate visual documents from webpages programmatically.
### Input Formats
1. **HTML** — Provide raw HTML string
2. **URL** — Provide webpage URL
3. **Template** — Use pre-designed templates with dynamic data
### Output Formats
- **PDF** — Generate PDF document
- **Screenshot** — Generate image (PNG/JPEG) with device viewport options
### Console Playground
**Console → SmartBrowz → PDF & Screenshot → Playground**
Test document generation directly in console:
1. Select **Input Type**: HTML, URL, or Template
2. Provide input
3. Select **Output Type**: PDF or Screenshot
4. Configure options (page size, margins, device viewport)
5. Click **Generate**
### SDK Usage
#### Java SDK
```java
import com.zc.component.smartbrowz.ZCSmartBrowz;
import com.zc.component.smartbrowz.ZCSmartBrowzConvertDetails;
import com.zc.component.smartbrowz.ZCSmartBrowzPDFOptions;
import com.zc.component.smartbrowz.ZCSmartBrowzNavigationOptions;
import com.zc.component.smartbrowz.ZCSmartBrowzPageOptions;
import com.zc.component.smartbrowz.beans.MarginDetails;
import java.io.InputStream;
ZCSmartBrowz smartBrowz = ZCSmartBrowz.getInstance();
// Convert to PDF from HTML
ZCSmartBrowzConvertDetails convertDetails = ZCSmartBrowzConvertDetails.getInstance();
ZCSmartBrowzPDFOptions pdfOptions = ZCSmartBrowzPDFOptions.getInstance();
pdfOptions.setFormat("A4");
MarginDetails margin = new MarginDetails();
margin.setTop("10"); margin.setBottom("10");
margin.setLeft("10"); margin.setRight("10");
pdfOptions.setMargin(margin);
pdfOptions.setPrintBackground(true);
ZCSmartBrowzNavigationOptions navOptions = new ZCSmartBrowzNavigationOptions();
navOptions.setWaitUntil("domcontentloaded");
navOptions.setTimeout(30000);
convertDetails.setPdfDetails(pdfOptions);
convertDetails.setNavigationDetails(navOptions);
convertDetails.setHtml("<html>Hello</html>");
InputStream outputStream = smartBrowz.convertToPdf(convertDetails);
// Convert to PDF from URL
convertDetails.setUrl("https://example.com");
InputStream outputStream = smartBrowz.convertToPdf(convertDetails);
// Generate from Template
import com.zc.component.smartbrowz.ZCSmartBrowzTemplateOptions;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
ObjectMapper mapper = new ObjectMapper();
JsonNode templateData = mapper.createObjectNode();
((ObjectNode) templateData).put("name", "John Doe");
ZCSmartBrowzTemplateOptions templateOptions = ZCSmartBrowzTemplateOptions.getInstance();
templateOptions.setPdfDetails(pdfOptions);
templateOptions.setNavigationDetails(navOptions);
templateOptions.setTemplateInput(templateData);
templateOptions.setTemplateId(2075000000021001L);
InputStream outputStream = smartBrowz.generateFromTemplate(templateOptions);
```
#### Node.js SDK
```javascript
const smartbrowz = app.smartbrowz();
// Generate PDF from HTML
const result = await smartbrowz.convertToPdf('<html>Hello</html>', {
pdf_options: {
format: 'A4',
margin: { top: '20', bottom: '20', left: '10', right: '10' },
landscape: false,
print_background: true,
scale: 1.0
},
page_options: {
javascript_enabled: true,
viewport: { height: 800, width: 600 }
},
navigation_options: {
timeout: 30000,
wait_until: 'domcontentloaded'
}
});
// Generate PDF from URL — same method, pass URL string instead of HTML
const result = await smartbrowz.convertToPdf('https://example.com', { pdf_options: { format: 'A4' } });
// Generate from Template
const result = await smartbrowz.generateFromTemplate('2075000000021001', {
pdf_options: { format: 'A4', landscape: false },
page_options: { javascript_enabled: true },
navigation_options: { timeout: 30000, wait_until: 'domcontentloaded' },
output_options: { output_type: 'pdf' },
template_data: { name: 'John Doe', course: 'Web Dev' }
});
```
#### Python SDK
```python
smart_browz = app.smart_browz()
# Convert to PDF from HTML
result = smart_browz.convert_to_pdf(
'<h1>Welcome</h1>',
pdf_options={
'format': 'A4',
'scale': 1,
'display_header_footer': True,
'print_background': False,
'landscape': False,
},
page_options={
'css': {'content': 'body { font-size: 12px; }'},
'viewport': {'width': 1440, 'height': 900},
'javascript_enabled': True,
},
navigation_options={'timeout': 5000, 'wait_until': 'networkidle0'},
)
# Convert to PDF from URL — same method, pass URL string
result = smart_browz.convert_to_pdf('https://catalyst.zoho.com/', pdf_options={'format': 'A4'})
# Take a screenshot from URL
output_screenshot = smart_browz.take_screenshot(
source='https://example.com',
output_options={'output_type': 'screenshot'},
screenshot_options={
'type': 'jpeg',
'quality': 100,
'full_page': False,
},
page_options={
'viewport': {'width': 1440, 'height': 900},
'javascript_enabled': True,
},
navigation_options={'timeout': 5000, 'wait_until': 'networkidle0'},
)
# Generate from Template
result = smart_browz.generate_from_template(
'153000000009001', # template ID
template_data={'name': 'John Doe'},
output_options={'output_type': 'pdf'},
pdf_options={'format': 'A4', 'scale': 1},
navigation_options={'timeout': 5000, 'wait_until': 'networkidle0'},
)
```
### API Usage
**OAuth scope required:** `ZohoCatalyst.pdfshot.EXECUTE`
```bash
# Generate PDF from HTML or URL
curl -X POST '{api-domain}/browser360/v1/project/{project_id}/convert' \
-H 'Authorization: Zoho-oauthtoken {access_token}' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://example.com",
"format": "A4",
"print_background": true,
"margin": { "top": "10", "bottom": "10", "left": "10", "right": "10" }
}'
```
---
## Component 4: Templates
Design and store templates for generating multiple documents with dynamic content.
### Creating Templates
1. **Console → SmartBrowz → Templates → Create Template**
2. **Design using HTML/CSS:**
- Use standard HTML5 tags
- Style with inline CSS or `<style>` tag
- Add placeholders for dynamic data: `{{variable_name}}`
3. **Save Template** with a unique name
### Template Example
```html
<!DOCTYPE html>
<html>
<head>
<style>
body { font-family: Arial; padding: 20px; }
h1 { color: #333; }
.info { margin: 10px 0; }
</style>
</head>
<body>
<h1>Certificate of Achievement</h1>
<div class="info">
<p>This certifies that <strong>{{student_name}}</strong></p>
<p>has successfully completed <strong>{{course_name}}</strong></p>
<p>on {{completion_date}}</p>
</div>
</body>
</html>
```
### Using Templates
**Generate PDF with dynamic data (Node.js):**
```javascript
const smartbrowz = app.smartbrowz();
const result = await smartbrowz.generateFromTemplate('2075000000021001', {
output_options: { output_type: 'pdf' },
pdf_options: { format: 'A4' },
template_data: {
student_name: 'John Doe',
course_name: 'Web Development',
completion_date: '2026-06-29'
}
});
```
**Use cases:**
- Certificates and diplomas
- Invoices and receipts
- Reports with dynamic data
- Marketing materials
- Personalized documents
---
## Component 5: Browser Grid (Early Access)
Run multiple headless browsers in parallel with auto-scaling.
**Note:** This feature is in Early Access. Contact support@zohocatalyst.com to enable it.
### What is Browser Grid?
Browser Grid allows you to configure and run multiple headless browsers concurrently across multiple nodes (virtual machines). The Hub (controller) automatically spawns nodes and browsers based on your configuration and request load.
**Architecture:**
```
Hub (Controller) → Nodes (VMs) → Browsers (Headless Chrome/Firefox)
```
### Browser Grid Configurations
#### 1. Basic Configuration
- **Nodes**: 1-10 nodes
- **Memory per node**: 1 GiB
- **vCPU per node**: 1
- **Browsers per node**: 1
- **Max concurrent browsers**: 10
**Best for:** Light request loads, simple automation tasks
#### 2. Advanced Configurations
**Light Node Type (1 GiB Memory, 1 vCPU)**
- **Nodes**: 1-10 nodes
- **Browsers per node**: 1
- **Max concurrent browsers**: 10
**Moderate Node Type (2 GiB Memory, 2 vCPU)**
- **Nodes**: 1-5 nodes
- **Browsers per node**: 1-2
- **Max concurrent browsers**: 10
**Heavy Node Type (4 GiB Memory, 4 vCPU)**
- **Nodes**: 1-2 nodes
- **Browsers per node**: 1-4
- **Max concurrent browsers**: 8
**Best for:** Heavy request loads, complex automation tasks requiring more processing power
### Configuration Comparison Table
| Configuration | Nodes | Memory/Node | vCPU/Node | Browsers/Node | Max Concurrent Browsers |
|---------------|-------|-------------|-----------|---------------|------------------------|
| Basic | 1-10 | 1 GiB | 1 | 1 | 10 |
| Light | 1-10 | 1 GiB | 1 | 1 | 10 |
| Moderate | 1-5 | 2 GiB | 2 | 1-2 | 10 |
| Heavy | 1-2 | 4 GiB | 4 | 1-4 | 8 |
### Creating a Browser Grid
1. **Console → SmartBrowz → Browser Grid → Create Browser Grid**
2. **Select Endpoint Type:**
- **CDP Endpoint** (for Puppeteer/Playwright)
- **Webdriver Endpoint** (for Selenium)
3. **Choose Configuration:**
- Basic
- Advanced: Light / Moderate / Heavy
4. **Configure Nodes and Browsers** based on selected configuration
5. Click **Create**
**Default Browser Grids:**
When you first access Browser Grid, two pre-configured grids are provided:
- **Puppeteer_Grid** — CDP endpoint, Basic configuration
- **Selenium_Grid** — Webdriver endpoint, Basic configuration
### Connecting to Browser Grid
**Connection code is identical to Headless**, but uses the Browser Grid endpoint:
#### Puppeteer
```javascript
const puppeteer = require('puppeteer-core');
(async () => {
// Connect using only the Browser Grid CDP endpoint — no api-key header needed
const browser = await puppeteer.connect({
browserWSEndpoint: 'YOUR_BROWSER_GRID_CDP_ENDPOINT'
});
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.disconnect();
})();
```
#### Selenium
```java
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;
ChromeOptions options = new ChromeOptions();
options.addArguments("--no-sandbox");
options.addArguments("--headless");
// Connect using only the Webdriver endpoint — no api-key capability needed
RemoteWebDriver driver = new RemoteWebDriver(
new URL("YOUR_BROWSER_GRID_WEBDRIVER_ENDPOINT"),
options
);
driver.get("https://example.com");
driver.quit();
```
### Browser Grid Workflow
1. **User connects** to Browser Grid via code
2. **Hub receives request** and checks for available node
3. **If node available** → Request sent to browser in node
4. **If no node available:**
- If node limit not reached → Hub creates new node with browser
- If node limit reached → Request is **queued**
5. **Queue duration:**
- Selenium: **30 seconds**
- Puppeteer/Playwright: **5 minutes**
6. **After queue timeout** → Request is killed, alert raised
### Browser Grid States
- **Inactive** — Default state after creation, grid not processing requests
- **Active** — Grid connected via code, nodes and browsers spawning as needed
- **Idle** — Grid active but no requests being processed, all nodes/browsers scaled down
### Browser Grid Alerts
Alerts appear in Console → SmartBrowz → Browser Grid → {grid_name} → Dashboard → Alerts
| Alert | Trigger Condition | Action |
|-------|-------------------|--------|
| Browser Creation Rejected | Requests queued beyond timeout, no browsers available | Increase node/browser configuration or reduce request load |
| 90% Disk Exhausted | Any node reached 90% of 10GB disk capacity | Clear disk space or increase disk limit |
| 80% Memory Exhausted | Any node reached 80% memory capacity | Reduce request load or upgrade to higher memory configuration |
| 80% CPU Exhausted | Any node reached 80% CPU capacity | Reduce request load or upgrade to higher vCPU configuration |
| Nodes Crashed | Node operating at max capacity and severely strained | Immediately reduce request load, restart grid |
**Clearing Alerts:**
Alerts persist until you **update the grid configuration**. Resolving the underlying issue doesn't automatically clear alerts.
### Browser Grid Dashboard
**Console → SmartBrowz → Browser Grid → {grid_name} → Dashboard**
**Real-time stats:**
- Number of nodes running
- Number of browsers spawned
- Max and average CPU core usage
- Max and average memory usage
- Alert history
**Performance Graphs:**
- Node creation timeline
- Browser spawn timeline
- CPU usage over time
- Memory usage over time
**Refresh button** — Click to update stats to latest values
### Ideal Practices for Browser Grid
1. **Right-size your configuration** — Don't over-provision. Start with Basic, scale up only if needed.
2. **Check free sessions before sending requests** — Use the Browser Grid SDK to manage grid lifecycle, then use the REST API to check `free_sessions` (no SDK equivalent exists for this specific stat):
**SDK — manage grid (Node.js):**
```javascript
const grid = app.smartbrowz().browserGrid();
// Get all grids and their details
const gridList = await grid.getGrid();
// Get node details for a specific grid
const nodeDetails = await grid.getGridNodes('YOUR_GRID_ID');
// Stop grid when done
await grid.stopGrid('YOUR_GRID_ID');
```
**REST API — check free sessions before connecting (api-key required here):**
```bash
curl 'https://console.catalyst.zoho.com/browser360/v1/project/{project_id}/browser-grid/{grid_id}/stats?data_to_fetch=live_stats' \
-H 'api-key: YOUR_API_KEY'
```
Response:
```json
{
"status": "success",
"data": {
"free_sessions": 10
}
}
```
If `free_sessions: 0`, wait until at least 1 browser is available before connecting.
> ⚠️ The `api-key` header is **only** required for REST API calls like this one. It is **not** used when connecting via Puppeteer/Playwright/Selenium — those use only the endpoint URL.
3. **Monitor alerts** — Regularly check Dashboard for alerts. Address issues before they cause request failures.
4. **Test with small loads first** — Validate your configuration with small request volumes before scaling up.
5. **Stop grid when not in use** — Browser Grid is auto-scaling, but stopping it completely when idle saves resources. Use `grid.stopGrid('YOUR_GRID_ID')` via SDK.
### Regenerating API Key
**Console → Browser Grid → {grid_name} → Overview → Regenerate**
**Consequences:**
- Grid must be **Inactive** to regenerate key
- All grid stats are reset
- You must update your code with new endpoint/key
- Reconnection is treated as first request
---
## Component 6: Dataverse
Dataverse is a SmartBrowz component for data extraction from the web. It provides three modules via Node.js SDK:
### Lead Enrichment — `getEnrichedLead()`
Fetches publicly available details about an organization. Provide at least one of: `leadName`, `websiteUrl`, or `email`.
```javascript
const smartbrowz = app.smartbrowz();
const response = await smartbrowz.getEnrichedLead({
leadName: 'zoho',
websiteUrl: 'https://www.zoho.com',
email: 'contact@example.com'
});
// Returns: employee_count, address, social, description, ceo, revenue, industries, etc.
```
### Tech Stack Finder — `findTechStack()`
Fetches the technologies and frameworks used by an organization.
```javascript
const response = await smartbrowz.findTechStack('https://www.zoho.com');
// Returns: website, technographic_data (frameworks, SSL, email hosting, etc.), organization_name
```
### Similar Companies — `getSimilarCompanies()`
Returns a list of organizations offering similar products or services.
```javascript
const response = await smartbrowz.getSimilarCompanies({
leadName: 'zoho',
websiteUrl: 'https://www.zoho.com'
});
// Returns: array of company name strings
```
**Important:** Only use Dataverse on publicly available data or domains that permit scraping.
---
## SmartBrowz Dashboard
**Console → SmartBrowz → Dashboard**
Unified view of all SmartBrowz component usage:
**Graphs (filterable by time period):**
- **Headless usage** — Number of connections and executions
- **Browser Logic usage** — Function invocations, success/failure count
- **PDF & Screenshot usage** — Document generation count
**Recent Browser Logic Executions:**
- Filter by: All Status, Successful, Failed
- Shows: Function name, timestamp, execution status
**Use dashboard to:**
- Track component usage over time
- Identify performance issues
- Debug failed executions
- Monitor resource consumption
---
## Related Skills
- **catalyst-functions** — for creating Browser Logic functions and understanding serverless function concepts
- **catalyst-datastore** — if storing automation results or fetching data for templates
- **catalyst-stratus** — if storing generated PDFs/screenshots
- **catalyst-signals** — if triggering browser automation based on events
---
## Common Errors
| Error | Cause | Fix |
|-------|-------|-----|
| "Connection refused to CDP endpoint" | Invalid API key or endpoint | Verify endpoint and API key from console, ensure no extra spaces |
| "Browser Logic function not found" | Function not deployed or incorrect name | Deploy function via CLI: `catalyst deploy` |
| "PDF generation failed" | Invalid HTML or unsupported CSS | Validate HTML syntax, test in Console Playground first |
| "Screenshot timeout" | Page load too slow or infinite loop | Increase `timeout` in `navigation_options`, check target URL accessibility |
| "Template variable not found" | Missing data in template invocation | Ensure all `{{variables}}` in template are provided in `template_data` |
| "Browser Grid queue timeout" | All browsers at capacity, request waited too long | Increase node/browser configuration or reduce request rate |
| "API key regenerated, connection failed" | Old API key used after regeneration | Update code with new API key from console |
| "Browser Grid alert: 90% disk exhausted" | Node disk usage high | Clear browser cache, reduce data storage in automation scripts, or contact support |
| "Selenium connection failed" | Incorrect Webdriver endpoint or missing capabilities | Use Webdriver endpoint (not CDP) for Selenium |
| "Puppeteer/Playwright timeout" | CDP endpoint not responding | Check endpoint URL, verify SmartBrowz is activated in console |
| "Browser Logic logs not appearing" | Function execution failed silently | Check function syntax, review DevOps logs, test locally with `catalyst serve` |
SKILL.md
---
name: catalyst-smartbrowz
description: "Catalyst SmartBrowz — browser automation and document generation service. Includes Headless (connect to remote Chrome/Firefox with Puppeteer/Playwright/Selenium), Browser Logic (serverless functions for browser tasks in Java/Node.js), PDF & Screenshot (generate visual documents from HTML/URL/Template), Templates (design dynamic content templates), Browser Grid (parallel headless browsers with auto-scaling, Early Access), and Dataverse (data scraping APIs). Trigger on 'SmartBrowz', 'headless browser', 'Headless Browser', 'Puppeteer', 'Selenium', 'Playwright', 'Browser Logic', 'PDF generation', 'screenshot', 'PDF/Screenshot generation', 'PDF & Screenshot', 'browser automation', 'Browser Grid', or 'web scraping'. Console + SDK (Java/Node.js/Python for PDF/Screenshot + Browser Grid) + CLI (for Browser Logic functions)."
metadata:
version: "2.0.0"
---
## Prerequisites
Before using SmartBrowz, activate it once per project in the console:
> Console → your project → **SmartBrowz** (left sidebar) → click **"Start Exploring"**
Skipping this step prevents access to Headless, Browser Logic, PDF & Screenshot, Templates, Browser Grid, and Dataverse components.
**For Browser Logic functions:** Requires Catalyst CLI installation. Initialize and deploy Browser Logic functions via CLI (cannot be created directly in console, but can be uploaded).
---
## How It Works
1. **Multi-component service** — SmartBrowz offers 6 independent components in one unified platform:
- **Headless**: Connect to remote Chrome/Firefox in Catalyst cloud with automation libraries
- **Browser Logic**: Serverless functions (Java/Node.js) containing browser automation logic
- **PDF & Screenshot**: Generate visual documents programmatically
- **Templates**: Design and store templates for dynamic content
- **Browser Grid** (Early Access): Parallel headless browsers with auto-scaling
- **Dataverse**: Data scraping APIs
2. **Choose your workflow:**
- **Headless mode**: Copy console-provided endpoints and code snippets to connect with Puppeteer/Playwright/Selenium
- **Browser Logic**: Initialize via CLI, code in IDE, deploy to console — for persistent browser automation tasks
- **PDF & Screenshot**: Use console Playground, SDKs (Java/Node.js/Python), or API to generate documents
- **Browser Grid**: Configure node/browser count, connect via CDP/Webdriver endpoints, process requests in parallel
3. **Load `references/smartbrowz-basics.md`** — for component details, automation library setup, Browser Logic structure, PDF/Screenshot SDK usage, Browser Grid configurations, and troubleshooting
4. **SDK-first rule** — When writing implementation code, always prefer SDK methods over raw REST API calls:
- **Node.js**: `app.SmartBrowz()` → `smartbrowz.convertToPdf()`, `smartbrowz.generateFromTemplate()`, `app.SmartBrowz().browserGrid()` → `grid.getGrid()`, `grid.stopGrid()`
- **Python**: `app.smart_browz()` → `smart_browz.convert_to_pdf()`, `smart_browz.generate_from_template()`, `app.smart_browz().browser_grid()` → `grid.get_all_grid()`
- **Java**: `ZCSmartBrowz.getInstance()` → `smartBrowz.convertToPdf()`, `smartBrowz.generateFromTemplate()`
- Use REST API **only** when no SDK equivalent exists (e.g., checking `free_sessions` on Browser Grid live stats)
5. **Key concepts:**
- **Remote browsers run in Catalyst cloud** — not local. Endpoints are auto-generated by console.
- **No api-key in connection code** — Puppeteer/Playwright/Selenium connect using only the endpoint URL. The `api-key` is only used for Browser Grid REST API calls (e.g., live stats).
- **Chrome browser only** (currently) — Firefox support in Browser Grid (Early Access)
- **Browser Logic functions = Serverless function type** — created with CLI, not console UI
- **Browser Grid = auto-scaling** — nodes and browsers spawn on demand based on configuration
- **Code Recipes** available in console for testing automation library use cases
6. **Security note** — Any browser automation or web scraping is at your own risk. Only use on domains that permit such actions or with proper approval.
## Security Checklist
- **API Key protection**: Endpoints for Headless and Browser Grid are secured with auto-generated API keys. Regenerate keys if compromised (note: this resets grid stats).
- **Browser Logic logs**: All function activity is logged in Console → DevOps → Logs. Review logs for debugging and security audits.
- **Browser Grid queue limits**: Selenium requests queue for 30 seconds, Puppeteer/Playwright for 5 minutes. After timeout, requests are killed.
- **Browser Grid alerts**: Monitor Dashboard for alerts (Browser Creation Rejected, 90% Disk Exhausted, 80% Memory/CPU Exhausted, Nodes Crashed).
- **Default storage**: Browser Grid nodes have 10GB disk limit. Monitor disk usage to prevent failures.
- **Rate considerations**: Browser automation can generate high network traffic. Be mindful of target website rate limits and terms of service.
## Triggers
Use this skill for: "SmartBrowz", "headless browser", "Headless Browser", "remote browser", "Puppeteer", "Playwright", "Selenium", "browser automation", "Browser Logic", "PDF generation", "screenshot webpage", "HTML to PDF", "URL to PDF", "template PDF", "PDF/Screenshot generation", "PDF & Screenshot", "SmartBrowz templates", "Browser Grid", "parallel browsers", "web scraping", "Dataverse", "CDP endpoint", "Webdriver endpoint", "headless Chrome", "headless Firefox", "browser testing", or "automation library".
## References
| Reference | Load when the query is about… |
|-----------|-------------------------------|
| `references/smartbrowz-basics.md` | Headless setup (Puppeteer/Playwright/Selenium code snippets), Browser Logic (CLI commands, function structure, deployment), PDF & Screenshot (console Playground, SDK usage in Java/Node.js/Python, API calls, input formats HTML/URL/Template), Templates (design, storage, dynamic content), Browser Grid (configurations Basic/Light/Moderate/Heavy, node/browser setup, CDP/Webdriver endpoints, workflow, alerts, states Active/Inactive/Idle, dashboard, ideal practices), Dataverse (data scraping APIs), troubleshooting |