Drift monitoring

Drift is a script or network connection that the published banner observes but does not find in its compiled inventory.

The banner sends drift telemetry only when the team's plan includes tracker monitoring. If entitlement lookup fails during a build, drift reporting is disabled in that bundle. The reporting endpoint also rejects inactive banners, unauthorized origins, and teams without the feature.

Understand the baseline

The published bundle includes known script fingerprints and known connection domains from the banner snapshot. The runtime compares later browser activity with those lists.

Unknown scripts are reported to the script drift endpoint. Unknown network activity is reported to the connection drift endpoint. The server aggregates repeated observations instead of creating a row for every request.

Script reports are stored in script_drift_reports. Connection reports are stored in connection_drift_reports. Connection rows are grouped by banner, destination domain, normalized path pattern, request type, and hostname.

Reports include first and last observation times, hit counts, outcome counts, a category, a vendor when recognized, and a status. Stored page and destination URLs follow the banner's telemetry grouping setting.

At origin grouping, connection reports carry no path: the runtime sends / as the path pattern, so a promoted connection is recorded for / only. Connection blocking matches on the path, so such a row blocks only requests to / itself, and the inventory does not show it as blocked even after you confirm its category. To block that host's requests, use origin and path grouping (numeric IDs, UUIDs, email addresses and long tokens in the path are replaced with placeholders such as :id, and the query string is never sent), or add a blocking rule for the domain.

Known list

A promoted item only joins the compiled baseline when you publish. Until then, and for items that have already reached the promotion threshold, visitors would keep reporting the same resource. To avoid that, CookieBeam publishes a known list (known.json) next to the banner script. It holds a hash of every cookie, script, and connection drift row that is promoted or has reached the promotion threshold.

When the runtime has drift to report, it downloads the known list once per page, drops the items it contains, and sends the rest. A small sample of known items is still sent, so last-seen times and hit counts keep moving. Rows below the threshold are never in the list, so they keep counting toward promotion normally. The list is refreshed when you publish and once a day for banners with new drift activity. If the list cannot be loaded, the runtime reports everything. Banners published before the known list existed keep their old behavior until they are published again.

Account for automatic promotion

A script or connection drift row is automatically promoted into the detected inventory when its hit count reaches five. Promotion creates or reactivates an inventory row, changes the drift status to promoted, and marks the banner as having unpublished changes.

Automatic promotion does not publish the banner. Review the category and vendor, then publish before expecting the compiled production inventory to include the item.

Automatic promotion has two caps:

• At most 50 drift rows of each report type can be automatically promoted for one banner.
• At 500 open new or reviewed rows for a report type, new unique rows are discarded. Existing rows can still receive additional observations.

The threshold uses aggregated observation counts. One telemetry batch can add more than one hit for the same resource.

Review script drift

For each new script report:

1. Check the domain, URL pattern or inline fingerprint, element type, and trigger.
2. Compare allowed, blocked, quarantined, and replayed counts.
3. Confirm or change the assigned category.
4. Promote the row manually when it belongs in the inventory, or change its status when it does not.
5. Publish the banner after inventory changes.

Manual category choices are stored as overrides on the detected inventory row. Later observations update last-seen data without replacing that override.

Review connection drift

For each new connection report:

1. Check the destination domain, normalized path, request type, and hostname.
2. Review the stored outcome counts.
3. Confirm whether the connection is third-party and whether its category is appropriate.
4. Promote the row when it belongs in the detected connection inventory.
5. Publish the banner after inventory changes.

The connection endpoint skips malformed entries within an otherwise valid batch and processes the remaining entries. A successful response can therefore report both accepted and skipped observations.

Verify after publishing

Use a clean browser profile and reproduce the tag or request. Check that the item no longer appears as new drift and that its consent behavior matches the published category.

Drift detection is an observation and inventory workflow. Promotion does not by itself prove that a resource was blocked or allowed on every page; use the stored outcome counts and a browser network trace to verify the case you are investigating.