Google updated its Preferred Sources documentation on August 20, 2026 with a custom interactive button. A publication can load the standard library and declarative control, use the programmatic SDK for a custom button, or send readers to a deeplink. WordPress teams still need to decide where the control belongs, prevent duplicate initialization, allow the script through policy layers, and test the return flow on cached pages.
Use this for WordPress publishers that appear in Google's source preferences tool and want readers to select the whole domain or subdomain as a preferred source from articles, newsletters, and high-value resource pages.
Quick answer
Start with Google's recommended standard integration: load https://news.google.com/swg/js/v1/publisher.js asynchronously in the document head and place a div with the google-add-preferred-source-btn attribute near a genuine reader relationship control. Test light and dark themes, browser-language behavior, consent and CSP policy, cache MISS and HIT HTML, mobile return navigation, and a deeplink fallback to https://www.google.com/preferences/source?q=handlwp.com. Only domains and subdomains are eligible, so do not submit /blog as the source.
What to check first
- Confirm the root domain appears in Google's source preferences search before shipping a control.
- Choose the standard declarative button unless a custom interface or application milestone truly requires manual initialization.
- Load the publisher library once in the document head and verify cached templates do not inject duplicate script or button instances.
- Place the control where readers have enough context to trust the publication, then test keyboard focus, localized labels, mobile return, and blocked-script fallback.
- Record button exposure and outbound initiation without claiming that a browser completed the Google preference flow.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Verify domain eligibility and choose the standard, custom, or deeplink integration. | Confirm the root domain appears in Google's source preferences search before shipping a control. | The page contains one publisher library and one intended control. |
| Load one approved library instance through the WordPress theme or asset pipeline. | Choose the standard declarative button unless a custom interface or application milestone truly requires manual initialization. | The root domain, not the /blog directory, is presented as the source. |
| Add the control to a stable article template location with accessible surrounding context. | Load the publisher library once in the document head and verify cached templates do not inject duplicate script or button instances. | Keyboard, mobile, locale, dark mode, cache MISS, and cache HIT checks pass. |
| Allow the required origin through CSP and test blockers, caches, mobile navigation, and localization. | Place the control where readers have enough context to trust the publication, then test keyboard focus, localized labels, mobile return, and blocked-script fallback. | Analytics records only evidence the site can directly observe. |
Why this usually happens
- A theme and an optimization plugin can both inject the publisher script.
- A client-side route change can mount the declarative element more than once.
- A restrictive Content Security Policy can block news.google.com before the control renders.
- A campaign click handler can replace Google's return flow with an unrelated navigation.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
standard_integration:
library: official publisher.js
control: declarative Google button
theme: light
language: browser default
manual_integration:
mode: manual
trigger: one accessible button
fallback:
type: official deeplink
domain: handlwp.com
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Standard button | Declarative div on one article | Localized control opens and returns |
| Custom button | Manual control attribute and callback queue | One click starts one flow |
| JavaScript blocked | Content blocker or restrictive policy | Deeplink remains usable |
| Cached article | MISS then HIT on mobile | One script and one control |
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Verify domain eligibility and choose the standard, custom, or deeplink integration.
- Load one approved library instance through the WordPress theme or asset pipeline.
- Add the control to a stable article template location with accessible surrounding context.
- Allow the required origin through CSP and test blockers, caches, mobile navigation, and localization.
- Measure initiation separately from completed preference selection and review reader value after launch.
Decision rule
Ship the control only when one interaction opens the official Google flow, the user returns to the same clean article URL, keyboard and mobile behavior pass, and the page still offers a useful fallback when the library is blocked.
Production verification checklist
- The page contains one publisher library and one intended control.
- The root domain, not the /blog directory, is presented as the source.
- Keyboard, mobile, locale, dark mode, cache MISS, and cache HIT checks pass.
- Analytics records only evidence the site can directly observe.
Field notes
- Use synthetic IDs and examples that can be traced from the first request or interaction to the final record.
- Keep a before and after result for every changed setting, package, selector, route, or deployed version.
- Separate user-visible success from internal success so a green interface cannot hide a failed request or inaccessible control.
- Review the evidence again after caches, queues, browser history, and scheduled work have had time to settle.
Questions teams ask during testing
Can this be tested on production?
Use production for read-only checks and one narrow synthetic fixture that cannot charge a card, send real customer email, expose personal data, or change inventory. Run upgrades, package changes, cache changes, and destructive repairs on staging first.
What evidence should the test report keep?
Keep exact versions, UTC timestamps, stable synthetic IDs, expected and actual results, screenshots or response excerpts, the decision owner, rollback point, and final verification. Redact credentials, tokens, customer data, private addresses, and infrastructure details.
How long should the observation window stay open?
Keep it open long enough to include at least one cache cycle, scheduled job cycle, and representative traffic period. For release changes, include both logged-in and logged-out use plus the first real operational handoff.
When is the task complete?
Complete it when the primary user path passes, downstream records reconcile, failure branches are understood, monitoring is active, and an established owner page links to this guide in context.
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, settings, stable fixture IDs, and a reproducible baseline.
- Treating one successful screen as proof that keyboard access, APIs, caches, jobs, reports, analytics, and downstream records agree.
- Testing only an administrator session instead of the devices, roles, networks, consent states, and failure branches customers use.
- Closing the work without a named owner, rollback point, observation window, and contextual incoming link from an established guide.
What to tell the client or owner
Give the site owner the affected versions, exact synthetic fixture, UTC timeline, before and after evidence, cause class, decision, rollback point, unresolved risks, and next review date. State which measurements prove success and which observation window remains open.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, improve WordPress visibility in Google and AI search.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references