=== Easy Tracking ===
Contributors: easystorewp
Donate link: https://www.easy-storewp.com/
Tags: ga4, search-console, analytics, tracking, telegram
Requires at least: 5.7
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

GA4 Key Events tracking + daily Search Console & GA4 AI summary report. Optional Telegram delivery.

== Description ==

**Easy Tracking** is a focused analytics tool for WordPress sites that:

1. Tracks 3 high-signal frontend events to GA4 (sign_up / form_submit / cta_click)
2. Pulls GA4 + Search Console data daily via official APIs
3. Optionally generates an AI-written daily summary
4. Optionally pushes the report to Telegram

The big idea: you already have GA4 / Search Console set up. This plugin lets you **read both APIs from inside WordPress admin**, summarize them with AI, and route the result to where you actually read it (Telegram).

= Why this over Site Kit? =

Site Kit is great for in-dashboard widgets. But:

* It does not let you pull data programmatically server-side
* It does not generate AI summaries
* It does not push to Telegram / Slack / Discord
* It tracks logged-in admin views (which Site Kit defaults to disable)

Easy Tracking is a **complement, not a replacement**. Use both.

= Three Key Events tracked =

1. **sign_up** — fired via Measurement Protocol when a WP user registers (works even if user is now logged in, which Site Kit excludes)
2. **form_submit** — fired by JS on form submit (works with WPForms / Contact Form 7 / native HTML forms)
3. **cta_click** — fired by JS on click of `[data-cta]` elements (you tag your buttons)

All 3 events are configured to be marked as **Key Events** in GA4 admin (one-time setup).

= Daily report content =

* GA4: yesterday's users / sessions / pageviews / engagement rate
* GA4: top traffic sources for yesterday
* GA4: conversion event counts (sign_up / form_submit / cta_click)
* GSC: yesterday's clicks / impressions / CTR / position (T-3 single day + 7-day cumulative)
* GSC: top 7-day queries
* AI summary (optional, requires AI plugin like easy-ai-auto)
* Auto-post stats (if easy-ai-auto installed)

= Soft integrations =

* **easy-ai-auto** — provides Telegram bot + LLM gateway. Without it, the plugin still pulls data and shows a preview in admin; with it, daily report auto-pushes to TG with AI summary.
* **easy-schedule** — central cron dashboard sees this plugin's daily report task

= No vendor lock-in =

* All credentials stored in your own `wp_options`
* No phoning home
* No tracking
* All API calls go to Google directly using your credentials
* Uninstall removes everything

== Installation ==

1. Upload zip via Plugins → Add New → Upload Plugin → Activate.
2. Go to **Easy 追蹤** menu.
3. Fill in **GA4 Settings**:
   * Measurement ID + API Secret (for sign_up event tracking via Measurement Protocol)
   * Property ID + Service Account email + Private Key (for daily Data API pulls)
   * Tip: paste the entire `service-account.json` from GCP into the JSON field — it auto-parses.
4. Fill in **GSC Settings**:
   * Site URL (must match Search Console property exactly, including trailing slash)
   * OAuth Client ID / Secret / Refresh Token (see FAQ for how to get refresh_token)
5. Configure **Daily report time** (default 09:00).
6. (Optional) Install [easy-ai-auto](https://wordpress.org/plugins/easy-ai-auto/) for AI summary + Telegram push.
7. Click **Send Test** to verify the pipeline.

== Frequently Asked Questions ==

= How do I get a GA4 service account? =

1. Go to https://console.cloud.google.com/ → IAM & Admin → Service Accounts → Create.
2. Skip role assignment.
3. Open the SA → Keys → Add Key → Create new key (JSON).
4. Download the JSON.
5. Open GA4 → Admin → Property Access → Add user → paste the SA email → Viewer role.
6. Paste the entire JSON into the plugin's "Service Account JSON" field.

= How do I get a GSC OAuth refresh_token? =

GSC requires OAuth user flow (it does not accept service accounts as users).

1. https://console.cloud.google.com/ → APIs → OAuth consent screen → External, Add your email as test user.
2. Credentials → Create Credentials → OAuth Client ID → Web application → Authorized redirect URI: `https://developers.google.com/oauthplayground`.
3. Open https://developers.google.com/oauthplayground → settings (gear) → check "Use your own OAuth credentials" → paste your client_id + secret.
4. Step 1: select "Search Console API v3 → https://www.googleapis.com/auth/webmasters.readonly".
5. Step 2: Authorize APIs → click → consent.
6. Step 3: Exchange authorization code for tokens → copy the **refresh_token**.
7. Paste client_id + client_secret + refresh_token into the plugin.

= Why is the daily report not pushing? =

In order:
1. Easy AI Auto plugin installed and active? (Required for TG)
2. TG bot token + chat_id filled in Easy AI Auto settings?
3. Daily schedule enabled in Easy Tracking settings?
4. wp_next_scheduled returns a future timestamp? (Check `Easy 排程` dashboard.)
5. WordPress cron working? (Some hosts disable wp-cron.)

Hit "Send Test" first to verify the full pipeline manually.

= Can I use a different LLM than what easy-ai-auto provides? =

Currently the AI summary is gated by `easy_ai_auto_call_litellm()`. If you have a different LLM integration plugin that exposes a similar function, you'd need a small bridge — we may add a generic filter `easy_tracking_ai_summary` in a future version.

= Does it work without Telegram? =

Yes. Without easy-ai-auto installed, you can still:
* Track the 3 GA4 events
* Open the admin → click "Preview" to see the daily report inline
* Disable the daily auto-cron (it would just no-op)

You lose: AI summary + auto TG push.

== Screenshots ==

1. Settings status panel (GA4 / GSC / TG configured?)
2. GA4 settings form (Measurement ID / API secret / Service Account)
3. GSC settings form (Site URL / OAuth credentials)
4. Daily report preview
5. Telegram daily report sample

== Changelog ==

= 1.4.0 =
* New: Opt-in telemetry — anonymously share plugin / WP / PHP version stats with the developer. Predefined OFF; user must explicitly opt in via admin notice.
* New: Welcome notice on first activation.
* New: Soft CTA in admin footer linking to https://www.easy-storewp.com/easy-suite/
* Changed: Plugin URI now points to https://www.easy-storewp.com/easy-suite/

= 1.3.0 =
* New: GA4 / GSC settings now configurable via admin (was wp-config-only)
* New: Service Account JSON one-shot paste (auto-extracts client_email + private_key)
* New: Easy Schedule integration (`easy_schedule_register_tasks` filter)
* Removed: Hardcoded GA4 Measurement ID fallback `G-F29VXG5DM4`
* Changed: Daily report prompt neutralized (uses `get_bloginfo('name')` + optional `easy_ai_auto` site role description)
* Changed: Plugin header completed for wp.org submission
* Added: `readme.txt` + `uninstall.php`

= 1.2.1 =
* Easy Schedule integration filter added

= 1.2.0 =
* Daily report with GA4 + GSC + auto-post DB stats
* AI summary via easy-ai-auto / LiteLLM
* Telegram push via easy-ai-auto bot

= 1.0.0 =
* Initial release.

== Privacy ==

Easy Tracking sends:
* User registration events (with WP user_id) to Google Analytics via Measurement Protocol — same data Site Kit / gtag would send
* Daily report queries (date ranges, top URLs, top queries) to GA4 Data API and Search Console API using your service account / OAuth credentials
* Daily report text to Telegram (only if you've configured Telegram via easy-ai-auto)
* Daily report data to your configured LLM endpoint for summarization (only if easy-ai-auto is configured)

Easy Tracking does NOT:
* Send any data to plugin author servers
* Track user behavior beyond the 3 GA4 events you opted into
* Phone home for analytics
* Share data with third parties

All credentials (GA4 service account / GSC OAuth tokens) are stored in your own `wp_options` table. Uninstall removes them.

If you previously stored credentials in `wp-config.php` constants (legacy), those remain in your config file — uninstall does not modify wp-config.php.
