Rumable SDK Source and Configuration¶

This page explains how Rumable injects, loads, and initializes the SDK. For an approach that does not require hand-written configuration, see One-Click Integration; for manual configuration, jump to Complete Examples for the Four Integration Methods; for first-time installation, see Installation and Integration; for version updates and rollbacks, see Operations Guide.

Injection Methods and Timing¶

Rumable adds external scripts after the standard <head> returned by the web server and does not modify business source files. The source and the loading method are independent of each other:

Same-domain resources are located under __rumable__/<site-id>/ on the website, and file names include a content digest. Choosing the same domain only changes where the SDK is downloaded from; data is still sent to the configured reporting endpoint.

Asynchronous script downloads do not block HTML parsing, but errors, requests, and interactions before initialization may not be captured. The synchronous method uses two ordinary external scripts without async or defer, so initialization completes before subsequent business scripts; a slow network or CDN failure delays subsequent page parsing and the first screen.

Sync cannot guarantee capturing all events before an SDK load failure or before initialization. An SDK load failure does not automatically switch to a same-domain copy; sync mode still has to wait for the browser to complete the request or determine that it failed. Neither method automatically relaxes CSP.

What Do source and loading Mean?¶

source indicates where the SDK is downloaded from, and loading indicates how the SDK is loaded. The two are independent choices:

If you do not specify loading, async is used; you can also explicitly set loading = "async". The examples below all state the loading method for easy comparison. [sites.sdk] is the TOML table name where these options are placed, not another parameter to fill in.

Select on the Configuration Page and Integrate with One Click¶

We recommend starting with the one-click integration flow: fill in the application parameters on the page, select the SDK method, then copy the generated command and run it on the server. No need to hand-write the TOML below. The configuration page provides two dropdowns under "Select SDK Source and Loading Method":

For example, to use the official CDN with synchronous loading, select "CDN" and "Sync", and enter https://static.guance.com/browser-sdk/v3/dataflux-rum.js as the CDN address. After confirming the digest on the right, read the release version, download the TOML, and then run the command generated on the page.

One-click integration supports all four combinations above and also supports selecting CDN and synchronous loading during automatic website discovery.

Sites with the CLI Already Installed¶

For first-time integration, directly use the command generated by the latest configuration page. If an existing site needs to change the SDK source or loading method, keep the original configuration, site ID, and state directory, and reapply as described in Configuration Updates and Upgrades. Downloading the TOML or refreshing the configuration page does not automatically update the CLI and SDK on the server.

Complete Examples for the Four Integration Methods¶

The four code blocks below are all complete Linux/Nginx configuration files. Select only one and save it as /etc/rumable/website.toml; do not combine all four examples into one file. For existing sites, back up the original TOML first, modify only the original [sites.sdk] table, and keep the original site ID, paths, sampling, and other settings.

When integrating for the first time, replace the following values:

Fill in service, env, and version according to your business; here version is the business application version, not the SDK version. The examples enable full session sampling and disable replay; adjust them after completing the acceptance check.

Example 1: Website Same-Domain + Async¶

Default method. The SDK is served from your website's domain, and the page does not wait for it to finish loading.

schemaVersion = 1

[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]

[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false

[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"

[sites.sdk]
source = "bundled" # Served from the website's domain
loading = "async" # Asynchronous loading; does not wait for the SDK download to complete

Example 2: Website Same-Domain + Sync¶

The SDK is served from your website's domain; it initializes first, then continues parsing the page.

schemaVersion = 1

[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]

[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false

[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"

[sites.sdk]
source = "bundled" # Served from the website's domain
loading = "sync" # Wait for the SDK to load and initialize before continuing to parse the page

Example 3: CDN + Async¶

The browser downloads the SDK from the specified CDN asynchronously, while the initialization script is still served from the website's domain.

schemaVersion = 1

[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]

[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false

[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"

[sites.sdk]
source = "cdn" # Download from CDN
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
integrity = false
loading = "async" # Asynchronous loading; does not wait for the SDK download to complete

Example 4: CDN + Sync¶

Load the CDN SDK and complete initialization first, then continue parsing the page.

schemaVersion = 1

[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]

[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false

[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"

[sites.sdk]
source = "cdn" # Download from CDN
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
integrity = false
loading = "sync" # Wait for the SDK to load and initialize before continuing to parse the page

How IIS and DataKit Use These Examples¶

IIS uses the same [sites.sdk] configuration. Replace the entire [sites.nginx] table in the selected example with the one below and keep the remaining fields:

[sites.iis]
site = "Default Web Site"
application = "/"
allowCompressionChanges = true

Change site to the actual IIS site name. allowCompressionChanges=true means IIS static and dynamic compression is allowed to be disabled for this application; the original settings are restored when disabled. A child application /shop corresponds to publicURL=https://www.example.com/shop/, and the injection and acceptance paths should also use the /shop/ prefix.

When reporting through DataKit, remove site and clientToken from [sites.rum], add datakitOrigin = "https://datakit.example.com" instead, and replace it with the real address. The two reporting methods are mutually exclusive; do not append /v1/write/rum.

How to Apply After Saving¶

When integrating with Nginx for the first time, run the following using the actual CLI path of the matching version:

sudo rumable setup --config /etc/rumable/website.toml --state-dir /var/lib/rumable --site website

Here rumable represents the installed CLI; if it is not in PATH, replace it with its absolute path. Confirm the Nginx attachment to be modified before applying, and then verify execution in the browser and that real data is ingested. For already-integrated sites, keep the original state directory and re-run enable after modifying the configuration.

For first-time integration on Windows and acceptance checks on both platforms, see Installation Guide; for modifying the configuration of already-integrated sites, see Operations Guide.

CDN Address, Digest, and SRI¶

• The URL must be a complete HTTPS script address, without credentials, query parameters, or fragments.
• A self-hosted CDN must serve the exact same SDK bytes as the selected installation package. Enablement and probing check the content digest, JavaScript MIME type, and both plain and gzip responses.
• The browser CSP must allow the actual CDN address. Selecting CDN does not move the initialization script off the website's domain.
• Cross-origin SRI requires the CDN to return an Access-Control-Allow-Origin that allows the site's Origin or *. The current official v3 address does not enable SRI by default; before enabling it, rely on the actual response headers and installation checks.
• The official v3 address is mutable; digest matching during probing does not lock future content. To pin a version, use same-domain mode or maintain immutable files on a self-hosted CDN.
• When using bundled, do not fill in url or enable integrity; otherwise validation rejects the configuration.

Automatic Discovery Configuration¶

Automatic discovery lets the tool scan the websites already present on the server and then lets you choose the integration target, saving the steps of manually entering the website address and Nginx/IIS target. It uses server, [rum], and [sdk], which is a different format from the complete configuration that contains [[sites]].

The following are complete automatic discovery configurations. Select only one and save it as /etc/rumable/discovery.toml; replace the application ID, OpenWay address, and token. They can only be passed to setup --discover, not directly to enable.

Same-domain async, using default behavior and no SDK configuration table:

schemaVersion = 1
server = "nginx"

[rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
sessionReplayEnabled = false

CDN sync, specifying the SDK address and loading method:

schemaVersion = 1
server = "nginx"

[rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
sessionReplayEnabled = false

[sdk]
source = "cdn"
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
loading = "sync"
integrity = false

On Windows, change server to "iis" and, according to actual authorization, set the top-level allowCompressionChanges = true before [rum]. The SDK parameters have the same meaning as in the complete configuration, but the table name is [sdk], not [sites.sdk].

On Nginx, run it with the actually installed CLI. After a site is selected in the terminal, the integration marker is printed:

sudo rumable setup --discover --config /etc/rumable/discovery.toml --state-dir /var/lib/rumable

On Windows, run setup --discover in an administrator terminal using the actual exe, configuration file, and state directory. Continue to use the original site ID, target, and state directory afterwards; do not take over the same deployment with another arbitrary ID.

Paths, Sampling, and Replay¶

includePaths and excludePaths match by case-sensitive prefix, with exclusions taking priority; probePaths must be within the injection scope and directly return verifiable HTML. Paths determine whether the server rewrites the page; they do not mean the SDK's Fetch/XHR requests are excluded, and injection is not re-evaluated when the SPA switches routes.

Replay is disabled by default. Adjust the following fields in the existing [sites.rum] table of the complete configuration rather than adding the table again:

sessionSampleRate = 100
sessionReplayEnabled = true
sessionReplaySampleRate = 20
sessionReplayOnErrorSampleRate = 0
defaultPrivacyLevel = "mask"

Replay depends on RUM session sampling; after changing the sampling rate, verify with a new session. Replay, request compression, and remote configuration may require a Worker. The default Blob Worker requires CSP to allow blob:; an external Worker is hosted on the user's domain and must remain version-matched.

For detailed sampling semantics, see Sampling Configuration. setUser, manual startView, custom events, and function callbacks still require business code; Rumable's static configuration cannot automatically replace these calls. "Application Version" is a business label, and "SDK Remote Configuration" adjusts collection parameters; neither one upgrades the SDK file.

Configuration Page or CLI Reports the Selected Method Is Unsupported¶

Open the latest configuration page, re-read the release version, and generate the installation command. If the installed CLI reports that it does not recognize loading or [sdk], update the CLI following the upgrade steps, then reapply the original site configuration. When upgrading, keep the original site ID, target, and state directory.