=== NudgeAI ===
Contributors: NudgeAI
Donate link: https://nudgeai.in/
Tags: ai, content, optimization, engagement
Requires at least: 5.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 2.6.7
License: GNU General Public License v2.0 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Integrate NudgeAI's AI-powered content enhancement and user engagement tools into your WordPress website.

== Description ==

NudgeAI uses predictive machine learning to identify when a visitor is about to leave a website, and slides in an interactive module to maintain engagement. In this way it provides AI-driven solutions for content monetization and user engagement. This WordPress plugin serves as the integration layer, allowing website owners to enhance content with AI-powered suggestions, implement dynamic user interaction elements, track performance metrics, and manage billing workflows through a secure, token-based authentication system.

Most WordPress site owners struggle with a "leaky bucket" problem, where hard-earned visitors arrive, browse a single page, and vanish within seconds. This phenomenon doesn't just hurt engagement metrics; it actively throttles Ad Revenue (ADR) and diminishes the lifetime value of a reader.

Enter NudgeAI, a WordPress plugin designed to solve the bounce rate problem not through aggressive pop-ups, but through predictive behavioral science. It offers a sophisticated, AI-driven approach to session extension.

It uses a lightweight machine learning layer that analyzes micro-behaviors: scrolling speed, cursor hesitation, and dwell time patterns. Instead of waiting for the exit, the AI predicts it approximately 3 seconds before it happens. This "Golden Window" allows the site to intervene while the user is still in a passive browsing state, making them far more receptive to new content.

This approach addresses a common challenge for content publishers, bloggers, news sites, and affiliate marketers: high bounce rates lead to fewer pageviews per session, which directly impacts ad impressions, revenue per mille (RPM), and overall earnings from display networks like Google AdSense, Ezoic, or Mediavine. 

By increasing average pages per session, the plugin aims to create more opportunities for ads to load and be viewed. The resulting uplift in ad revenue is estimated at around 25% in many use cases, though actual results depend on factors like site niche, traffic quality, content type, audience demographics, and ad placement.

Beyond the bounce prediction engine, NudgeAI offers customization options for the triggered modules. Site owners can select from a library of pre-built templates or tweak them to match branding, tone, and goals.

Compatibility is a key strength: it works with most modern WordPress themes and page builders, and it doesn't require server-side resources. Privacy considerations are addressed through standard compliance features, data is anonymized where possible, and no personal information is stored without consent.

The plugin is particularly useful for sites with high traffic but low engagement, such as viral content pages, listicles, or informational articles where users often arrive via search or social media and leave after one page. 

In practice, site owners report gradual improvements: initial tests might show modest gains in session depth, but over weeks of data collection, the AI refines its predictions, leading to more effective nudges.

Overall, NudgeAI represents a practical application of AI in web performance optimization, focusing on retention rather than acquisition.


### Key Features

* **Subtle Modules**: Rather than using a disruptive, full-screen overlay, slides in a compact, interactive module that preserves the reading experience.
* **Contextual Relevance**: Each module is chosen based on its ability to align with the user's current journey, ensuring the intervention feels like a suggestion rather than an interruption.
* **Cognitive Pivot**: The modules are designed to shift the user’s brain from "consumption mode" to "active participation mode."
* **Engagement Variety**: By presenting interactive elements like quizzes, polls, or summarizer, the "Nudge" provides an immediate reason for the user to stay on the site.
* **Conditional Logic**: Smart injection based on post type settings, exclusion rules, and authentication status
* **Content Targeting**: Enable/disable injection on posts, pages, and custom post types
* **Exclusion Rules**: Define specific posts/pages to exclude from NudgeAI processing
* **UI Customization**: Configure themes
* **Analytics Dashboard**: Analytics around URLs processed.

### Security & Privacy

* All API communications use HTTPS
* Tokens are stored securely in WordPress options
* Nonce verification on all forms and AJAX requests
* Input sanitization and validation throughout
* Proper WordPress coding standards compliance
* No PII data is stored
* Webhook token validation — tokens received via the authentication webhook are verified against the NudgeAI API before being stored; already-authenticated sites reject webhook POSTs entirely

### System Requirements

* WordPress 5.0 or higher
* PHP 7.4 or higher (with curl and json extensions)
* MySQL 5.6 or higher (or MariaDB equivalent)
* HTTPS support for secure API communications

== Installation ==

1. Log in to your WordPress admin panel
2. Navigate to **Plugins > Add New**
3. Search for **NudgeAI** in the marketplace.
4. Click **Install Now** and then **Activate**

Alternatively, you can download via Dashboard:

1. Download the plugin zip file from your NudgeAI dashboard
2. Log in to your WordPress admin panel
3. Navigate to **Plugins > Add New**
4. Click **Upload Plugin** and select the downloaded zip file
5. Click **Install Now** and then **Activate**

Alternatively, you can install via FTP:

1. Extract the plugin files to `/wp-content/plugins/nudgeai/`
2. Activate the plugin through the WordPress admin

== Frequently Asked Questions ==

= How do I authenticate with NudgeAI? =

After plugin activation, you'll be redirected to the authentication screen. Click **Authenticate with NudgeAI** to initiate the login process. You'll be redirected to NudgeAI's authorization page in a new tab. Complete login with your NudgeAI credentials, authorize the WordPress plugin, and NudgeAI will post the access token to your configured webhook URL.

= What is the webhook URL? =

Your webhook URL is: `https://yourdomain.com/wp-json/nudgeai/v1/webhook`

This endpoint is intentionally public — it must be reachable by NudgeAI's external servers without a WordPress user session. Security is enforced at the application level:

* **Token validation**: Any token received via this endpoint is immediately verified against the NudgeAI API before being stored. Requests carrying an invalid or fabricated token are rejected with a 401 error.
* **One-time acceptance**: Once your site is authenticated, this endpoint stops accepting new tokens and returns a 400 error for any further POST requests. It only becomes receptive again after you deauthorize or reset the plugin via the Danger Zone tab.

= What exactly does NudgeAI do on my WordPress site? =

NudgeAI monitors visitor behavior in real time and uses AI to predict when someone is likely to leave (bounce) the page, often about 3 seconds before it happens. If a high bounce risk is detected, it automatically displays a lightweight interactive element, like a quick quiz, poll, horoscope, or similar module, to encourage the user to stay longer and explore more pages.

= Will NudgeAI slow down my WordPress site? =

No. NudgeAI is built with a "performance-first" mindset. Similar to Google Analytics, it consists of a single line of lightweight code that loads asynchronously. This ensures that the AI processing happens in the background without affecting your Core Web Vitals or page load speeds.

= What kind of "Nudges" are shown to users? =

Instead of intrusive full-screen ads, NudgeAI introduces interactive modules designed for high engagement. These include:
* **Quizzes and Trivia**: Tailored to your site’s niche.
* **Opinion Polls**: Quick, one-click interactions.
* **Horoscopes or Daily Insights**: Personalized content that sparks curiosity.

= Do I need coding or AI knowledge to set it up? =

Not at all. The integration is designed to be "plug-and-play." If you can copy and paste a snippet into your site’s header (the same way you set up a Facebook Pixel or Google Analytics), you can use NudgeAI. 

= What kind of ROI can I expect? =

While results vary by niche, NudgeAI is specifically designed to move the needle on two core metrics: Pages per Session and Ad Revenue (ADR). On average, users see their pages per session increase from 1.8 to 3.4, which typically correlates to a 25% lift in total ad revenue.

= Is NudgeAI compatible with my theme, ad networks, and privacy laws? =

Yes, it works with most modern WordPress themes and popular ad platforms. For privacy, it anonymizes behavioral data where possible, no personal user info is stored without consent.


== External Services ==

This plugin connects to NudgeAI's external servers to function. By installing and activating this plugin, you agree to NudgeAI's terms of service and privacy policy.

= NudgeAI Platform (nudgeai.in) =

NudgeAI is the AI-powered content enhancement and user engagement platform this plugin integrates with.

**During authentication:** Your WordPress site's domain and webhook URL are sent to `https://nudgeai.in/integrations/authorize` to initiate the OAuth2 login flow. NudgeAI then delivers an access token back to your site via your webhook endpoint. No visitor data is involved at this stage.

**During admin use:** While using the plugin's admin dashboard (Settings, Customization, Modules, Exclusions, Analytics tabs), requests are made to `https://nudgeai.in/api/v1/` using your stored access token to fetch and save configuration data.

= NudgeAI Widget Service (widgets.nudgeai.in) =

The widget delivery service that serves the NudgeAI loader script and powers AI features shown to visitors.

Once authenticated and enabled on posts/pages, a project-specific loader script is injected into each enabled post or page:

`https://widgets.nudgeai.in/integrations/{project-uuid}/loader.js`

When a visitor loads a page with this script, two requests are made to NudgeAI servers:

* **AI model data:** The loader fetches widget configuration and small AI models specific to your project. No visitor personal data is sent.
* **Page content for AI processing:** The current public page URL is sent to NudgeAI. NudgeAI uses this URL to fetch the publicly accessible content of that page (similar to how a search engine crawler works, respecting your site's `robots.txt` rules) in order to generate relevant AI-derived content for the widget. This requires the post or page to be publicly accessible — if the page is private or password-protected, the widget will not be able to read content and NudgeAI features will not function.

The loader script only runs on posts and pages where injection is explicitly enabled, and does not run on excluded content, archives, search results, 404 pages, or the home page.

Terms of Service: https://nudgeai.in/terms
Privacy Policy: https://nudgeai.in/privacy

== Changelog ==

= 2.6.7 =
* Fix: Wrap admin JavaScript bundle in an IIFE and guard against duplicate Vue mounts to avoid WP_DEBUG console errors

= 2.6.6 =
* Fix: Move inline loader CSS to wp_add_inline_style per WordPress.org enqueue guidelines

= 2.6.5 =
* Bugfixes

= 2.6.4 =
* Security: webhook endpoint now validates received tokens against the NudgeAI API before storing; already-authenticated sites block webhook POSTs entirely
* Security: replaced placeholder permission_callback on webhook route with __return_true (WordPress-compliant public endpoint declaration)

= 2.6.3 =
* Added External Services disclosure section to readme.txt for WordPress.org compliance

= 2.6 =
* Initial release to WordPress.org
* Complete OAuth2-style authentication flow
* Admin dashboard with multi-tab navigation
* Script injection with conditional logic
* REST API endpoints for all functionality
* Security features and WordPress coding standards compliance

== Upgrade Notice ==

= 2.6.4 =
* Security update — webhook endpoint now validates tokens against the NudgeAI API before storing

= 2.6.3 =
* Documentation update — no functional changes

= 2.6 =
* Initial release - no upgrade required

== Arbitrary section ==

This plugin is developed by NudgeAI and distributed under the GNU General Public License v2.0 or later. For support, visit the [NudgeAI support portal](https://nudgeai.in/support).
