=== TomAwesome Review Widgets ===
Contributors: tomawesome
Donate link: https://ko-fi.com/tomawesome
Tags: reviews, google reviews, testimonials, business profile, healthcare
Requires at least: 6.2
Tested up to: 7.1
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create Google review widgets with your own Business Profile OAuth connection or Places API key. Google setup is required.

== Description ==

TomAwesome Review Widgets lets you connect multiple businesses, synchronize reviews, and create unlimited shortcode widgets with independent layouts and filters.

The plugin connects directly from your WordPress server to Google. It does not use a TomAwesome cloud service, does not send review data to the plugin author, and does not include advertising or paid feature gates.

= Before you install: Google setup is required =

This is not a plugin that displays Google reviews immediately after activation.

TomAwesome does not provide a shared API key, preapproved Google Cloud project, OAuth application, or shortcut around Google's approval process. Before any reviews can appear, the site owner must create their own Google connection, add a Review Source, and synchronize it.

There are two very different setup paths:

* **Google Places API — easier, but limited:** Requires a billing-enabled Google Cloud project, Places API (New), an API key, and a Place ID. It does not require Business Profile API approval or OAuth. Google supplies at most five reviews selected by relevance.
* **Managed Business Profile — advanced, but complete:** Requires an eligible verified Business Profile, a dedicated Google Cloud project, Google's Basic API Access approval, seven enabled Business Profile APIs, Google Auth Platform configuration, and an OAuth web client. It can retrieve the complete paginated review list for locations the connected account owns or manages.

Managed setup is substantially harder and is not a one-click process. Google controls project approval, may take days or longer, and does not guarantee a completion date. Installing this plugin does not begin or accelerate that approval.

If five Google-selected reviews are enough, Places is normally the best starting point. A widget can be switched to a synchronized managed source later.

The complete beginner walkthrough is available after activation under **Review Widgets > Getting Started** and in the project's [installation and Google setup guide](https://github.com/drumhead39/tomawesome-review-widgets/blob/main/docs/INSTALLATION.md).

= Review sources =

* Google Business Profile: for verified locations you own or are authorized to manage. With approved Google API access, all required APIs, and OAuth, the plugin can retrieve the complete paginated review list.
* Google Places API (New): for a public Place ID. Google currently returns at most five reviews selected by relevance.

= Unlimited widget configurations =

* Grid, list, carousel, or single featured review
* Independent business/source selection
* Review count and minimum rating
* Newest, oldest, highest-rated, or randomized order
* Written reviews only
* Expandable long review text
* Reviewer photo and date controls for managed Business Profile sources; Places sources always show available author attribution
* Business rating summary
* Google business-name heading with an optional custom public heading per widget
* Read-all and leave-a-review links
* Responsive desktop, tablet, and mobile columns
* Built-in color, margin, padding, border, and corner-radius controls
* Optional custom CSS classes
* Shortcodes such as `[tomawesome_reviews id="123"]`

= Healthcare Privacy Mode =

Healthcare Privacy Mode is an optional, conservative workflow intended for healthcare and other privacy-sensitive organizations. When enabled for a widget, the plugin:

* Displays only reviews separately approved by an administrator in the Review Library.
* Requires privacy-reviewed display copy.
* Replaces the imported reviewer name with “Google Reviewer.”
* Hides reviewer photos, profile links, exact review dates, and owner responses.
* Suppresses links that could lead visitors directly back to the unsanitized review listing.
* Keeps privacy-reviewed copy separate from the untouched synchronized review.

Healthcare Privacy Mode is not available for Google Places sources because current Google Maps policies require Places reviews to retain author attribution and individual source links.

This feature is a technical safeguard. It is not legal advice, a certification, or a guarantee that a site or organization complies with HIPAA or any other law. Site owners remain responsible for authorizations, policies, risk analysis, workforce training, Google API terms, and legal review.

= Data handling =

API credentials and OAuth tokens are encrypted locally using a key derived from the site's WordPress salts. Imported review content is stored in the site's WordPress database for no more than 30 days and is refreshed during synchronization. Owner responses are not stored.

The plugin adds suggested disclosure text to Tools > Privacy Policy Guide.

= External services =

This plugin connects to Google services only after an administrator configures a Google connection or API key.

For Google Business Profile, the plugin sends the administrator through Google's OAuth consent flow, sends the OAuth client credentials and authorization code to Google's token endpoint, and sends authorized account/location identifiers to Google Business Profile API endpoints. Google returns account, location, aggregate rating, reviewer attribution, rating, review text, and review timestamps. Requests occur when an administrator connects or discovers locations, during a manual synchronization, and during the daily scheduled synchronization.

For Places API (New), the plugin sends the configured Place ID and API key to Google. Google returns Place details, aggregate rating data, reviewer attribution, review text, timestamps, individual review links, and any required third-party data-provider attributions. Requests occur during manual and daily synchronization.

For Places sources, available reviewer photos and profile links are required attribution and are always displayed; a visitor's browser requests those images from Google's URL. For managed Business Profile sources, reviewer photos remain optional and Healthcare Privacy Mode prevents them from loading.

Sites that publish Places API content must maintain publicly accessible Terms of Use and a Privacy Policy that incorporate Google's Terms of Service and Privacy Policy. Places widgets display Google Maps attribution, all available author attribution, returned data-provider attribution, individual review links, and a description of review selection and filtering.

= Why Places widgets contain extra public information =

Google's current Places policies require sites displaying Places reviews to identify Google Maps as the content source, credit authors and returned data providers, give visitors direct access to each source review, and clearly explain how the reviews are selected, filtered, and ordered. The plugin enforces these elements only when a widget uses a Google Places source. They are not advertising and should not be hidden with CSS or removed by a theme override.

The selection/filter notice is placed beside the Google Maps attribution in the widget footer and updates automatically with the widget settings. For example: “Google selects up to five reviews by relevance; this widget shows written 5-star reviews, newest first.”

After Business Profile API access is approved, import and synchronize the managed location as a new Review Source, then edit the widget and select that managed source. The Places selection notice, Google Maps Places attribution, returned provider credit, and individual Places-review links disappear automatically. Managed sources can retrieve the complete review list, make reviewer photos optional, and allow Healthcare Privacy Mode.

Google terms and policies: https://policies.google.com/terms

Google privacy policy: https://policies.google.com/privacy

Business Profile API policies: https://developers.google.com/my-business/content/policies

Places API policies and attribution: https://developers.google.com/maps/documentation/places/web-service/policies

TomAwesome Review Widgets is not affiliated with, sponsored by, or endorsed by Google LLC. Google and Google Business Profile are trademarks of Google LLC.

Source code and development documentation: https://github.com/drumhead39/tomawesome-review-widgets

== Installation ==

1. Upload the plugin ZIP through Plugins > Add New > Upload Plugin, or copy the `tomawesome-review-widgets` directory into `/wp-content/plugins/`.
2. Activate TomAwesome Review Widgets.
3. Read the warning and connection comparison under Review Widgets > Getting Started.
4. Choose one setup path:
   * Easier Places path: create a billing-enabled Google Cloud project, enable Places API (New), create an API key, and find the Place ID.
   * Advanced managed path: create a dedicated Cloud project, apply for Basic API Access, wait for approval, enable all seven Business Profile APIs, configure Google Auth Platform, and create an OAuth Web application.
5. Save the credentials under Review Widgets > Google Connection.
6. Add or import a Review Source.
7. Open that source and select Synchronize now. Importing a managed location does not download reviews automatically.
8. Confirm synchronization succeeds before assigning the source to a widget.
9. Open Review Widgets > Add New, configure and publish the widget, then copy its shortcode into a Shortcode block or page-builder element.

The Getting Started page remains available in the Review Widgets menu. Read the full [beginner installation and Google setup guide](https://github.com/drumhead39/tomawesome-review-widgets/blob/main/docs/INSTALLATION.md) before attempting managed Business Profile setup.

== Frequently Asked Questions ==

= Will reviews appear immediately after I activate the plugin? =

No. Activation does not contact Google or download reviews. You must configure your own Google credentials, create or import a source, and synchronize that source before a widget can display anything.

= Which setup path should a beginner choose? =

Use Places when five Google-selected reviews are enough. It still requires Google Cloud, billing, Places API (New), an API key, and a Place ID, but it avoids Business Profile project approval and OAuth.

Use the managed Business Profile path only when the connected Google account owns or manages the location and you need the complete review list, multiple managed locations, or Healthcare Privacy Mode.

= How long does managed Business Profile setup take? =

There is no guaranteed timeline. The hands-on configuration requires multiple Google Cloud and OAuth steps, and Google separately reviews the Basic API Access application. Approval may take days or longer. TomAwesome cannot submit, approve, check, or accelerate that application for you.

= Does TomAwesome provide the Google project, API key, or OAuth credentials? =

No. Every site operator creates and controls their own Google Cloud project and credentials. Do not share one approved project or its credentials across unrelated businesses without confirming Google's current requirements.

= Can I create more than one widget? =

Yes. Widgets are unlimited and each has its own source, layout, filters, responsive columns, and display controls.

= Can one site display reviews for multiple businesses? =

Yes. One connected Google account can import multiple managed Business Profile locations. You may also configure multiple public Places sources.

= Why does Places mode show only a few reviews? =

The Places API currently returns at most five reviews selected by Google. Use the Business Profile connection for a complete review list from a business you manage.

= Why does my Places widget show a review-selection notice and extra Google Maps links? =

Google's Places policies require a clear description of review selection, filtering, and ordering, along with Google Maps attribution, available author attribution, returned provider credit, and direct access to each individual source review. The plugin places the concise notice beside the Google Maps attribution in the footer and updates it when the widget's count, minimum rating, written-text requirement, or order changes.

These elements are tied to the selected source type and are not optional styling controls. Do not hide them with Custom CSS. Open Review Widgets > Getting Started > Public Places for the full explanation and current policy link.

= What happens when I switch a widget to a managed Business Profile source? =

First import and synchronize the managed location as a new source; do not convert the existing Places source. Edit the widget, select the new managed Business Profile source, and update it. The Places selection notice, Places-specific Google Maps attribution, returned provider credit, and individual Places-review links disappear automatically on the next page load. Reviewer photos become optional, Healthcare Privacy Mode becomes available, and the managed source can retrieve the complete paginated review list.

= Can Healthcare Privacy Mode be used with a Places source? =

No. Current Google Maps policies require Places reviews to retain available author attribution and an individual source link. Select a managed Business Profile source before enabling the privacy workflow.

= Is Healthcare Privacy Mode HIPAA compliant? =

No plugin can certify an organization's HIPAA compliance. The mode enforces privacy-oriented display restrictions and a manual approval workflow, but the site owner must determine whether each use is lawful and consistent with Google terms.

= Does the plugin send data to TomAwesome? =

No. There is no TomAwesome proxy, analytics service, telemetry, advertising service, or paid account. Configured API requests go directly between the WordPress site and Google.

= How often are reviews refreshed? =

WordPress schedules a daily synchronization. Administrators can also synchronize a source manually. WordPress Cron depends on site traffic; sites with low traffic may use a real server cron to call `wp-cron.php`.

= How long are Google reviews stored? =

No more than 30 days. Successful synchronizations renew the local performance cache. Expired content is removed even after a failed synchronization.

= What happens when I uninstall the plugin? =

By default, saved configuration and content remain to prevent accidental data loss. Enable “Delete plugin settings...” under Review Widgets > Google Connection before uninstalling if you want all plugin data removed.

== Changelog ==

= 1.0.0 =

* Promoted the tested plugin to its first stable public release.
* Added an upfront warning that Google setup is required and reviews do not appear immediately after activation.
* Clearly separated the easier, limited Places path from the advanced managed Business Profile path.
* Rewrote the beginner installation guide with click-by-click Google Cloud, billing, API key, Basic API Access, seven-API, OAuth, synchronization, and troubleshooting instructions.
* Clarified that managed-project approval may take days or longer and cannot be granted or accelerated by the plugin.
* Documented that importing a managed location creates an empty source until Synchronize now succeeds.
* Updated the Google Business Profile API list and WordPress 7.1 compatibility metadata.
* Corrected the unused translation-folder header and database-query Plugin Check warnings while preserving synchronization, filtering, and saved privacy approvals.
* Made the existing save-nonce verification explicit for static analysis and expanded regression coverage.

= 0.2.5 =

* Shortened the Places review-selection notice and moved it beside the Google Maps attribution in the widget footer.
* Kept the notice synchronized with the active count, rating, written-text, and order filters.
* Added built-in and packaged documentation explaining every Places-only compliance element.
* Documented how Places-specific elements disappear automatically when a widget switches to a managed Business Profile source.

= 0.2.4 =

* Updated Places output for Google's August 2026 attribution requirements.
* Added Google Maps and returned data-provider attribution.
* Added a direct Google Maps link to every Places review.
* Made available Places author attribution mandatory and added a selection/filter notice.
* Disabled Healthcare Privacy Mode for Places sources.
* Requires one Places source synchronization after upgrade before cached Places content renders.

= 0.2.3 =

* Added per-widget color pickers for the widget, review cards, text, accents, stars, and borders.
* Added visual margin, padding, border-width, and corner-radius controls.
* Existing widgets keep their current styling until custom values are entered.
* Clarified the advanced custom CSS class field.

= 0.2.2 =

* Replaced visitor-facing internal source titles with the synchronized Google business name.
* Added an optional per-widget Public heading override.
* Added a generic Google Reviews fallback so internal source labels are never exposed publicly.

= 0.2.1 =

* Replaced raw Business Profile quota errors with actionable administrator guidance.
* Added direct links to check Google Cloud quota and apply for Basic API Access.
* Distinguished zero quota pending API approval from a temporary rate limit.
* Preserved Google's technical response for troubleshooting.
* Added quota-error handling tests.

= 0.2.0 =

* Added a guided Getting Started screen and live setup progress.
* Added an automatic onboarding redirect after activation.
* Added direct Getting Started and Google Connection links on the Plugins screen.
* Expanded the managed Business Profile setup instructions for first-time Google Cloud users.
* Clarified API-project approval, OAuth test users, redirect URIs, and production readiness.
* Corrected administrator coding-standard issues and release packaging exclusions.

= 0.1.0 =

* Initial developer preview.
* Added multiple Business Profile and Places sources.
* Added unlimited grid, list, carousel, and featured-review shortcode widgets.
* Added encrypted local credential storage and daily/manual synchronization.
* Added 30-day API-content retention enforcement.
* Added Healthcare Privacy Mode with manual privacy-copy approval.
* Added responsive, accessible front-end rendering and reduced-motion support.

== Upgrade Notice ==

= 1.0.0 =

First stable release. Existing credentials, sources, synchronized reviews, widgets, and styling are preserved when updating from 0.2.5.

= 0.2.5 =

Places widgets now use a shorter footer notice. No source synchronization or widget reconfiguration is required.

= 0.2.4 =

Synchronize each Places source once after updating. Until then, its widget is hidden from visitors so older cached content cannot omit Google's current required attribution and individual review links.

= 0.2.3 =

Adds optional visual styling controls directly to the widget editor without changing existing widget designs.

= 0.2.2 =

Internal review-source titles are no longer exposed in public widget summaries. Synchronize each source once to store Google's business name, or set a custom Public heading in the widget.

= 0.2.1 =

Adds clear next steps when Google blocks managed-location discovery because API quota is zero or temporarily exhausted.

= 0.2.0 =

Adds first-run onboarding and a substantially clearer Google Business Profile setup guide. Continue testing on a staging site.

= 0.1.0 =

Developer preview. Test Google connectivity and widget output on a staging site before production use.
