=== AttentionVerify — Attention-Based Video Reward System for WooCommerce ===
Contributors: omniya, freemius
Tags: woocommerce, attention, video, reward, coupon, face-detection, analytics, webhook
Requires at least: 6.0
Tested up to: 6.9
Stable tag: 1.0.0
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

An attention-verified video reward plugin for WooCommerce. Reward customers who genuinely watch your video ads with automatic coupons — powered by real-time AI face detection.

== Description ==

**AttentionVerify by OMNIYA** is a WordPress plugin that uses real-time camera-based attention verification to reward customers for genuinely watching video ads on WooCommerce stores.

= How It Works =

1. Store owner assigns a video to a WooCommerce product from the wp-admin settings page
2. Customer visits the product page — the attention widget appears automatically, no shortcode needed
3. Customer clicks "Start Verification" and watches the video
4. MediaPipe AI monitors face presence, head pose angle, and tab focus in real time
5. On 95%+ verified attention — a unique WooCommerce coupon is automatically generated and displayed to the customer instantly

= Key Features =

**Free Plan**
* Real-time face detection & attention timer
* WooCommerce coupon reward on verified completion
* Basic analytics dashboard
* Anti-cheating detection (tab switch, head pose)
* Firebase Firestore session logging
* AttentionVerify watermark shown

**Pro Plan — $49/mo**
* Everything in Free
* AttentionVerify watermark removed
* Custom reward message and branding
* Coupon expiry control
* Content unlock reward option
* Full analytics dashboard
* Session breakdown and drop-off data
* Anti-cheating detection
* CSV data export
* Priority video loading
* Email support

**Enterprise Plan — Custom pricing**
* White label / full branding
* Custom integrations
* Dedicated support
* Scope and pricing defined via meeting

= Why AttentionVerify? =

* **100% client-side AI** — no camera frames, images, or biometric data stored anywhere
* **Built with GDPR & CCPA principles in mind** — only anonymized behavioral metrics logged, no PII stored
* **Zero code setup** — configure everything from wp-admin, no shortcode needed
* **Firebase powered** — real-time session logging; see the Firestore Security Rules section below for the rules you should apply in your own Firebase project
* **Anti-cheating built-in** — tab switch detection, head pose validation, 1.5s grace buffer for blinks
* **Universal webhook** — works with WooCommerce, Shopify, Magento, or any custom platform
* **Freemius powered** — secure payments, automatic renewals, VAT handling, multi-currency
* **No WooCommerce API keys required** — coupons are created directly via WooCommerce's own native functions, in-process

= Privacy & Security =

* Firebase credentials are stored server-side only — never exposed in browser source
* No camera frames, images, or video stored at any point during or after verification
* Recommended Firestore Security Rules are provided below — apply them in your Firebase project's console
* All demographic data is anonymized behavioral inference only — no PII stored
* Designed to support GDPR/CCPA-compliant deployment — see the note under "Is the plugin GDPR compliant?" below for what this does and doesn't cover

= Firestore Security Rules =

This plugin writes session documents directly to your own Firebase project from the browser (there is no server-side Firebase Admin SDK involved). Apply the following rules in your Firebase Console under **Firestore Database → Rules** — they constrain writes to the exact shape this plugin uses, and prevent a session document from being rewritten once it reaches a terminal state:

`
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

    match /sessions/{sessionId} {
      allow get: if true; // required so the plugin's server-side verification (a public, unauthenticated read) can confirm completion status before issuing a reward
      allow list: if false;

      // hasOnly (not just hasAll) is what actually prevents a client from
      // attaching an extra field — an "image", "face_data", "video", or
      // anything else — alongside the required ones. hasAll alone only
      // checks that the required keys are present; it does not stop
      // additional keys from being included in the same write.
      allow create: if request.resource.data.keys().hasAll(['session_id','ad_id','completion_status','created_at'])
                    && request.resource.data.keys().hasOnly(['session_id','ad_id','completion_status','attention_duration','face_lost_count','head_moved_count','tab_switch_count','fail_count','created_at','updated_at'])
                    && request.resource.data.completion_status == 'in_progress'
                    && request.resource.data.session_id is string
                    && request.resource.data.session_id.size() < 200;

      allow update: if resource.data.completion_status == 'in_progress'
                    && request.resource.data.keys().hasOnly(['session_id','ad_id','completion_status','attention_duration','face_lost_count','head_moved_count','tab_switch_count','fail_count','created_at','updated_at'])
                    && request.resource.data.session_id == resource.data.session_id
                    && request.resource.data.ad_id == resource.data.ad_id
                    && request.resource.data.completion_status in ['in_progress', 'verified', 'failed'];

      allow delete: if false;

      match /events/{eventId} {
        allow create: if request.resource.data.keys().hasAll(['type','message','timestamp'])
                      && request.resource.data.keys().hasOnly(['type','message','timestamp']);
        allow read, update, delete: if false;
      }
    }

    match /publisher_stats/totals {
      allow get: if true;
      allow list: if false;
      allow write: if request.resource.data.keys().hasOnly(['total_seconds_watched','completed_attention','uncompleted_attention','updated_at']);
      allow delete: if false;
    }

    match /{document=**} {
      allow read, write: if false;
    }
  }
}
`

**Important limitation, stated plainly:** these rules constrain the *shape* of what can be written (field names, types, and that a completed session can't be silently reset), but they cannot verify that the attention percentage a browser reports actually came from a real, live camera check — that verification happens entirely client-side, which is an inherent characteristic of any browser-based, unauthenticated verification flow like this one, not something rules alone can close.

= Firebase App Check (Recommended) =

[Firebase App Check](https://firebase.google.com/docs/app-check) is an additional layer on top of the Firestore rules above: it verifies that requests reaching your Firestore database are genuinely coming from your own site's widget, not a scripted client that has simply copied your public Firebase config. This is configured per-project directly in your own Firebase Console — **the plugin cannot enable or enforce it for you**, so it's a setup step you take yourself, once, per Firebase project. Once you've done the Console steps below, this plugin's Settings page has a matching field so the widget can start sending App Check tokens.

**Step 1 — Register a reCAPTCHA v3 site key (free):**

1. Go to https://www.google.com/recaptcha/admin/create
2. Choose **reCAPTCHA v3**
3. Add your site's domain
4. Copy the generated **Site Key** (you'll paste this into the plugin's Settings in Step 3)

**Step 2 — Enable App Check in the Firebase Console:**

1. Open your project in the [Firebase Console](https://console.firebase.google.com)
2. Go to **App Check** in the left-hand menu (under Build)
3. Register your web app, choosing **reCAPTCHA v3** as the provider, and paste in the Site Key from Step 1
4. Under **Firestore Database → App Check**, start in **Monitoring mode** first (not Enforced) — this lets you confirm real traffic is passing before you risk blocking genuine visitors
5. After a day or two of monitoring shows your site's own requests passing normally, switch Firestore to **Enforced**

**Step 3 — Give the plugin the Site Key:**

1. Go to **AttentionVerify → Settings** in wp-admin
2. Under **Firebase Configuration**, paste the same reCAPTCHA v3 Site Key from Step 1 into **App Check Site Key**
3. Save — the widget will automatically start attaching App Check tokens to its Firestore requests

Leaving the App Check Site Key field blank is safe — the plugin functions exactly as before, App Check simply isn't used. This is an *additional* safeguard on top of the Firestore rules above, not a replacement for them; apply both.

= External Services =

This plugin connects to the following external services:

1. **Firebase / Google Firestore** — real-time session logging
   * https://firebase.google.com | Privacy: https://policies.google.com/privacy
   * Used for: storing session data (attention score, dwell time, status)

2. **Freemius** — license management and payment processing
   * https://freemius.com | Privacy: https://freemius.com/privacy
   * Used for: plan licensing, payments, and upgrade flows

3. **MediaPipe (Google)** — client-side face detection
   * https://mediapipe.dev | Privacy: https://policies.google.com/privacy
   * Used for: real-time face and head pose detection — runs entirely in the browser, nothing sent to server

4. **Google Fonts (fonts.googleapis.com)** — typography / font loading
   * https://fonts.google.com | Privacy: https://policies.google.com/privacy
   * Used for: loading DM Sans and DM Mono fonts in the frontend widget
   * Data sent: browser user-agent, IP address (standard CDN request)
   
== Installation ==

= Automatic Installation =

1. Go to **Plugins → Add New** in your WordPress admin
2. Search for **AttentionVerify**
3. Click **Install Now** then **Activate**

= Manual Installation =

1. Download the plugin zip file
2. Go to **Plugins → Add New → Upload Plugin**
3. Upload the zip file and click **Install Now**
4. Activate the plugin

= First-Time Setup (Under 10 Minutes) =

1. Go to **AttentionVerify → Settings**
2. Enter your **Firebase credentials** (API Key, Auth Domain, Project ID, Storage Bucket, Sender ID, App ID)
3. Apply the recommended **Firestore Security Rules** in your Firebase Console (see the "Firestore Security Rules" section above)
4. Go to **Per-Product Video Management** — enter a Product ID and assign a video URL
5. Visit that product page — the attention widget appears automatically. No shortcode needed! WooCommerce coupons are generated natively — no API keys to configure.

== Frequently Asked Questions ==

= Do I need any coding knowledge? =
No. Everything is configured from the wp-admin settings page. No shortcode or code editing required whatsoever.

= Is camera footage stored anywhere? =
No. The plugin uses 100% client-side AI (MediaPipe) running in the browser. No camera frames, images, or video are stored at any point. Only behavioral metrics (attention score, dwell time) are logged.

= What is Firebase and do I need an account? =
Firebase is Google's real-time database service used to log session data. You need a free Firebase account and project. Full setup instructions are in the documentation. Setup takes approximately 5 minutes.

= Which browsers are supported? =
Chrome, Firefox, and Safari on both desktop and mobile browsers. Camera access must be allowed by the user.

= Can I assign different videos to different products? =
Yes. In Settings → Per-Product Video Management, you can assign a unique video URL to each WooCommerce product ID. Supports Media Library uploads and external URLs.

= Does it work with non-WooCommerce stores like Shopify? =
Yes — via the API-Based Reward Integration (Enterprise plan). The plugin sends a standard webhook POST request when attention is verified. Store owners can connect any platform using Make.com (free) or Zapier to receive the signal and trigger their own reward. WooCommerce users get automatic coupon generation with zero extra setup.

= Is the plugin GDPR compliant? =
Designed to support GDPR/CCPA-compliant deployment: no personally identifiable information is stored, only anonymized behavioral metrics are logged, and all demographic data is inferred behaviorally rather than stored as face data or PII. That said, overall compliance also depends on your own store's setup (privacy policy, cookie consent, hosting location, etc.), so we'd recommend having your own legal/compliance review confirm full compliance for your specific business rather than treating this as a blanket guarantee.

= What WooCommerce version is required? =
WooCommerce 8.x or higher is recommended. The plugin creates coupons directly using WooCommerce's own native functions — no REST API or API keys required.

= Can I use YouTube, Vimeo, or self-hosted videos? =
Yes. Any direct video URL works — self-hosted, YouTube, or Vimeo links are all supported.

= How do I upgrade my plan? =
Visit https://attentionverify.com/#pricing to view all available plans and upgrade options.

= What data is sent in the webhook POST request? =
The plugin sends: event type, session ID, product ID, coupon code, attention percentage, site URL, and timestamp — all in standard JSON format compatible with any platform.

== Screenshots ==

1. **Attention verification widget** on WooCommerce product page — face detection active, attention timer counting
2. **AttentionVerify Dashboard** — current plan badge, Firebase status
3. **Analytics Dashboard** — sessions this month, average attention score, dwell time, coupon history, recent sessions table
4. **Settings page** — Firebase configuration, coupon settings, per-product video management

== Changelog ==

= 1.0.0 =
* Initial public release
* Real-time face detection & attention verification using MediaPipe AI (100% client-side)
* WooCommerce coupon reward — auto-generated on verified completion
* Firebase Firestore session logging with secure write rules
* Analytics dashboard — sessions, attention score, dwell time, coupon history
* Anti-cheating detection — tab switch detection, head pose validation, 1.5s grace buffer
* Custom attention threshold configuration
* API-Based Reward Integration — universal webhook support for any e-commerce platform
* Enterprise client management panel
* Freemius licensing — Free, Pro, Enterprise plans with automatic payment and renewal
* Per-product video assignment with live preview in admin
* AttentionVerify watermark on Free plan
* CSV export for session data
* Built with GDPR & CCPA principles in mind — no PII stored, anonymized behavioral data only
* Coupons generated via native WooCommerce functions — no REST API keys required

== Upgrade Notice ==

= 1.0.0 =
Initial release of AttentionVerify by OMNIYA — an attention-verified video reward plugin for WooCommerce.

== External Services ==

This plugin connects to the following external services:

= Firebase (Google) =
Used for storing and retrieving video watch session data.
Firebase JavaScript libraries are bundled locally within this plugin. No Firebase files are loaded from external CDN.
Data sent: Anonymous session data, video watch progress.
Sent when: A user watches a video on the frontend.
Terms of Service: https://firebase.google.com/terms
Privacy Policy: https://policies.google.com/privacy

= MediaPipe (Google) =
Used for real-time face detection and attention tracking. This plugin uses the following MediaPipe libraries loaded from jsDelivr CDN:

* https://cdn.jsdelivr.net/npm/@mediapipe/camera_utils/camera_utils.js
* https://cdn.jsdelivr.net/npm/@mediapipe/face_mesh/face_mesh.js

**Why CDN is required:** The complete MediaPipe Face Mesh package (including WebAssembly binaries and model data files) exceeds 30MB. WordPress.org has a plugin size limit and bundling these binary files locally would make the plugin impractically large. The jsDelivr CDN is a widely used, open-source CDN specifically for npm packages, and is considered acceptable for this type of use case.

**Data privacy:** MediaPipe runs entirely in the user's browser (client-side only). No camera images, video frames, or biometric data are transmitted to any server — including Google's servers. Only behavioral metrics (attention score, dwell time) are processed locally and logged to the site's own Firebase instance.

Data sent: No data is sent to Google or jsDelivr. All processing is local.
Sent when: A user watches a video on the frontend.
Terms of Service: https://developers.google.com/terms
Privacy Policy: https://policies.google.com/privacy

= Freemius =
Used for licensing and plugin updates.
Data sent: Site URL, plugin version, and license key.
Sent when: Plugin is activated or license is verified.
Terms of Service: https://freemius.com/terms/
Privacy Policy: https://freemius.com/privacy/