Proactive nudges

A proactive nudge is a single, dismissible message that offers real help: a coupon your store actually accepts, or store credit the shopper already has. It is off by default, it never fabricates urgency, and the decision to show it is made server side, not in the browser.

This is the one feature in the plugin that is easiest to turn into spam, so the bar is set high on purpose. A trigger such as idling on the page is allowed to choose when to surface a message, but a trigger alone never produces a nudge. There has to be a grounded value signal that exists right now, or the shopper sees nothing.

The server-side gate

A small PHP helper, Fahad_AI_Proactive, owns the decision. It runs on the server where every rule is unit testable, rather than trusting client JavaScript that could be tampered with. The widget receives, at most, a tiny pre-approved config; it can render that config and enforce the frequency cap, but it can never invent a deal.

A nudge is eligible only when every one of these holds:

• The merchant turned it on. The kill-switch defaults to off, so proactive messages are strictly opt-in.
• A real value signal is present right now: an applicable coupon, or a positive wallet balance.
• The per-visitor frequency cap is positive and has not been reached.
• The shopper has not dismissed the nudge in this session.

If any check fails, the server returns an empty config and the widget gets nothing to show. There is no fallback path that lets a nudge slip through without a grounded reason.

Grounded value signals

The helper resolves a single signal, never two stacked messages. It prefers a coupon over store credit, because a store-wide coupon helps any shopper while credit is per account.

• A coupon. The candidates come from the same list_active_coupons data the chat uses. Those codes have already passed every WooCommerce validity gate: published, not expired, within usage limits, and applicable to the cart. A code that appears here is a real, usable deal.
• Store credit. If there is no coupon, the helper checks the logged-in shopper's own wallet balance through the wallet provider. A positive amount is unused credit worth mentioning. A zero or empty balance is not a benefit, so it produces no signal.

When it appears

Triggers choose the moment, never the message. The widget arms a couple of honest, low-friction signals and whichever fires first wins. Opening the chat by any path cancels them, because an engaged shopper does not need an interruption.

• Idle on the page. The default trigger. After a stretch of no interaction, the nudge may surface. This is the calm path that works on every device.
• Exit intent. On pointer-capable desktops, the pointer leaving toward the top of the viewport is the classic leaving signal.
• Returning with a cart. A shopper coming back with items already in the cart is a moment where applicable value is genuinely useful.

None of these fire on page load, and none of them invent value. The signal is grounded on the server before any trigger is armed, so the trigger only decides timing for an offer that already exists.

Frequency cap, dismissal, and memory

The cap bounds how many times a proactive message may appear in a single visit. The default is once per session. Set it to zero to turn proactive messages off without changing anything else.

When a shopper dismisses a nudge, that choice is remembered for the session so it does not reappear. The widget mirrors the server's eligibility check client side and stores the show count plus the dismissal under a stable key in sessionStorage. If storage is blocked by a privacy mode, it degrades to at most once per page rather than looping.

// what the widget remembers, per visitor, under fahad_ai_proactive_v1
{ "shown": 1, "dismissed": false }

The nudge itself is accessible: it is a labelled region announced through a polite live region, both actions are real keyboard-operable buttons, and Escape dismisses it.

No fabricated urgency

The message text is built only from the grounded signal: the real coupon code and its plain description, or the real formatted balance. It states a fact and offers help. It never says hurry, limited time, only a few left, or selling fast. A banned-vocabulary check pins this so scarcity language cannot creep in.

You can use code SAVE10 (10% off) on this order. Want help applying it?
You have $12.00 in store credit. Want to use it on this order?

Turning it on

Open WooCommerce, then Fahad AI, and find the Proactive Assist section.

1. Tick Proactive Nudges to let the assistant offer a real, applicable deal or unused store credit. It is off until you do this.
2. Set Max Nudges Per Visit. One is recommended; zero turns proactive messages off.
3. Save. The nudge will only appear for a shopper when a grounded coupon or positive balance exists at that moment.

What it never does

• It stores nothing about the shopper and feeds nothing to the model. Only a formatted, non-identifying string ever reaches the widget.
• It never shows two nudges at once. One signal is chosen, or none.
• It never invents a coupon, a discount, or a balance. Every value is read from real store data first.
• It never overrides the merchant. The kill-switch is the final word, and it defaults to off.