URL Scrubbing
UrlScrubber masks secrets in a URL or any text before it is sent: every page location, referrer, title and string parameter passes through it.
On this page
Quick Reference#
import 'package:magic_analytics/magic_analytics.dart';
void main() {
final String safe = UrlScrubber.scrub(
'https://app.example.com/[email protected]&token=abc123',
);
// https://app.example.com/reset?email=[Filtered]&token=[Filtered]
assert(safe.contains(UrlScrubber.filtered));
}
| Member | Does |
|---|---|
UrlScrubber.scrub(text) |
Returns text with every secret the three rules find replaced |
UrlScrubber.filtered |
The replacement, [Filtered] |
A masked value becomes [Filtered] rather than disappearing, so a report still shows that the URL carried a secret and where. Text with nothing to mask comes back unchanged.
The Three Rules#
Applied in this order:
- Query values. A
?key=value,&key=valueor#key=valuepair whose key containstoken,password,secret,signature,credential,api_key,emailorcode(any case) keeps its key and loses its value. - Route-bound segments. A path segment sitting where a registered Magic route has a param whose name contains
tokenis masked. The routes are read fromMagicRouter.instance.allRoutesat scrub time, so a route inside a layout group, or one added after boot, is covered. - Email addresses. Anything shaped like an email address, raw or with a percent-encoded
@, is masked wherever it appears.
Rules 1 and 2 mirror magic_sentry's token scrubber, copied rather than imported so this package does not depend on Sentry.
Where It Runs#
The facade scrubs for you, so app code never calls it on the way out:
| Input | Scrubbed |
|---|---|
String values in track and setDefaultParams |
Yes, before the length limit applies |
setUserProperties values |
Yes |
screen name, location and referrer |
Yes |
identify |
Refused when scrubbing would change the id |
| Event, parameter and property names | Not scrubbed; they are code, and are validated against the GA4 name rules |
The page view observer adds a second guard: it reports the route PATTERN (/monitors/:id), so the real URL never reaches the scrubber at all. The scrubber covers the strings an app passes in by hand.
Limits#
It masks values it can recognise: a key that names a secret, a route param that says token, an email shape. A secret in a free-text parameter that matches none of these is not caught. Do not put one there.
Name a credential route param with token in it (:resetToken) or the route rule does not see it.
Gotchas#
| Mistake | Fix |
|---|---|
A route param named :key or :hash carrying a credential |
Rename it with token in it; the rule matches on the name |
| Scrubbing before a route is registered | Register routes first; the rule reads MagicRouter.instance.allRoutes |
| Putting an email in a parameter to read it back later | Send the user's UUID; the email is masked on the way out |
| Relying on the scrubber for a free-text secret | Keep secrets out of parameters |
Related Documentation#
- Facade and Provider: where each call is scrubbed.
- Testing: asserting that a page view carries the pattern.