Site Configuration

Goal

Manage advanced site settings, including encrypted URLs, scripts, browser emulation, proxies, request/response header recording, page controls, and access behavior.

Prerequisites

• The target site has been created.
• Test the site before publishing scripts.

Steps

1. Go to "Site Management > Site List".
2. Find the target site and click configuration.
3. Enable encrypted URL as needed to avoid showing the origin site address directly in the user frontend.
4. Configure browser emulation, proxy, request headers, response headers, page controls, and scripts.
5. Save the site configuration.
6. Use a test account to access the target site and verify opening, login, navigation, API data, and SSE event handling.
7. To customize behavior by account category, return to the site list and open "Account Category Config".

Configuration Reference

Item	Purpose	Notes
Encrypted URL	Hide the origin site address shown in the user frontend	Does not replace the target site's own authentication
Browser emulation	Adjust browser brand, mobile device model, time zone, and other identification data	Revalidate target site compatibility after changes
Proxy settings	Configure direct access, system proxy, PAC, or a fixed proxy server for the site	Proxy errors can prevent the site from opening or cause login exceptions
Request headers	Record specified request headers for page scripts to read through api.header(name, true)	Only configured headers that actually pass through the remote browser are recorded
Response headers	Record specified response headers for page scripts to read through api.header(name, false)	Header names are converted to lowercase when read
Page script	Handle DOM, forms, buttons, navigation, and page enhancements	Limit matching URLs to avoid unintended effects
SSE script	Rewrite Server-Sent Events stream data	Suitable for advanced scenarios; test first
Normal API interception script	Rewrite the response body of non-SSE APIs	The script must return the new response body string
Page control	Hide or remove page elements by URL and selector	Selectors may fail after the target site is redesigned
Account category config	Set differentiated login logic for different account categories	Used together with site browser accounts

Script Configuration

The "Script Configuration" area on the site configuration page adds a set of script rules for the target site. Each rule runs when the remote browser accesses the target site, according to its matching URL and script type.

Field	Type	Description
name	string	Script name. The recommended format is "site-purpose-version", for example crm-login-v1.
url	string	Matching URL. When empty it is usually treated as *; production rules should be as precise as possible.
pageScript	boolean	Whether this is a page script. When enabled, the script runs in the page context and can use window.api.
sseScript	boolean	Whether this is an SSE interception script. It is shown and effective only when pageScript = false.
selector	string	Execution condition for page scripts. When set, the script runs only if the page can match this CSS or XPath selector.
content	string	JavaScript script content. Parameters and return values differ by script type.

Page Script

When pageScript = true, the script runs as a page script. It is suitable for DOM handling, forms, button clicks, navigation, overlays, user data reads/writes, and page enhancements.

Runtime behavior:

1. The remote browser accesses the target page.
2. The system initializes window.api in the page and accessible iframes.
3. If selector is configured, the script runs only when the selector matches an element.
4. The script can directly use api.config, api.user, api.dom, api.utils, and api.header(). See the Script API appendix for the full API.

Example: wait for an element, hide an ad area, and read product configuration.

await api.utils.wait(
  () => !!api.dom.querySelector(document, '.main-panel'),
  10000,
  200
);

const envName = api.config.envName || 'default';
console.log('current env:', envName);

const banner = api.dom.querySelector(document, '.ad-banner');
if (banner) {
  banner.style.display = 'none';
}

SSE Script

When pageScript = false and sseScript = true, the script intercepts Server-Sent Events data. The system wraps EventSource and fetch in the page and processes streams whose URL matches and whose content type is text/event-stream.

Execution form:

async (data) => {
  // Script content entered in content
}

Parameter	Type	Description
data	string	Current SSE message or streaming chunk text.

The return value must be the new SSE text. If no string is returned, the page may receive abnormal data.

Example: replace text in SSE data.

return data.replace('old text', 'new text');

Normal API Interception Script

When pageScript = false and sseScript = false, the script intercepts normal API responses. The system matches the API URL, reads the response body, and passes the body to the script for rewriting.

Execution form:

async (data, api, url) => {
  // Script content entered in content
}

Parameter	Type	Description
data	string	Original response body.
api	object	Script API. See the Script API appendix.
url	string	Current intercepted API URL.

The return value must be the new response body string.

Example: rewrite a JSON API response.

const obj = JSON.parse(data);
obj.debug = true;
obj.fromScript = url.includes('/api/');
return JSON.stringify(obj);

Matching URL Rules

The url field supports the following rules:

Pattern	Description	Example
*	Match all URLs	*
regex:<expression>	Match the URL with a regular expression	regex:/api/chat
exact:<full URL>	Match the complete URL exactly	exact:https://example.com/api/user
script:<expression>	Execute an expression with the current URL as the variable url	script:url.includes('/api/')
Plain string	Check whether the target URL starts with this string	https://example.com/api/

For production scripts, prefer exact paths or stable prefixes to reduce the risk of affecting unrelated pages and APIs.

Request Headers and Response Headers

Request headers and response headers in site configuration record specified headers, which page scripts can read through api.header(). See the Script API appendix for full parameters.

Steps:

1. Add request header names to record in "Request Headers", for example authorization and cookie.
2. Add response header names to record in "Response Headers", for example content-type and set-cookie.
3. Save the configuration and access the target site through the remote browser.
4. Read them in the page script.

const authorization = await api.header('authorization', true);
const contentType = await api.header('content-type', false);

Notes:

• Header names are converted to lowercase when read.
• Only headers that are configured and actually pass through the remote browser can be read.
• Response headers may be string arrays, so scripts should handle arrays and empty values.

Selector Syntax

Script selectors and page control selectors support CSS and XPath.

Pattern	Description
.button.primary	CSS selector.
xpath://div[@id="app"]	XPath selector.
.dialog:p	Return the parent element of the matched element.
.dialog:p2	Return the parent two levels above the matched element.
.header:bottom	In overlay boundary methods, use the bottom boundary of the target element.
.sidebar:right	In overlay boundary methods, use the right boundary of the target element.

Configuration Change Process

1. Record the current configuration and script content.
2. Modify them on a test site or with a test account.
3. Verify opening, login, navigation, logout, API responses, and SSE events.
4. Check whether page control rules hide or remove the correct elements.
5. Sync the configuration to the production site.
6. Ask related users to re-enter the site and verify.

Verification

• Site cards in the user frontend display according to the configuration.
• When encrypted URL is enabled, the user interface does not directly show the origin site URL.
• Custom scripts take effect according to matching rules when the remote browser accesses the target site.
• Page scripts can correctly read configuration, locate elements, and handle page behavior.
• SSE scripts rewrite only the target event stream and do not affect normal APIs.
• Normal API interception scripts return valid response body content.
• After the target site changes, scripts and selectors still match correctly.

FAQ

• Test scripts on a test site before using them in production.
• Encrypted URL only affects frontend display and access paths; it does not bypass the target site's own security policies.
• Page scripts are suitable for DOM, forms, and page behavior.
• SSE scripts are only suitable for Server-Sent Events streams and should not be used for normal JSON APIs.
• Normal API interception scripts must return strings, otherwise the target page may fail to parse the response.
• Full parameters and examples for available script APIs are in the Script API appendix.
• Account category configuration is suitable for defining different behavior for different login methods on the same site.