Nvirya AdGuard v11.7.0
Ctrl K

Remote Rules and Advanced Configuration

In addition to built-in ad filtering and the interactive Element Picker, Nvirya AdGuard v11.7.0 supports importing custom domain blocklists from a remote URL and exporting/importing per-site CSS rules. Both workflows are located in the About tab under Backup & Sync.

1. Sync from Remote URL (Domain Blocklists)#

How remote rule synchronization works#

The Sync from Remote URL ("Import blocked domains from a raw host list") feature fetches a plain-text or JSON list of domains, extracts valid hostnames, and merges them into your custom blocked domain set (nvirya_x_custom_blocked).

Every domain added to nvirya_x_custom_blocked is enforced in two ways:

  1. JavaScript Network Interception: isAdUrl(u) checks isCustomBlockedHost(u.hostname) (matching both the exact domain and any of its subdomains via hostMatches), blocking matching fetch, XMLHttpRequest, navigator.sendBeacon, <script src>, and <img src> calls.
  2. Cosmetic CSS & DOM Purge: installCosmeticCSS() generates rules hiding iframe[src*="<domain>"], img[src*="<domain>"], a[href*="//<domain>"] for each custom-blocked domain, and syncRulesFromRawUrl() immediately scans up to 400 <script>, <iframe>, <img>, and <a> elements on the current page to remove or hide matches.

Supported rule formats#

The parser (parseDomainsFromRawText and extractDomainCandidate) accepts raw .txt or .json responses over http: or https: in the following formats:

  • Standard hosts file lines:
    0.0.0.0 ads.example.com
127.0.0.1 tracker.example.net
::1 banner.example.org
  • Adblock-style domain anchors:
    ||ads.example.com^
||popups.example.net^$third-party
  • Plain domain lists (one domain per line):
    ads.example.com
 clicks.example.net
  • JSON arrays or objects:
    [
  "ads.example.com",
  { "domain": "tracker.example.net" },
  { "hostname": "pop.example.org" }
]

What the parser validates and what it ignores#

To prevent malformed rules or incompatible filter syntax from breaking pages, extractDomainCandidate() enforces strict rules:

  • Line cap: Reads up to 15,000 lines (Math.min(lines.length, 15000)) per remote file.
  • Domain syntax validation: Every candidate is stripped of leading schemes (http://, https://), wildcard prefixes (*.), and path/option suffixes (/, ?, ^, $, :, |), then validated against RE_VALID_DOMAIN (/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i).
  • Ignored lines:
    • Comments and headers starting with #, !, //, or [ (as well as inline comments after whitespace).
    • Localhost entries (localhost, broadcasthost, local) and the current page's own hostname.
    • Cosmetic and scriptlet filter rules: Any line containing ##, #@#, #?#, or #$# is completely skipped. Sync from Remote URL imports domain names only, not uBlock/AdGuard CSS selectors or scriptlets.

How to configure and update remote rules#

  1. Open the Nvirya AdGuard control panel (Alt+A) and switch to the About tab.
  2. Under Backup & Sync, tap Sync from Remote URL.
  3. When prompted (Enter raw list URL (.txt or .json):), paste a direct https:// URL pointing to a raw text or JSON host list and confirm.
  4. The script fetches the URL (appending a cache-busting ?_t=<timestamp> query parameter) via GM_xmlhttpRequest (10-second timeout) or fetch, saves the URL to nvirya_x_sync_url, records the sync time in nvirya_x_sync_time, and displays a toast: Synced {count} new domains.
  5. Automatic 24-Hour Refresh: Whenever a saved sync URL exists in nvirya_x_sync_url, Phase 3 background initialization checks whether more than 24 hours (SYNC_INTERVAL_MS = 86,400,000 ms) have elapsed since nvirya_x_sync_time. If so, it silently re-fetches the URL and merges any newly added domains into your blocklist.

Security and trust considerations#

Important: Only synchronize domain lists from sources you trust.

  • Because every synced domain is injected into <style data-nvirya-cosmetic> (iframe[src*="..."], img[src*="..."], a[href*="//..."]) and blocked across all sites (*://*/*), importing an untrusted or overly broad host list (for example, a list that includes CDNs like cloudflare.com, jsdelivr.net, gstatic.com, or githubusercontent.com) can break images, scripts, and layouts across many unrelated websites.
  • The script validates that each entry is a syntactically valid domain name (RE_VALID_DOMAIN), but it does not verify whether a domain in your remote list is actually an advertising server versus a critical website CDN.

How to recover from incompatible synced domains#

If a synced domain list blocks a legitimate resource on a site:

  1. Unblock a single domain: Open Overview → Quick Actions → Connection Log, search for the domain in the Filter domains... box, and tap Allow next to that domain (removeCustomBlockedHost).
  2. Temporarily bypass on one site: Tap Pause for This Session or Allow This Site in Overview → Quick Actions.
  3. Clear all synced domains: Open your userscript manager's storage editor for Nvirya AdGuard and delete the nvirya_x_custom_blocked and nvirya_x_sync_url keys.

2. Exporting and Importing Per-Site Filter Rules#

When you hide elements using Hide Page Element, Nvirya AdGuard stores the generated CSS selectors per hostname in nvirya_x_site_rules:

json 
{
  "example.com": [
    {
      "selector": "div.sticky-promo-banner",
      "action": "hide",
      "created": 1761034000000
    }
  ]
}

Exporting rules (Export Filter Rules)#

  1. Go to About → Backup & Sync → Export Filter Rules ("Copy custom site rules to clipboard").
  2. If you have custom rules saved, the script formats state.siteRules as indented JSON and copies it to your clipboard (Copied {count} rules to clipboard), falling back to a copyable browser prompt() dialog if clipboard access is restricted.

Importing rules (Import Filter Rules)#

  1. Go to About → Backup & Sync → Import Filter Rules ("Merge rules from JSON or Base64 text").
  2. Paste either a JSON object mapping hostnames to rule arrays, a Base64-encoded JSON string, or a JSON array of selector strings (which will be applied to the current hostname).
  3. The script merges non-duplicate selectors into nvirya_x_site_rules, immediately updates <style data-nvirya-site-rules>, and shows Imported {count} new rule(s).

Recovering from a bad custom CSS rule#

  • To remove a single selector on the current site, open Overview → Quick Actions → Site Filter Rules and tap the red × button next to the selector.
  • To clear all custom selectors on the current site, open About → Storage & Updates → Clear Site Rules and confirm (Remove all custom rules for this site?).