=== ClickClue ===
Tags: session replay, analytics, privacy, usability
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.10.1
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Consent-first session replay, stored on your WordPress server.

== Description ==
See how visitors use your pages. ClickClue records consented website interactions so administrators can replay visits, filter recordings, bookmark useful examples and add review notes. No external analytics account is needed.

Free includes recording, replay, filters, saved filters, bookmarks, notes and all privacy controls. There is no monthly recording allowance, trial period or upgrade requirement for local recording. Your sampling, retention, storage budget and hosting capacity determine how much you keep.

The separate Pro add-on adds a website Clues inbox, page click/scroll heatmaps, structural form insights, custom journeys, before-and-after comparisons, optional visitor feedback, team roles, expiring account-bound invitations, connected-site summaries and administrator JSON exports. Pro features are delivered in the separate add-on, not in this Free package.

== Installation ==
1. Install and activate ClickClue. Open ClickClue > Settings & privacy, or choose Start tutorial for the optional walkthrough.
2. Publish your site-specific privacy policy and select it in WordPress Settings > Privacy. The built-in replay prompt cannot record without a published policy.
3. Review excluded paths, privacy settings and sampling; then enable recording and save. Clear page/CDN caches.
4. For your first test, use 100% sampling in a signed-out window. Choose Allow replay and interact with an included page.
5. Refresh Recordings after a few seconds and choose Watch. Review the actual masking before recording real visitors.

New installations start paused with visitor permission required, 10% sampling, seven-day retention and a 250 MiB replay payload budget. Retention is adjustable from 1 to 365 days and the payload budget from 1 to 10,240 MiB in either edition. These controls do not provide hosting space. Database indexes and backups require additional space.

Signed-in visitors and account, login, administration, order-pay and order confirmation pages are always excluded. Network activation is not supported; activate separately on each site.

= Updating an existing installation =
Use the upgrade ZIP for your existing installation directory. Older ClickClue packages use the directory tracewell. Do not activate a second copy under another directory or uninstall the existing copy to change its name. Update Free first, then the matching Pro add-on if installed, and clear page/CDN caches. Existing recordings and saved settings are preserved.

When upgrading from a release before 0.8.0, the updated replay notice requires fresh positive consent; previous refusals remain respected. Updating from 0.8.0 or 0.8.1 preserves valid choices when the recording scope is unchanged. Changing image approvals or enabling or changing Pro goals or campaigns requires current positive consent; previous refusals remain respected. Site isolation, introduced in 0.6.11, scopes visitor permission and recording authorization to the individual site. An unfinished deletion request from an older version cannot be confirmed automatically. The visitor is told it is unconfirmed, recording stays off, and the site owner can review deletion requests using the existing privacy process. Existing recordings continue to follow retention and administrator deletion.

== Privacy ==
Capture starts only after visitor permission. Typed values are masked before upload. All page text is masked by default. Images are excluded by default. Optional, administrator-approved public/static WordPress library images can be prepared locally and included in new recordings. Private regions still take priority. SVG, canvas, audio, video, embedded frames, hidden inputs and editable content remain excluded. Query strings and fragments are removed. Structural classes and IDs can remain for layout; use data-tw-block or exclusion selectors on regions with sensitive attributes.

Recordings stay in your WordPress database. Free does not send recordings to ClickClue or an external analytics provider. No raw IP addresses are saved by ClickClue. A rotating keyed IP hash is kept temporarily for rate limiting. Existing web server or hosting logs are outside the plugin's control. No request bodies, console logs, customer IDs or order IDs are intentionally collected.

The built-in prompt saves a site-scoped consent choice for 180 days. Do Not Track and Global Privacy Control prevent recording. Revoking consent stops capture, clears unsent data and requests deletion of the current valid session. A failed deletion remains visible as pending; it is not reported as complete. Older sessions remain subject to retention and administrator deletion.

If you use an external consent manager, disable the built-in prompt only after wiring window.ClickClue.grantConsent() and window.ClickClue.withdrawConsent(). Consent is still required. Privacy controls alone do not establish legal compliance for a particular installation.

== Operation ==
Recordings are limited to 30 minutes and 8 MB each. Oversized snapshots and event backlogs stop capture. Uploads use acknowledged batches, bounded retries and deduplication. Unsent events stay in memory, up to 2 MiB, and are cleared on withdrawal. Reconnection can resume a paused recorder with a fresh snapshot. Pending data cannot survive a destroyed browser process. Replay shows interrupted or unconfirmed delivery instead of implying a complete visit. Recording pauses when the chosen storage budget is reached; it resumes when space becomes available.

Cleanup uses hourly WP-Cron plus bounded cleanup during dashboard access and session creation. Configure a real cron trigger on low-traffic sites when timely retention matters. Deactivation preserves data. The optional Delete data when uninstalling setting controls permanent uninstall cleanup.

The player reconstructs a website; it is not desktop video. Media, external fonts, background images and unavailable styles may differ from the live page. Test performance with your hosting and theme.


= Approved public images =
This optional setting is off by default in both editions. An administrator can choose specific public, static WordPress image attachments and confirm that they contain no personal or sensitive content. ClickClue reads eligible local uploads, creates bounded PNG/JPEG copies and stores used copies with the recording. It does not fetch arbitrary visitor image URLs or capture visitor screen pixels. Preparation requires the PHP GD image extension and an eligible local upload. The prepared catalogue is bounded separately from recordings (up to 256 images in named collections, about 46 MiB of encoded image data and URL metadata); Only used copies are loaded with a recording: at most 64 and 2 MiB, counted towards its payload budget. Matching uses up to eight same-origin URL variants per image within a 256 KiB metadata allowance; unmatched images remain placeholders. Private, masked and excluded regions take priority. Removing approval removes stored image copies from existing recordings while preserving other recording events. Exports already downloaded require separate review. Update your site notice and test your exact pages before enabling this option.

= First-use guidance =
The first-visit checklist and contextual Pro-help dismissals are stored only in the current administrator's browser. They do not send setup or upgrade-interest analytics to ClickClue, change recording consent, or limit Free features. Clear or reset the browser-local tutorial to repeat its guidance.

== Development ==
Readable source and a dependency-locked asset build are included. See BUILD.txt and THIRD-PARTY-LICENSES.txt. The tutorial links to the bundled assets/help.html guide; it needs no external documentation account.

== Changelog ==

= 0.10.0 =
* Adds a first-visit checklist with recording readiness, signed-out test guidance and replay review progress.
* Adds three dismissible, contextual links explaining the separate Pro add-on in the bundled guide.
* Keeps setup progress in the current administrator's browser without transmitting usage analytics.
* Preserves existing recording, retention, storage and privacy settings.
* Update Free first, then matching Pro, without uninstalling.

= 0.9.0 =
* Adds acknowledged upload batches, bounded memory-only retries and recovery after temporary disconnection.
* Shows recording completeness in replay; a closed tab or missing batch is not silently labelled complete.
* Updates computed layout in bounded batches for changed and visible elements.
* Organises up to 256 individually approved public images in named collections, with up to 64 used copies and 2 MiB per recording.
* Preserves masking, local storage, existing settings and uncapped monthly Free recording.
* Update Free first, then matching Pro, without uninstalling. Image approval changes and enabled Pro goal/campaign changes require current consent.

= 0.8.1 =
* Keeps tutorial help available inside the installed plugin without an external website.
* Clarifies optional approved images in the settings and suggested privacy-policy wording.
* Applies each site’s uninstall preference when removing ClickClue from a multisite network.
* Update Free first, then the matching Pro add-on. Existing recordings, settings and consent choices are preserved.

= 0.8.0 =
* Adds optional, default-off approved public images to replay, while keeping private regions excluded.
* Preserves more structural layout detail without fetching arbitrary image URLs or external fonts.
* Removes stored approved-image copies when approval is withdrawn; recording events follow normal retention.
* Update Free first, then matching Pro, clear page/CDN caches and renew positive replay consent.


Earlier release history is included in changelog.txt.
