=== Opace Preferred Source Button & Analytics for Google ===
Contributors: opacewebdesign
Tags: preferred-sources, google-search, seo, gutenberg, analytics
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Let readers open Google's Preferred Sources popup from WordPress, with placement controls and honest click analytics.

== Description ==

Need to audit a live implementation first? [Install the free Preferred Source Checker for Chrome](https://chromewebstore.google.com/detail/add-as-preferred-source-b/dnifhlampnjpfigeniaoihblbdegijgp) to check eligibility, the publisher SDK, button rendering and the fallback link.

Add Google's hosted Preferred Sources popup button to a WordPress site. Readers can choose a source in Google's own flow without leaving the page. Custom button presets use Google's direct preferences link if the script cannot load; the native style includes a no-JavaScript fallback.

= Google Preferred Sources for WordPress =

Google Preferred Sources is a reader choice, not a site-wide ranking factor. Google says selected fresh, relevant content may appear more often in Top Stories and receive a preferred badge in AI Overviews and AI Mode. No traffic, AI citation or visibility is guaranteed. See [publisher guidance](https://developers.google.com/search/docs/appearance/preferred-sources) and [click-through finding](https://blog.google/products-and-platforms/products/search/preferred-sources-language-expansion/).

= Add as Preferred Source with a Preferred Source Button =

Give readers a way to add your publication as a Preferred Source in Google's popup. Show a Preferred Source Button in an article, footer, widget or floating banner; custom presets use a direct-link fallback if the script cannot load.

= Preferred Source Button placement and controls =

* Place the button with the Gutenberg block, `[opace_preferred_source]`, `[opace_preferred_source_button]` or `[opsrc_button]` shortcode, classic widget, floating banner, footer, after the first H2 or at the end of content.
* Use Smart placement to rotate five supported positions, then favour the highest measured click-through rate with continued exploration. It measures clicks, not completed additions.
* Show a banner immediately, after scroll depth or delay, or on desktop exit intent. Include returning-visitor and post-click or dismissal suppression controls.
* Choose Google's native button or custom Google-colours and neutral presets, with light, dark and language settings.

= Analytics, eligibility and consent =

* Record anonymous aggregate impressions, clicks and click-through rate for 30 or 90 days, with a per-placement table. Optional GA4/dataLayer events record clicks only.
* Check whether the WordPress address is a domain or subdomain. Google has no eligibility API, so the plugin links to its preferences tool for the owner to check manually. Subdirectories are not eligible.
* Enable GDPR two-click mode to defer the Google script until a reader agrees. Declining uses the direct preferences link.
* Use network activation-safe defaults, per-site settings, optional network settings locking and a documented white-label filter for agency installations.

= External services and privacy =

The plugin loads Google's `publisher.js` from `news.google.com` only on pages where a button or banner renders, so Google's popup can open. The plugin itself sends no personal data to Google. A browser request to Google may involve IP address and browser data under [Google's Terms of Service](https://policies.google.com/terms) and [Privacy Policy](https://policies.google.com/privacy).

The fallback link and eligibility panel point to `google.com/preferences/source` but make no automatic request. The two-click mode prevents a Google request until the reader agrees. Plugin analytics are anonymous aggregate counts in the WordPress database. Optional GA4/dataLayer events send placement, style and popup-or-deeplink mode to an existing setup; the plugin does not load GA4. Browser local storage supports consent, banner suppression and returning-visitor behaviour. A short-lived transient based on an anonymised IP hash rate-limits public analytics events.

= Measurement limit =

Google's SDK has no completion callback, promise or event. Analytics record impressions and clicks on the trigger, never confirmed Preferred Source additions, conversions, rankings or visibility results.

= Related Preferred Sources tools =

* [Preferred Sources suite hub](https://opace.agency/tools/suite/add-as-preferred-source-button-for-google/)
* [Eligibility checker](https://opace.agency/tools/suite/add-as-preferred-source-button-for-google/button-checker/)
* [Button and code generator](https://opace.agency/tools/suite/add-as-preferred-source-button-for-google/button-generator/)
* [Preferred Sources framework packages for React, Vue, Svelte and Astro](https://github.com/OpaceDigitalAgency/add-as-preferred-source-button-for-google)
* [Install the Preferred Source Checker Chrome extension](https://chromewebstore.google.com/detail/add-as-preferred-source-b/dnifhlampnjpfigeniaoihblbdegijgp) or [inspect its source](https://github.com/OpaceDigitalAgency/preferred-source-checker-for-google-chrome-extension)
* [Opace SEO services](https://opace.agency/services/seo/)
* [Opace Digital Agency on GitHub](https://github.com/OpaceDigitalAgency)

Independently developed by Opace Digital Agency and not affiliated with, endorsed by or sponsored by Google.

== Installation ==

1. In your WordPress admin, go to Plugins → Add New and search for "Opace Preferred Source", or upload the plugin ZIP via Plugins → Add New → Upload Plugin.
2. Install and activate the plugin.
3. Complete the setup wizard to review address guidance, choose a button style and enable a placement.
4. Open Preferred Source → Settings to refine placement, triggers, analytics and consent mode.

== Frequently Asked Questions ==

= Can the plugin confirm that my site is eligible? =

No. It checks whether the current address is a supported domain or subdomain format and links to Google's source preferences tool. Google provides no automated eligibility API. Subdirectories such as `example.com/blog` are not eligible.

= Are the analytics confirmed additions or conversions? =

No. Google's SDK does not report whether a reader completed the popup. The plugin records impressions and clicks, and Smart placement uses click-through rate only.

= Does the button improve rankings or guarantee AI Overview visibility? =

No. Preferred Sources is a reader-level personalisation feature. The button is an invitation for readers to use Google's flow; it does not change general rankings or guarantee inclusion in any Google surface.

= What happens if Google's script is blocked? =

Custom button presets open Google's direct source-preferences link. With JavaScript disabled, every style renders a plain link. The native style relies on Google's rendered button when JavaScript is available.

= Does the plugin load data from Google? =

It loads Google's hosted `publisher.js` on pages where a button or banner renders. Enable two-click mode to wait for reader agreement. The script tag also includes `data-opsrc-sdk="1"` for consent-management tools that target scripts by attribute.

= What are the shortcodes? =

Use `[opace_preferred_source]`, `[opace_preferred_source_button]` or `[opsrc_button]`. All accept `style`, `label`, `theme`, `lang` and `align`. Use Preferred Source → Help & shortcodes for examples and developer-filter guidance.

= Can I change the button or white-label the admin? =

Yes. The plugin documents filters including `opsrc_render_button_html`, `opsrc_render_banner_html` and `opsrc_white_label` on its Help & shortcodes screen.

= Is this plugin affiliated with Google? =

No. It integrates Google's publicly documented Preferred Sources button. Google is a trademark of Google LLC.

== Screenshots ==

1. Settings placement tab with Smart placement, automatic placement and supported insertion positions.
2. Settings design tab with button styles, live preview, label and theme controls.
3. Banner trigger settings for immediate, scroll-depth and delayed display, plus audience frequency controls.
4. Advanced consent and Google button language settings.
5. Analytics dashboard with aggregate impressions, button clicks and click-through rate. These are trigger metrics, never confirmed additions.
6. Gutenberg editor with the Preferred Source Button block selected and its block settings visible.
7. Front-end floating banner with the Google-colours button and direct-link fallback.
8. Help & shortcodes reference with setup guidance and measurement limits.

== Changelog ==

= 1.1.5 =
* Bundled an English (UK) translation and now load the plugin text domain from the languages folder.
* Regenerated the translation template from the published 1.1.4 strings.
* Removed line-break tags from the help page and setup wizard markup in favour of list and paragraph elements.
* Updated the activation notice to use the approved plugin name.

= 1.1.4 =
* Aligned the plugin directory, main file and translation domain with the approved `opace-preferred-source-button-for-google` slug.
* Made the existing field-by-field settings sanitisation callback explicit on the registered settings instance.
* Standardised the remaining developer filters and uninstall helpers on the unique `opsrc` prefix before publication.
* Restored WordPress's confirmation notice after settings are saved.

= 1.1.3 =
* Renamed the plugin to Opace Preferred Source Button & Analytics for Google.
* Replaced short internal prefixes with unique `opsrc`/`opace` identifiers and updated the directory installation instructions.

= 1.1.2 =
* Refreshed the directory documentation with the complete shortcode list and clearer multisite and agency deployment guidance; no runtime behaviour changed.

= 1.1.0 =
* Added Smart and content-aware placement, per-placement analytics and the Help & shortcodes screen.

= 1.1.1 =
* Fixed index-permalink REST URLs and block editor dependencies.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.1.5 =
Adds a bundled English (UK) translation, tidies the help page and wizard markup and updates the activation notice wording.

= 1.1.4 =
Aligns the package and translation identifiers with the final WordPress.org slug and clarifies settings sanitisation.
