=== NotifReach: Push Notifications ===
Contributors: icodeplugins
Tags: push notifications, firebase, fcm, web push, campaigns
Requires at least: 5.6
Tested up to: 7.0
Requires PHP: 7.2
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Web push notifications via Firebase (FCM): subscribe widget, hook-triggered templates, campaigns with A/B testing and analytics, and a subscriber map.

== Description ==

Send web push notifications to your visitors' browsers and devices using Firebase Cloud Messaging (FCM HTTP v1). Visitors opt in from the frontend with a single toggle button; from there you can notify them manually, automatically in response to any WordPress or plugin event, or through scheduled and recurring campaigns with click and conversion analytics.

Notifications are sent with **your own Firebase project**: you connect your Google OAuth2 client and your Firebase credentials, and your site talks to FCM directly. No third-party sending service sits in between.

= Collecting subscribers =

* **Subscribe/unsubscribe toggle button** via shortcode, reflecting its state with `subscribed` / `unsubscribed` CSS classes.
* **Subscription modal** whose content comes from a dedicated, translatable custom post type ("Subscription modal templates") edited with the native WordPress editor — not indexed on the frontend.
* **All subscription fields are optional and selectable** (phone, email, first name, last name). Only the device token is required; an email is needed only if you want to create or link a WordPress user account.
* **Decoupled feedback messages**: a feedback shortcode you can place anywhere, rendered inline, as native WordPress (Gutenberg) **snackbar toasts**, or both. A JavaScript event is also dispatched for fully custom rendering.
* **Placement and styling** presets for the button and the modal (inline or fixed corners, accent colour, custom classes), with a shortcode builder and live preview in the settings.
* **Works with any form plugin or custom UI**: bind the plugin to your own selectors, or trigger a subscription by dispatching the `icfp:external-subscribe` JavaScript event.
* **Resilient subscriptions**: device tokens are refreshed automatically when they rotate, renewed subscriptions are recovered by the service worker, and dead tokens are pruned.

= Sending notifications =

* **Send screen** with a filterable, paginated **recipient selector** (filter by campaign, location, role, browser/device; select across the whole filtered list) and a rich message composer: title, body, click URL with a page/post picker, icon, badge, hero image, media pickers, live preview, and **action buttons** that each open their own URL.
* **Hook-triggered notifications**: build notification templates (custom post type) bound to any WordPress or plugin action hook, with dynamic placeholders resolved from the hook arguments. A hook knowledge base and a plugin hook scanner help you find the right event.
* **Ready-made templates** are bundled with the plugin and installed on activation. You can also **import a template from a `.json` file** (file picker or drag & drop) from the Push Templates screen; duplicate and near-duplicate templates are detected on import.
* **Multilingual routing**: the subscriber's language is stored and matched to the template language (Polylang / WPML aware).

= Campaigns =

* **Three campaign types**: permanent (send on demand), scheduled (one-off, with optional daily/weekly/monthly recurrence), or triggered by a WordPress event.
* **Audience targeting** by user role, by anonymous visitors (subscribers with no account), by language, or by an explicit list of subscribers.
* **A/B testing**: two variants, a configurable audience split, and optional auto-send of the higher-CTR variant to the rest of the audience.
* **UTM parameters and conversion goals** on the click URL, with click and conversion tracking.
* **Frequency capping**: cap how many pushes a subscriber can receive within a rolling window.
* **Test send** to your own devices before sending to the full audience.

= Measuring and managing =

* **Campaign Analytics**: subscribers, active devices, sent, failed, clicks, CTR, conversions, CVR and unsubscribes, filterable by period, granularity, role and campaign, with CSV export.
* **Subscribers Map**: an optional geolocation captured at subscription time, reverse-geocoded via OpenStreetMap, shown on a map with cascading filters (continent, country, region, postcode, role, browser, device) and a synchronised table.
* **Subscriber preference center**: a frontend page where visitors opt in or out of individual campaigns, subscribe on the spot, or unsubscribe.
* **Passwordless account link**: subscribers with a linked account receive a login link by push (delivered instantly) and, optionally, by email.

= Reliable scheduling =

Scheduled and recurring campaigns run through **WP-Cron**, a **server crontab**, or an external service such as **cron-job.org** calling the plugin's cron endpoint.

= Developer-friendly =

* A public PHP API (`ICodePlugins\FirebasePush\API`) for sending, managing subscribers and reading metrics.
* Authenticated **REST routes** under `icfp/v1` (usable with WordPress Application Passwords) to send notifications, run campaigns, read metrics and manage subscribers.
* Actions and filters throughout — `icfp_subscriber_recorded`, `icfp_save_subscriber`, `icfp_delete_subscriber`, `icfp_rest_capability`, `icfp_webpush_urgency`, and more.
* **Fully translatable** (text domain matches the plugin slug; an up-to-date `.pot` is included in `/languages`; translations are provided via translate.wordpress.org).

= Shortcodes =

* `[icodeplugins_firebase_subscribe_btn]` — the subscribe/unsubscribe toggle button. Optional attributes: `label`, `class`, `parent` (CSS selector to move the button into), `modal` (target a specific modal template by ID or slug).
* `[icodeplugins_firebase_subscribe_feedback]` — the feedback region. Optional attributes: `class`, `parent`, `display` = `inline` (default), `toast`, or `both`.
* `[icodeplugins_firebase_subscribe_assets]` — loads the subscription assets on a page that renders its own custom subscribe UI.
* `[icodeplugins_notification_preferences]` — the subscriber preference center.

= How it works =

Subscriptions are created in the browser using the Firebase JavaScript SDK and a Web Push VAPID key; the resulting FCM device token is stored in your site database, together with whichever optional fields you chose to collect. To deliver a notification, the site authenticates to Google with your own OAuth2 client and calls the FCM HTTP v1 API.

== External services ==

Web push cannot work without a push service: the browser vendors require one, and this plugin uses **Google Firebase Cloud Messaging (FCM)**, with the Firebase project **you** own and configure. Two further services (OpenStreetMap) are used only by the optional Subscribers Map.

This plugin connects to the following third-party services.

**1. Firebase Cloud Messaging — HTTP v1 API (Google)**
Hosts: `https://fcm.googleapis.com`
What it is / why: the push service that actually delivers notifications to your subscribers' browsers. It is required for the plugin to send anything at all.
Data sent, and when: **every time a notification is sent** (manually, by a campaign, or by a hook-triggered template), the plugin sends the message content (title, body, icon/badge/image URLs, click URL, action buttons) together with the recipient's FCM device token. No other subscriber data (email, phone, name, coordinates) is ever sent.
Terms of service: https://firebase.google.com/terms/ — Privacy policy: https://policies.google.com/privacy

**2. Google OAuth 2.0 / Google APIs (Google)**
Hosts: `https://accounts.google.com`, `https://oauth2.googleapis.com`, `https://www.googleapis.com`
What it is / why: authenticates your site to your own Firebase project, so it can call the FCM API above.
Data sent, and when: when the administrator clicks "Connect Google Account" (browser redirect to Google), then whenever an access token must be issued or refreshed before a send, and once more if the administrator clicks "Disconnect" (token revocation). Only your own OAuth client ID/secret and the authorization/refresh tokens are exchanged. No subscriber data is involved.
Terms of service: https://policies.google.com/terms — Privacy policy: https://policies.google.com/privacy

**3. Firebase JavaScript SDK (Google)**
Hosts: `https://firebaseinstallations.googleapis.com`, `https://fcmregistrations.googleapis.com` (contacted by the SDK; the SDK files themselves are bundled with the plugin and served from your own domain).
What it is / why: runs in the visitor's browser and in the service worker to register the browser with FCM and obtain the device token that identifies it.
Data sent, and when: **only when a visitor chooses to subscribe** (and afterwards, if the browser rotates the token). The browser sends your Firebase project identifiers, your Web Push VAPID public key and the browser's push subscription details to Google. Nothing is sent for visitors who never subscribe.
Terms of service: https://firebase.google.com/terms/ — Privacy policy: https://policies.google.com/privacy

**4. Nominatim — reverse geocoding (OpenStreetMap Foundation)**
Host: `https://nominatim.openstreetmap.org`
What it is / why: turns the coordinates a subscriber agreed to share into a readable address (country, region, postcode) for the optional Subscribers Map.
Data sent, and when: **only if a visitor explicitly grants the browser's location permission when subscribing.** The plugin then sends those coordinates (latitude/longitude) and an identifying User-Agent, once per subscriber. If permission is denied — or the browser prompt is dismissed — nothing is collected and nothing is sent. No personal detail (email, phone, name, device token) is sent.
Terms of service: https://osmfoundation.org/wiki/Terms_of_Use — Nominatim usage policy: https://operations.osmfoundation.org/policies/nominatim/ — Privacy policy: https://osmfoundation.org/wiki/Privacy_Policy

**5. OpenStreetMap map tiles (OpenStreetMap Foundation)**
Host: `https://tile.openstreetmap.org`
What it is / why: supplies the background map images of the Subscribers Map screen. (The map library, Leaflet, is bundled with the plugin — it is not loaded from a CDN.)
Data sent, and when: only when an administrator opens the **Subscribers Map** admin screen, and only what any image request carries — the administrator's IP address and browser user-agent. No visitor or subscriber data is sent. No tile is requested on the front end.
Tile usage policy: https://operations.osmfoundation.org/policies/tiles/ — Privacy policy: https://osmfoundation.org/wiki/Privacy_Policy

= Privacy and consent =

* The plugin does **not** track visitors, does not profile them and contains no analytics. Nothing is collected from a visitor who does not subscribe.
* Subscribing is always an explicit action: the visitor clicks the subscribe button and then grants the browser's own notification permission.
* Geolocation is **opt-in twice**: the feature is optional for you, and the visitor must grant the browser's location permission. Refusing changes nothing else — the subscription still works.
* The subscriber's browser/device (from the user-agent) is recorded on your own server to display it in the Subscribers Map. It is never sent to a third party.
* Subscriber details (email, phone, name, coordinates, addresses) are **stored on your own site only**, in your own database, and are deleted with the plugin's data when you uninstall it.
* Clicks and conversions are counted per campaign for your analytics; they are stored on your site only.

Please make sure your site's privacy policy reflects the use of Firebase/Google (and OpenStreetMap, if you enable the Subscribers Map).

== Installation ==

1. Upload the plugin to `/wp-content/plugins/` and activate it.
2. In **NotifReach → Settings → Connection**, enter your Firebase configuration (Project ID, API Key, App ID, Messaging Sender ID, Auth Domain), the Web Push **VAPID key**, and connect your **Google OAuth2** client (Client ID / Client Secret).
3. Under **Settings → Subscription fields**, choose which optional fields to collect.
4. Create at least one **Subscription modal template** (the content shown inside the subscribe modal).
5. Add `[icodeplugins_firebase_subscribe_btn]` to a page or template, and optionally `[icodeplugins_firebase_subscribe_feedback]` near it. (The Integration tab can also render them for you.)
6. (Optional) Create **Push Templates** bound to the hooks you want to trigger notifications, or start from the bundled ones.
7. (Optional) Create a page with `[icodeplugins_notification_preferences]` so subscribers can manage their notifications.

Your site must be served over **HTTPS** for web push to work.

== Frequently Asked Questions ==

= Do visitors have to give a phone number? =

No. Every subscription field is optional and you choose which ones to show. Only the browser's push token is required. An email address is only needed if you want the plugin to create or link a WordPress user account for the subscriber.

= Do I need a Firebase account? =

Yes. Notifications are sent with your own Firebase project and your own Google OAuth2 client, both of which you configure in the Connection settings.

= My scheduled campaigns go out late. Why? =

WP-Cron only runs when someone visits your site, so a low-traffic site fires it late. Use a real server crontab, or an external service such as cron-job.org, to call the plugin's cron endpoint on a fixed schedule.

= Why don't role-targeted campaigns reach most of my subscribers? =

Filtering by user role only reaches subscribers linked to a WordPress account. Most visitors subscribe anonymously, so tick **Anonymous (no user account)** in the campaign's Audience box, alone or alongside roles. Leaving everything unchecked targets all subscribers.

= A notification was accepted but did not appear on Brave (mobile). Why? =

Brave on Android disables Google services for push messaging by default. Enable "Use Google services for push messaging" in Brave's settings, restart Brave, then subscribe again. On iOS, web push requires iOS 16.4+ and the site to be installed to the Home Screen (PWA).

= Does it support translations? =

Yes. The plugin is fully internationalized; a `.pot` file is provided in `/languages`, and translations are handled via translate.wordpress.org. Subscriber and template languages are matched, with Polylang / WPML support.

= Is HTTPS required? =

Yes. Browsers only allow web push and service workers on secure origins.

== Screenshots ==

1. Send screen: filter your subscribers by campaign, location, role or device, select the recipients, and compose a rich notification.
2. A push template bound to a WordPress hook, with the dynamic placeholders that hook exposes.
3. Campaign editor: A/B test with an audience split and auto-send of the winning variant, plus a live preview and action buttons.
4. Campaign analytics: sent, failed, clicks, CTR, conversions and unsubscribes over the period.
5. Subscribers Map: where your subscribers are, with cascading filters and a synchronised table.
6. Connection settings: your own Google OAuth2 client and Firebase project configuration.
7. The subscription modal as visitors see it, with content you edit in the WordPress block editor.
8. Subscriber preference center: visitors turn individual campaigns on or off themselves.

== Changelog ==

= 1.0.0 =
* Initial release: web push notifications via Firebase Cloud Messaging (FCM HTTP v1), sent with your own Firebase project and Google OAuth2 client.
* Frontend subscribe/unsubscribe toggle button and translatable subscription modal (custom post type), with every subscription field optional.
* Feedback shortcode with inline and native WordPress snackbar toast rendering, plus a JavaScript event for custom UIs and form plugins.
* Send screen: filterable, paginated recipient selector and a rich message composer (icon, badge, hero image, action buttons, live preview).
* Hook-triggered notification templates with dynamic placeholders, a WordPress hook knowledge base and a plugin hook scanner. Bundled ready-made templates; import more from a `.json` file, with duplicate detection.
* Campaigns: permanent, scheduled/recurring and event-triggered, with audience targeting, A/B testing, UTM and conversion goals, frequency capping and test sends.
* Campaign Analytics with CSV export, and a Subscribers Map with geolocation and segmentation filters.
* Subscriber preference center and passwordless account link (by push and, optionally, by email).
* Multilingual routing (Polylang / WPML aware), a public PHP API and authenticated REST routes under `icfp/v1`.
