--- title: "Frontend scans (remote crawler)" manual: "Accessibility Quality Gate" version: "2.1" permalink: "https://docs.typo3.org/permalink/priebera/typo3-a11y-quality-gate:usage-remote-scans@2.1" source: "Usage/RemoteScans.rst" rendered: "2026-10-27T10:03:44+00:00" --- # Frontend scans (remote crawler) {#usage-remote-scans} Frontend scans are executed by a hosted crawler that renders pages with Chromium, executes JavaScript and runs axe-core in addition to the AQG rules. They are managed on the **Frontend scan** tab of the overview. ## Free Remote Preview {#usage-remote-scans-free} Installations without a licence key can run a limited number of remote single-page scans without a licence key or AQG account, once a TYPO3 administrator has activated the preview for the site (see [Activating the FREE Remote Preview](https://docs.typo3.org/permalink/priebera/typo3-a11y-quality-gate:usage-remote-scans-free-activation@2.1)). The tab shows the scans and pages used today, the remaining scans and the time of the next reset. The allowance is not defined by the extension. AQG reads the current quota, usage and reset time from the AQG service and displays them; treat the values shown in the module as authoritative. The preview scans the TYPO3 page that is currently selected in the page tree. Results are stored separately from licensed scan results. Features that are not part of the preview — page screenshots, TYPO3 record mapping, scan history, diff tracking and PDF export — are shown as locked. The crawler runs on the AQG service, outside the TYPO3 installation, and only scans sites on the public internet. When the base URL of the selected page's Site is a local, development or internal address — `localhost`, `*.ddev.site`, `.test`, `.local`, a private IP address and the like — the tab explains this instead of offering a scan: refusing such addresses is a security safeguard of the crawler, not a licence limit, and the content scan keeps working. A site that the crawler refuses during a scan, for example a host that only resolves in a VPN or internal DNS, gets the same explanation. Run the preview in an installation whose Site is publicly reachable, such as staging or production, or select a page of a Site with a public base URL that this installation serves. There is no way to scan local or private addresses with the AQG crawler. Below a Free Remote Preview result, the tab names what a 5-day trial adds — full-site frontend scans with screenshots, record mapping, scan history and comparison — and what PRO and Agency add on top: PDF export, acceptance evidence, monitoring and **Verify fix**. The offer follows the result and never covers it; [showProHints](https://docs.typo3.org/permalink/priebera/typo3-a11y-quality-gate:confval-showprohints@2.1) hides it. ### Activating the FREE Remote Preview {#usage-remote-scans-free-activation} FREE scans are sent to the AQG cloud crawler only after a TYPO3 administrator has accepted the FREE terms and the FREE data processing terms (DPA) for the site and the AQG service has recorded that acceptance. Until then the tab says that the preview is not activated, offers administrators the way to **Settings > Licence > FREE Remote Preview**, and does not contact the AQG service for the site at all. In **Settings > Licence > FREE Remote Preview** an administrator 1. reads what FREE sends to the AQG service (the address of the chosen page, the site's base URL and the anonymous installation ID — no TYPO3 content, passwords, editor data or screenshots), 1. opens the FREE terms and the DPA that the AQG service publishes (version, language and document links come from the service; nothing is activated while they are not published), 1. chooses the site, enters the organisation (legal name of the website operator), their name and email address, 1. ticks the declaration (never preselected) that they are authorised to have the site scanned and accept the FREE data processing terms, and 1. selects **Accept and activate FREE Remote Preview**. The extension sends the acceptance to the AQG service: installation ID, site URL and domain, terms version, the accepted documents with their versions and hashes, the declaration with its hash, the organisation and the administrator's name, email address and TYPO3 user ID. The AQG service records it with its own UTC timestamp and answers with an acceptance ID. Only that answer activates FREE: the extension keeps the acceptance ID, the accepted versions and the service's timestamp in `sys_registry` and shows them per domain. A network error, a refused request or an answer that does not confirm exactly what was sent activates nothing. - The activation belongs to the domain, as the AQG service records it for installation and domain. Sites with the same domain (with or without `www.`, any path or port) share one activation and are shown in one row: switching it off, renewing it or a refusal by the AQG service applies to all of them. - Only administrators can accept or change the activation; editors see the status of the sites they can read on the site root. - The acceptance survives logouts, cache flushes and deployments of the same database. It is not asked again before each scan. - **Switch off** stops new FREE scans for the site and keeps the acceptance; **Switch on** reuses it while it is valid for the same installation and terms. - New terms, an acceptance the AQG service revoked or that expired, another installation (a different installation ID) or another domain need a new acceptance. **Check status** asks the AQG service for the current state. - FREE requests carry the acceptance ID, and the AQG service checks it on every token request and scan. > [!NOTE] > The acceptance endpoints and the published FREE terms are provided by the > AQG service. Until it offers them, activation is not possible and FREE > scans stay off. The contract is described in > [FREE Remote Preview terms acceptance (API)](https://docs.typo3.org/permalink/priebera/typo3-a11y-quality-gate:developer-free-acceptance-api@2.1). FREE results are kept on the AQG service only for a limited time, described in its privacy information. This is independent of the frontend scan history kept in TYPO3 (**Settings > Scan history**). ## Licensed frontend scans {#usage-remote-scans-licensed} With an active Trial, PRO or Agency licence both scan scopes are available: a site scan that crawls the site within the page budget of the plan, and a single-page scan of one selected TYPO3 page. The scope of each run is recorded and shown in the scan history. Additional features become available: - screenshots of the scanned pages, - mapping of findings back to TYPO3 records, if the AQG frontend markers are active (see [Site settings (site sets)](https://docs.typo3.org/permalink/priebera/typo3-a11y-quality-gate:configuration-site-settings@2.1)), - scan history with comparison between scans, - new and resolved findings per scan, - a remediation plan grouped by rule, - remote CSV and PDF export. Before the first licensed scan, configure the crawler access as described in [Remote scan access](https://docs.typo3.org/permalink/priebera/typo3-a11y-quality-gate:configuration-remote-access@2.1): scanner token for hidden content, basic authentication for protected environments, excluded URL patterns and priority URLs. ## How a scan is started {#usage-remote-scans-submit} Start a scan with the scan button on the **Frontend scan** tab. The target is always resolved on the server from the selected TYPO3 page; the browser never supplies a scan URL, installation identifier, licence key or access token. Only one remote scan per site can run at a time. A second submit while a scan is active is rejected with a conflict message; wait for the running scan to finish. A single-page scan needs edit access to the page (for a URL without a TYPO3 page: to the site root) and the `showScanNow` permission; a site scan needs edit access to the site root and `showScanAll`. Results follow the same page permissions: page scans are visible to users who can read the page, site scans to users who can read the site root. Comparisons, the regression signal, fix verification and acceptance evidence only pair compatible scans: same site, scope, scan type, language and start URL, and the same kind of scan (a Free Remote Preview is never compared with a licensed scan). A Free Remote Preview result keeps that label after an upgrade: it has no screenshot and no record mapping. ## Verify fix (PRO, Agency) {#usage-remote-scans-verify-fix} On the frontend page detail, each finding offers **Verify fix**. AQG scans that page again and reports the outcome next to the finding: - **Resolved** — the fresh scan of the same language completed, the page loaded, every issue type the scanner reported for it was stored, and the rule is not among them. - **Still present** — the rule is still reported, with the number of occurrences. - **Not verified** — the scan failed or was cancelled, it checked another language, the page did not load or is missing from the result, or fewer issue types were stored for the page than the scanner reported. A finding that is merely absent from incomplete results is never marked resolved. The verification records the scan that decided it. It uses the same scan permission, submit lock and one-scan-per-site rule as **Scan this page**. ## Acceptance evidence (PRO, Agency) {#usage-remote-scans-acceptance} When two compatible scans are compared, the comparison offers the acceptance evidence as PDF and CSV: baseline and current scan dates and coverage, fixed, new, worse and still open findings, the pages that could not be compared, and the limits of automated testing. It is evidence of automated results, not a statement of WCAG conformance. The PDF is not tagged for screen readers; the CSV contains the same evidence, see [PDF exports are not tagged](https://docs.typo3.org/permalink/priebera/typo3-a11y-quality-gate:limitations-pdf@2.1). > [!NOTE] > The crawler requests your site from the public internet. Installations that > are not reachable from outside, or that block unknown user agents, cannot be > scanned remotely.