=== CauseWise Analytics ===
Contributors: razorsoft
Stable tag: 0.4.0
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Loads the CauseWise page-view tracker, records Button block clicks, and shows analytics in WordPress.

== Description ==

CauseWise Analytics adds the hosted CauseWise tracker to public WordPress pages and shows analytics in wp-admin.

Enter the public site key from https://causewise.io, or paste the tracking snippet from the CauseWise dashboard. The plugin reads `data-site` from a snippet and stores only that public key. It then loads `https://causewise.io/causewise.js` through WordPress. The pasted snippet is not saved and is not added to the page. Do not also paste the snippet into the theme, or the page will send two page views.

Dashboard → Home shows a CauseWise Stats widget in the main column: a traffic chart, page views, unique sessions, Today / 7 Days / 30 Days, and Top Pages / Referrers. Four smaller widgets for page views, sessions, traffic, and top pages stay available in Screen Options. Show, hide, drag, and collapse them with the normal Dashboard controls. Configure sets the date range for a smaller widget. Each widget links to the CauseWise Analytics screen.

The CauseWise Analytics screen shows overview counts, the traffic chart, top pages, referrers, sessions, goals, funnels, and recent events for today, the last 7 days, or the last 30 days. A navigation bar at the top jumps to each section on that same screen. Recent events load separately from the charts. Each row shows the event name, type, time, and page path. The list can be filtered, paged, and refreshed without reloading WordPress. It reads the CauseWise API. It does not calculate a second set of metrics. Charts use `@razorsoft/causewise-react` 0.1.2. See `licenses/causewise-react.txt`.

The same charts can be placed on a page with a CauseWise block or a shortcode. Analytics Overview, Traffic Chart, Top Pages, Referrers, Goals, and Recent Events are in the CauseWise block category. The shortcodes are `[causewise_stats]`, `[causewise_traffic]`, `[causewise_top_pages]`, `[causewise_referrers]`, `[causewise_goals]`, and `[causewise_events]`. Each accepts `range` (`today`, `7d`, or `30d`), an optional `title`, and `theme` (`light`, `dark`, or `system`). Top Pages, Referrers, and Recent Events also accept `limit` from 1 to 20. The default range is `7d`.

A page shows a sign-in message to everyone else. The numbers load in the browser only after WordPress confirms the viewer can activate plugins, through the same private analytics route the Dashboard uses. They are not saved in the post, the block, or the shortcode. Event properties are not shown. The management API key stays on the server. Page caches are asked not to store the response when that viewer is signed in.

A management API key is required for that screen. Create one in CauseWise under Settings → API keys. Leave the site ID blank when the key belongs to one site; enter the site ID when it can see more than one. The key is stored in WordPress and is sent only from the server to CauseWise. It is not added to the tracker and it is not included in the admin page.

Select a Button or Buttons block and open the CauseWise panel to record clicks without writing JavaScript. Turn on Enable event tracking, choose an event name such as `button_click`, and add optional properties such as `location` = `hero`. A click sends one event through `window.causewise.track` on the CauseWise script already on the page. The plugin does not add a second analytics backend. Page views stay automatic. Do not name a click `pageview`.

The panel explains what is sent. CauseWise records the event name, the properties you type, and the page address the tracker already includes. It does not read the button text, the link address, or anything typed into a form. Property names that look like emails, passwords, tokens, or other personal data are not saved. If the CauseWise script is missing, the button still works and nothing is sent.

A Buttons block and a Button inside it can both be configured. The click is sent once, for the button. A second copy of the click listener does not send a second event.

The choice is stored with the block. The button’s saved HTML is unchanged, so existing buttons stay valid. Data attributes are added when the page is rendered. Other blocks, classic HTML buttons, and form submissions are not tracked.

Settings use the `activate_plugins` capability so the screens work on WordPress.com installations that do not grant `manage_options`. The block panel uses the WordPress block editor filters and does not require `manage_options`.

== Installation ==

1. Upload `causewise-analytics-0.4.0.zip` in Plugins → Add New → Upload Plugin, or copy the `causewise-analytics` folder into `wp-content/plugins/`.
2. Activate CauseWise Analytics.
3. Open Settings → CauseWise Analytics.
4. Enter the public site key (`cw_` plus 36 hexadecimal characters) or paste the CauseWise tracking snippet, then enable tracking.
5. To view analytics in WordPress, paste a management API key in the Dashboard section of the same screen. Enter a site ID when the key can see more than one site.
6. Remove any CauseWise snippet already pasted into the theme or a header plugin.
7. View a public page while logged out. Confirm one request to `https://causewise.io/api/collect`.
8. Open CauseWise → Analytics, or Dashboard → Home, to see the widgets.

== Frequently Asked Questions ==

= Does this send a page view itself? =

No. `causewise.js` sends one page view when it loads and ignores a second event for the same URL.

= Which key do I paste for tracking? =

The public tracking key, or the whole install snippet from CauseWise. A management API key is rejected in the public site key field. Other scripts are rejected.

= Which key loads the WordPress dashboard? =

A management API key from CauseWise. It stays in the WordPress database. Visitors never receive it.

= How do I track a button click? =

Edit the page, select a Button or Buttons block, and open the CauseWise panel. Enable event tracking and set an event name. Publish the page. The public site must have CauseWise tracking turned on in Settings → CauseWise Analytics.

= What does a button click send? =

One custom event with the name you chose, plus any safe properties you added. The CauseWise tracker also sends the page address, as it does for every event. The button text, the link, and form fields are not added.

= Why was a click not recorded? =

Tracking has to be enabled for the site and for that block, and the event name has to be valid. `pageview` is reserved. A click that happens before `causewise.js` finishes loading is not queued. Clicks in the block editor are not recorded. A preview of the public page can record a click.

= Can I show analytics on a page? =

Yes. Add a block from the CauseWise category, or paste one of the shortcodes in the Classic Editor or a page builder that runs shortcodes. `range` can be `today`, `7d`, or `30d`. Example: `[causewise_stats range="7d" title="This week"]`. Someone who cannot manage CauseWise sees a sign-in message. The numbers are not stored in the page.

= Can I hide a widget? =

Yes. On Dashboard → Home, open Screen Options and uncheck the CauseWise widgets you do not want. Drag the remaining widgets to rearrange them. Collapse a widget from its title bar. Configure changes the date range for a smaller widget. CauseWise Stats changes the range from the buttons inside the widget.

== Changelog ==

= 0.4.0 =
* Adds CauseWise blocks and matching shortcodes for the overview, traffic, top pages, referrers, goals, and recent events.
* Renders those sections with `@razorsoft/causewise-react` 0.1.2 through the existing private analytics route.
* Keeps analytics out of the saved page. Visitors see a sign-in message, and event properties are not included.
* An empty goal list says that no goals have been configured yet.

= 0.3.0 =
* Adds a CauseWise panel to Button and Buttons blocks with event tracking, an event name, and optional properties.
* Sends one click through the existing CauseWise browser tracker. Page views are unchanged.
* Skips personal or secret property values, missing trackers, and a second event for the same click.
* Adds section navigation on the analytics screen, and a paged recent-event list with filters and refresh for checking custom events.

= 0.2.0 =
* Adds a CauseWise Stats widget to Dashboard → Home, plus widgets for page views, sessions, traffic, and top pages.
* Adds a CauseWise Analytics screen with overview cards, a traffic chart, date ranges, top pages, referrers, sessions, and empty, loading, and error states.
* Reads analytics from the CauseWise API. The management key stays on the server.
* Explains empty goals, funnels, recent activity, errors, and permissions in plain language.

= 0.1.0 =
* Initial release. Accepts a public site key or the CauseWise tracking snippet.
