Docs Overview/
Browser & WebView Integration/

Browser & WebView Integration

EdgeOne provides a client attestation SDK suitable for websites, which can be integrated into Web pages through frontend JavaScript to enable transparent verification for browser users.
Note:
To quickly integrate an imperceptible (invisible backend) attestation method into a simple Web service, you can focus on the SDK integration and attestation call part.
If the attestation method you use has user-visible interactive components, also focus on the interactive attestation adaptation part to provide a better interaction experience for the selected site.
If your site service uses both third-party domain name APIs, further focus on the CORS support: configure automatic attestation scope part to ensure the site can normally access third-party services.

Browser Compatibility

Client attestation SDK supports modern mainstream browser environments, including Mobile WebView. The earliest version recommended is as follows:
Chrome ≥ 90
Firefox ≥ 90
Safari ≥ 11
Edge ≥ 90
Mobile WebView (iOS ≥ 11, Android WebView ≥ 67)
Opera ≥ 76
Note:
Earlier browser versions (especially those that do not support Promise, Fetch, or Crypto API) may prevent the SDK from running normally.
Currently only support response integration SDK based on HTTPS protocol HTML page.

SDK Integration and Attestation Call

You can integrate the SDK into the webpage through any method. When the browser or WebView Component successfully loads the SDK, it will instantiate the EOClientSecurityKit global object in the window object. Developers can access the SDK API through this object to perform further configuration and control.
Inject JavaScript Via HTML Page (Recommended)
Manual Integration Adaptation
Injecting JavaScript via a way enables convenient integration with browsers and WebView, suitable for HTML pages provided by or proxied through the EdgeOne Platform, reducing manual intervention to the maximum extent.

Applicable Scenarios

WebView clients or browsers need to access HTML pages and API endpoints protected by EdgeOne. (HTML pages are distributed via EdgeOne proxy.)

Integration Method

No need to modify frontend code. Configure the injection rule in the EdgeOne console to enable JavaScript injection.
The client attestation SDK will be encapsulated in a JavaScript code snippet and automatically injected into the HTML content when responding to the specified HTML page. When the client continues accessing EdgeOne to load page content or initiate an AJAX request, the code snippet will run the corresponding attestation mechanism based on attestation rule requirements and automatically submit the attestation result. When used with seamless client attestation, the above attestation process requires no special adjustments or adaptations to page resources.

How SDK Works

After the SDK code is injected and loaded, it automatically intercepts XMLHttpRequest and fetch API calls in the page. The SDK transparently handles HTTP 428 challenges from the EdgeOne server and automatically adds the attestation token to subsequent request headers upon successful attestation, achieving automated client attestation.

Configure JavaScript Injection Range

You can use JavaScript injection rules to configure the injection range. By setting rule priority and match conditions, you can specify EdgeOne to inject JavaScript code fragments into specific resources or skip injection to satisfy both the best access performance and attestation effect at the same time.
Note:
Avoid enabling JavaScript injection in the following scenarios to prevent business exceptions:
Non-HTTPS page path
API path or path accessed by mobile terminal
WebSocket service path
Paths with edge function enabled
Paths with proactive feature recognition enabled
When configuring rules, you can specify conditions such as domain name (Host), URL path, and request method. For example, it can take effect only for a certain second-level domain or target a specific path (such as /checkout). In addition, you can match cookies or request headers as needed for high flexibility. Script injection is performed only when the request matches all conditions set.

Scenario Example: Automatic Deployment of JavaScript Injection for ALL HTML Pages on a Site, Attestation Browser Client

Attestation browsers and WebView clients by default when accessing ALL HTML pages on the e-commerce site www.buyexample.com, so that attestation policy can be deployed for API integration.

Operation Steps

Note:
1. Before performing the operation steps here, please first configure the attestation method.
2. Before configuring in the production environment, use a test domain to deploy and test compatibility.
1. Log in to the EdgeOne console, enter Service Overview in the left menu bar, and click the configured site under Secure Content Delivery Network.
2. Click Security Protection > Client Attestation. Click the Attestation SDK Integration page, and select Browser Integration: Inject JavaScript under Add Rule to enter the rule configuration interface.



3. Fill in the rule name, configure the judgment condition and JavaScript injection options. For example, in the match condition options, select request domain matching; in the JavaScript injection options, select inject JavaScript. When a request matches multiple rules, the rule disposal method with higher priority (lower numeric value) takes precedence.



4. Click Save and Publish. The rules will deploy.
Suitable for specific scenarios where JavaScript injection cannot be performed on the EdgeOne Platform, such as local file loading or multi-CDN distribution.

Use Cases

Web pages load from local storage (file system, internal storage).
Static site files are distributed via multiple CDNs not controlled by EdgeOne.
Developers need finer control over SDK loading and initialization.

Implementation Approach

Ensure the client device can access the Internet. Insert the following <script> tag directly into the target HTML page <head> section (or before the <body> closing tag):
Note:
Please ensure the src attribute points to the correct SDK distribution address.
<script src="https://cdnstatic.tencentcs.com/edgeone/security/client-attestation/eoclientsecuritykit.min.js"></script>

How It Works

<script> After the tag loads and executes, eoclientsecuritykit.min.js will run and intercept requests sent via AJAX (XHR and Fetch API) on the page. The SDK will handle attestation challenges, obtain attestation tokens, and automatically attach them to subsequent requests, thereby protecting the API endpoint.

Adapting to Use Interactive Attestation (Optional)

In some client attestation scenarios, EdgeOne SDK requires specific runtime environment support, such as:
When the attestation process requires user interaction (such as verification code)
Perform compute-intensive tasks (such as Proof of Work)
In such scenarios, the SDK needs to load JavaScript in a runtime environment (WebView or browser). This section elaborates on how to adapt to these interactive attestation scenarios, including WebView usage methods and rendering options for attestation UI.

Running Interactive or JS-Based Attestation in WebView

When the authenticator needs to render an interactive CAPTCHA or run JavaScript-based encryption Proof-of-Work challenges, the SDK requires a WebView instance in the API parameters. This means developers must allocate a WebView instance in advance and pass it as an argument to the SDK when calling the attestation API.

Interactive Attestation Scenarios

Some authenticators (such as TC-CAPTCHA with embedded or pop-up interaction settings) require a WebView instance to render their interactive interface. The WebView instance will display the verification code webpage within the application, so it must be preset to ensure correct display.
Embedded Interactive Authentication
Popup Interactive Authentication
Display in fixed blocks on the device screen. To ensure the UI displays correctly without affecting user experience, the developer must preset the rendering window size, layering sequence, and alignment mode. Please note, the embedded attestation GUI does not scale with the screen view.
Description: For Tencent Cloud Captcha (TC-CAPTCHA) embedded mode, reserve at least 300x230 pixel space to get the best rendering effect and user interaction experience.
When attestation is invoked, it displays as a floating window on the device screen. Similar to embedded attestation, the rendering window size, layering sequence, and alignment mode must also be preset. The feature of popup attestation is that when the screen view is less than a specific threshold, the popup attestation GUI will automatically resize to adapt to different screen sizes.
Description: The initial rendering block size of Tencent Cloud Captcha (TC-CAPTCHA) popup mode is 360x360 pixels.

JavaScript-Based Attestation Scenario

Some authenticators (such as TC-CAPTCHA in seamless mode) require a WebView instance as a JavaScript runtime environment, primarily for executing encrypted Proof of Work (PoW) challenges. In this scenario, the WebView instance provides only a JavaScript execution sandbox, without the need to render any UI visibly. Therefore, the passed-in WebView instance does not need to be visible, and the SDK will not use it for UI rendering.

Rendering the Required UI for Attestation

For H5/web applications in a browser or WebView environment, when using interactive or visible attestation, the SDK requires an HTML element to render the attestation UI. The SDK supports various common container elements, such as <span>, <p>, <div>, and <section>. The SDK determines the rendering position of the attestation UI based on the following priority order:
Option One: Use Selector Callback to Specify Element
Option Two: Use Eo-Client-Attestation Element ID
Option Three: Default Dynamically Create Element
Developers can invoke the window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(elementSelectorFunc) API to allocate an element selector function. When the SDK needs to render the attestation UI, it will invoke this function. elementSelectorFunc can be defined in the following two ways:
Return CSS selector string: Return directly the CSS selector string, such as element ID (#valid-dom-id), class name (.valid-dom-class), or more complex descendant selector (#valid-dom-id .valid-dom-class). The SDK will use this selector to search for page elements and render UI.
Return async function callback: If you need to dynamically create or confirm the rendering element at runtime, return a Promise that eventually resolves to a CSS selector string. This provides flexibility for complex dynamic UI scenarios.
Example:
// Selector prototype for element rendering callback
type ClientAttestationDOMSelector = () => string | Promise<string>

// Example 1: Use element ID to specify element (synchronously)
const tmpProviderSyncId: ClientAttestationDOMSelector = () => {
  return '#valid-dom-id'; // Return element ID selector
};

// Example 2: Use async function to specify element (dynamically create element)
const tmpProviderAsync: ClientAttestationDOMSelector = () => {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      const id = Math.random().toString(36).substring(2, 15);
      const iframe = document.createElement(\'div\');
      iframe.id = id;
      document.body.appendChild(iframe);
      resolve(`body > #${id}`); // Parsing into selector string
    }, 500);
  });
};

// Callback function setting (select one of the example to configure)
// window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(tmpProviderSyncId);
// window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(tmpProviderAsync);

Note:
If a selector for the designated rendering element callback is defined inline (option one), this option will take precedence.
If setClientAttestationDOMSelectorProvider fails to allocate a callback function, the SDK will search for the first HTML element with ID eo-client-attestation on the page. Once found, this element will be used to render the attestation UI. This method provides a simple agreement, allowing developers to reserve the attestation UI display area.
Example:
<div id="eo-client-attestation"></div> <!-- Element reserved for rendering area -->
Developers can place this div element in a suitable location on the HTML page, customize the style as needed, and ensure the attestation UI matches the overall design style of the page.
When the other two rendering options do not exist, EdgeOne SDK will adopt the default policy: dynamically create a new HTML element at the end of the <body> tag for rendering the attestation UI.
Note:
While this default rendering method ensures attestation UI display, it may not provide the best user experience. Since elements are dynamically created and positioned at the <body> end, their style and layout may not align with the page design, or even be obstructed by other elements. Therefore, strongly recommend developers proactively allocate and designate a specialized element for rendering the attestation UI (via option one or option two) to enable precise control over its display position, size, and style, delivering a higher-quality user experience.

CORS Support: Configuring Automatic Attestation Scope (Optional)

When integrating third-party services on a page, you may encounter cross-origin resource sharing (CORS) policy conflicts. EdgeOne SDK provides a flexible mechanism to limit the scope of application of its request blocking. By reasonably configuring the automatic attestation scope, developers can ensure effective management of the SDK's behavior in complex Web environments and prevent conflicts with third-party service CORS policies.