Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Description of using URL-encoding for $removeparam rules #605

Merged
merged 7 commits into from
Jan 13, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions docs/general/ad-filtering/create-own-filters.md
Original file line number Diff line number Diff line change
Expand Up @@ -2398,19 +2398,23 @@ You can also use regular expressions to match query parameters and/or their valu

**Escaping special characters**

Do not forget to escape special characters like `,`, `/` and `$` in the regular expressions. Use `\` character for that purpose. For example, an escaped comma should look like this: `\,`.
Special characters should be URL-encoded in a rule to correctly match the URL text.

For example, to remove `?$param=true`, you should use the `$removeparam=%24param` rule.

:::note

Regexp-type rules target both name and value of the parameter. To minimize mistakes, it is safer to start every regexp with `/^` unless you specifically target parameter values.
Spaces and commas should also be URL-encoded, otherwise the rule won't match the URL. However, `.`, `-`, `_`, and `~` should be used as they are, since they are not marked as reserved characters in URL encoding.

:::

We will try to detect and ignore unescaped `$` automatically using a simple rule of thumb — it is not an options delimiter if all three are true:
Remember to escape special characters like `.` in the regular expressions. Use the `\` character to do this. For example, an escaped dot should look like this: `\.`.

:::note

1. It looks like `$/`
1. There is another slash character `/` to the left of it
1. There is another unescaped dollar sign `$` to the left of that slash character
Regexp-type rules apply to both the name and value of the parameter. To minimize errors, it is safer to start each regexp with `/^`, unless you are specifically targeting parameter values.

:::

**Remove all query parameters**

Expand All @@ -2425,6 +2429,12 @@ Use `~` to apply inversion:
- `$removeparam=~param` — removes all query parameters with the name different from `param`.
- `$removeparam=~/regexp/` — removes all query parameters that do not match the `regexp` regular expression.

:::note

If `~` does not appear at the beginning of the rule, it is treated as a symbol in the text.

:::

**Negating `$removeparam`**

This sort of rules work pretty much the same way it works with [`$csp`](#csp-modifier) and [`$redirect`](#redirect-modifier) modifiers.
Expand Down
Loading