=== Designed2Use GA Views ===
Contributors: designed2use, guy1ncognito
Tags: google analytics, ga4, pageviews, views, analytics
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display Google Analytics 4 pageview counts on posts and pages. Recent posts fetch fast; older posts refresh in the background.

== Description ==

Designed2Use GA Views shows the Google Analytics 4 pageview total for a post or page using a simple shortcode. It is built so a visitor's page load is never held up by the slow Google API.

**How it fetches counts (hybrid model)**

* A cached value is shown whenever one is fresh.
* On a cache miss for a **recent** post (published within your live-fetch window), the count is fetched live with a short, fail-fast timeout over a narrow date range (the post's publish date to today) — fast because the query window is small.
* On a cache miss for an **older** post, a background job is queued and the last stored value is shown immediately. The slow, history-heavy query runs off the request path.
* Administrators can force a live refresh of the page they are viewing with `?d2ugav_refresh=1`.

**Features**

* `[d2ugav_pageview]` shortcode, or automatic display appended to post content / Echo Knowledge Base header.
* Settings page for credentials, property ID, live-fetch window, cache duration, label, metric, event name, and post types.
* Optional per-post "legacy baseline" to add historical (e.g. Universal Analytics) views to the live GA4 count.
* Lightweight: talks to the GA4 Data API directly over REST with a self-signed service-account token — no bundled multi-megabyte SDK.

Google Analytics is a third-party service governed by Google's own terms; see https://policies.google.com/privacy and https://marketingplatform.google.com/about/analytics/terms/us/ .

== Installation ==

1. Upload the `designed2use-ga-views` folder to `/wp-content/plugins/`, or install through the Plugins screen.
2. Activate the plugin.
3. In Google Cloud, create or select a project and enable the **Google Analytics Data API** for it (APIs & Services → Library → search "Google Analytics Data API" → Enable).
4. Create a service account, add a JSON key, and download it.
5. In Google Analytics, open Admin → Property access management and grant the service account's email the **Viewer** role on your GA4 property.
6. Go to **Settings → GA Views**, paste the service-account JSON, enter your numeric GA4 Property ID, choose your options, and save.
7. Add `[d2ugav_pageview]` to a post/template, or set **Automatic display** to append it to post content.
8. Optionally click **Refresh counts now** to queue a batch of posts for an immediate background refresh.

**Advanced: keeping the key out of the database**

Instead of pasting the JSON into the settings field, define one of these in `wp-config.php`:

`define( 'D2UGAV_CREDENTIALS_JSON', '{ ...service account json... }' );`
`define( 'D2UGAV_CREDENTIALS_PATH', '/absolute/path/outside/webroot/key.json' );`

**Diagnosing unexpected counts**

If a count is not what you expect, open **Settings → GA Views Diagnostics**, pick a post, and click **Run live test**. It runs a live GA4 report and shows the exact URL it matched, the request, the HTTP status, the rows returned, the computed count, and the raw GA4 response — so you can see immediately whether the issue is a URL mismatch, an event-name mismatch, a date range, or credentials.

For a logged trace of every request (including front-end renders and background refreshes), enable **Debug logging** on the settings page. The trace is written to your PHP error log and never includes credentials or access tokens; turn it off again when finished. The same logging can be forced on site-wide with `define( 'D2UGAV_DEBUG', true );` in `wp-config.php`.

== Frequently Asked Questions ==

= Where is my service-account key stored? =
If you paste it into the settings page, it is stored in the `wp_options` table of your database. The key is never displayed again after saving. For higher security, define `D2UGAV_CREDENTIALS_JSON` or `D2UGAV_CREDENTIALS_PATH` in `wp-config.php` instead — then nothing is stored in the database.

= Does this slow down my site? =
Recent posts make one fast, narrow GA call on the first view after the cache expires (then it is cached). Older posts never call Google on render — they refresh in the background. You can also set the live-fetch window to 0 to push *every* post to the background.

= Why don't counts appear immediately? =
New posts and old posts are refreshed by a background job a few seconds after they are queued. Recent posts populate on their first front-end view. Use **Refresh counts now** to queue a batch right away.

= My counts look low / high. =
Check that the GA4 Property ID is correct, the selected metric/event matches how your site tracks views, and (for very old content) that the fallback lookback window is long enough. Pages are matched by URL using the GA4 `fullPageUrl` dimension.

== Screenshots ==

1. The settings page under Settings → GA Views.
2. A pageview count rendered on a post.

== Changelog ==

= 2.0.0 =
* Complete rewrite for WordPress.org distribution.
* Removed the bundled Google SDK; the GA4 Data API is now called directly over REST.
* Hybrid fetch model: recent posts fetched live with a narrow publish-date window and fail-fast timeout; older posts refreshed in the background via WP-Cron. Page loads never block on the slow API.
* Added a full settings page (credentials, property ID, live-fetch window, cache duration, label, metric, event, post types, display mode).
* Added nonce protection to the editor meta box and escaped all output.
* Added a Diagnostics screen (Settings → GA Views Diagnostics) and an optional debug-logging setting to troubleshoot unexpected counts.
* Clamp the GA4 query start date to the API's minimum so posts published before GA4 existed no longer fail.
* Prefixed all functions/classes/meta and added internationalization.

== Upgrade Notice ==

= 2.0.0 =
First public release. Configure your service account and property ID under Settings → GA Views after activating.
