=== ElPlan Kuchikomi Wall ===
Contributors: elplan
Tags: google reviews, local seo, schema.org, business reviews, structured data
Requires at least: 6.0
Tested up to: 6.9
Stable tag: 2.1.5
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display Google Business Profile reviews, X posts, and manual testimonials on your WordPress site. Note: a Google Places API key is required to show Google Reviews.

== Description ==

**IMPORTANT: A Google Places API key is required to display Google Reviews.** Google provides a free tier (1,000 requests/month), which is sufficient for most sites. Step-by-step setup guide is available at [el-plan.com/kuchikomi-wall/api-guide/](https://www.el-plan.com/kuchikomi-wall/api-guide/). Manual testimonials and X (Twitter) embeds work without any API key.

**Kuchikomi Wall** helps local businesses manage and display Google Business Profile reviews and customer testimonials on their WordPress site. Turn your best reviews into social proof on your website.

= Key Features =

* **Google Reviews Integration** - Connect your Google Business Profile and display customer reviews automatically (cached for performance, Google API compliant)
* **X (Twitter) Embeds** - Add tweet URLs and display them as testimonial cards (no API key required)
* **Manual Testimonials** - Add any testimonial manually from emails, Coconala, direct feedback, or any other source
* **5 Display Templates** - Card Grid, Slider/Carousel, Simple List, Badge, and Floating layouts
* **3 Color Schemes** - Light, Dark, and Auto
* **Unified Dashboard** - Manage all review sources from a single admin interface
* **Setup Wizard** - Initial setup flow for API key, Place ID, and display style
* **Live Preview** - Preview display settings before embedding the widget
* **Gutenberg Block** - Native block included; search "Kuchikomi Wall" in the block inserter
* **Shortcode Support** - Embed anywhere with `[tmnl_kuchikomi_wall]`

= Free vs Pro =

| Feature | Free | Pro |
|---|---|---|
| Google Reviews (1 location) | Yes | Yes |
| X (Twitter) embeds | Yes | Yes |
| Manual testimonials | Yes | Yes |
| 5 display templates | Yes | Yes |
| Gutenberg block | Yes | Yes |
| Multiple locations (multi-store) | No | Yes |
| Schema.org structured data (JSON-LD) | No | Yes |
| Review request QR code | No | Yes |

**Pro is available at [el-plan.com/kuchikomi-wall](https://www.el-plan.com/kuchikomi-wall/) - $3.50/month (billed $35/year).**

= Perfect For =

* Local businesses wanting to show Google Reviews on their website
* Freelancers and consultants showcasing client testimonials
* Salons, clinics, restaurants, and anyone who collects Google Reviews
* Web creators building client sites

= Shortcode Usage =

Basic:
`[tmnl_kuchikomi_wall]`

With options:
`[tmnl_kuchikomi_wall limit="6" template="slider" color="dark" min_rating="4"]`

Parameters:
* `limit` - Number of reviews to display (default: 6)
* `source` - `all`, `manual`, `google`, or `x_embed` (default: all)
* `template` - `card`, `slider`, `list`, `badge`, or `floating` (default: card)
* `color` - `light`, `dark`, or `auto` (default: light)
* `min_rating` - Minimum star rating to display, 1-5 (default: 1)

= Google Reviews Setup =

1. Get a Google Places API key (free tier: 1,000 requests/month)
2. Find your Google Place ID
3. Enter both in **Kuchikomi Wall > Google Reviews > Settings**
4. Reviews are cached for 30 days (Google API compliant)

= Privacy & API Compliance =

* Google review text is **not stored** in your database (compliant with Google's Terms of Service)
* Only Place ID is saved permanently; review data is cached temporarily via WordPress Transients
* X (Twitter) embeds use the free oEmbed API; no authentication or API key required

= Multilingual Ready =

Kuchikomi Wall is translation-ready. A Japanese translation (`ja`) is included. Contributions for other languages are welcome.

= Support =

* Plugin homepage: https://www.el-plan.com/kuchikomi-wall/
* **Google API key setup guide (English):** https://www.el-plan.com/kuchikomi-wall/api-guide-en/
* **Google API key setup guide (Japanese):** https://www.el-plan.com/kuchikomi-wall/api-guide/
* Support forum: Use the WordPress.org support tab

== Installation ==

1. Upload the `elplan-kuchikomi-wall` folder to `/wp-content/plugins/`
2. Activate the plugin through **Plugins > Installed Plugins**
3. Go to **Kuchikomi Wall** in the admin menu
4. Add your first testimonial manually, or connect Google Reviews

= Installing the Premium version =

Before activating the Premium package, deactivate the free **ElPlan Kuchikomi Wall** plugin first. Deactivating the free plugin does not delete your API key, Place ID, display settings, or testimonial data.

Recommended order:

1. Deactivate the free **ElPlan Kuchikomi Wall** plugin
2. Upload the Premium ZIP file
3. Activate **ElPlan Kuchikomi Wall (Premium)**
4. Open the Kuchikomi Wall menu and confirm your settings are still available

== Frequently Asked Questions ==

= Do I need a Google API key? =

A Google API key is required only if you want to display Google Reviews. Manual testimonials and X (Twitter) embeds work without any API key. Google provides 1,000 free API calls per month, which is sufficient for most websites.

= Does this plugin store Google review text in my database? =

No. To comply with Google's Terms of Service, review text is cached temporarily (30 days) using WordPress Transients, not stored permanently. Only your Google Place ID is saved.

= Can I use this without Google Reviews? =

Yes. You can use manual testimonials and X (Twitter) embeds completely free, without any API key.

= How many reviews can I display? =

The free version supports unlimited manual testimonials. Google Reviews returns up to 5 reviews per API call (Google limitation). X (Twitter) embeds support as many tweet URLs as you add.

= Is it compatible with page builders? =

The shortcode `[tmnl_kuchikomi_wall]` works in any area that supports shortcodes, including Elementor, Divi, WPBakery, and the Classic Editor. A native Gutenberg block is also included; search for "Kuchikomi Wall" in the block inserter.

= Is there a Pro version? =

Yes. [Kuchikomi Wall Pro](https://www.el-plan.com/kuchikomi-wall/) ($3.50/month, billed $35/year) unlocks:

* **Schema.org structured data (JSON-LD)** - Automatically outputs structured data (LocalBusiness, AggregateRating) to help search engines understand your business information.
* **Multiple locations** - Connect up to 10 Google Business Profile locations. Perfect for chains, franchises, or agencies managing multiple clients.
* **Review request QR code** - Generate a QR code that links directly to your Google review page.

= Do I need to remove the free version before installing Premium? =

You do not need to delete it, but you must deactivate the free **ElPlan Kuchikomi Wall** plugin before activating **ElPlan Kuchikomi Wall (Premium)**. Your existing settings and data are stored in WordPress and remain available after switching.

== Screenshots ==

1. Dashboard - manage all review sources in one place
2. Card Grid template - clean, responsive review display
3. Slider template - carousel display for testimonials
4. List template - compact vertical layout
5. Gutenberg block - insert and configure from the block editor
6. Admin: Add manual testimonial
7. Admin: Google Reviews settings

== Changelog ==

= 2.1.4 =
* Changed: Removed automatic Free/Premium switching guard; Premium installation now requires manually deactivating the free package first
* Added: Premium installation instructions to the readme

= 2.1.3 =
* Fixed: Keeps the free package admin menu available during normal plugin loading

= 2.1.2 =
* Fixed: Premium activation flow when the free package is already active

= 2.1.1 =
* Fixed: Prevents fatal errors when the free and Premium packages are active at the same time
* Fixed: Version metadata and Stable tag now match the release version
* Improved: readme.txt cleanup for current 2.1.x features and setup notes

= 2.1.0 =
* Added: Single-page admin dashboard with AJAX source management
* Added: Setup wizard and live preview
* Added: Badge and Floating display templates
* Added: Additional widget options for author photo, date, source label, and long text display

= 2.0.8 =
* Updated: Revised Pro feature descriptions to accurately reflect Schema.org structured data (JSON-LD) output capabilities

= 2.0.7 =
* Improved: readme.txt now prominently states that a Google Places API key is required for Google Reviews
* Added: Direct links to API key setup guides (English and Japanese) in the Description and Support sections

= 2.0.6 =
* Added: Freemius SDK integrated - Pro license activation and management
* Added: Pro feature: Multiple Place IDs (up to 10 stores)
* Added: Pro feature: Schema.org JSON-LD structured data (AggregateRating, LocalBusiness, Review)
* Added: Pro feature: QR code generation for Google review requests
* Added: Pro feature: SNS review collection workflow (X/Instagram/Facebook)

= 2.0.5 =
* Added: Free/Pro feature comparison table in the admin dashboard
* Added: "Upgrade to Pro" button with Freemius checkout popup
* Added: Japanese translation bundled (ja.mo/ja.po) with full i18n support
* Fixed: Hardcoded Japanese strings replaced with translatable equivalents
* Fixed: `load_plugin_textdomain()` added to enable bundled translation files
* Improved: API key guide link now automatically switches to the user's language

= 2.0.4 =
* Added: LP link and Freemius checkout JS to the admin dashboard
* Added: API key connection test button with instant feedback
* Added: "How to get an API key" guide link in Google Reviews settings
* Improved: WP.org directory description and FAQ updated

= 2.0.3 =
* Added: "Google API Key Setup Guide" link in the admin dashboard
* Added: "Upgrade to Pro" banner in the admin dashboard
* Added: "Plugin Homepage" and "Support Forum" quick-links in the admin dashboard
* Added: API key connection test button with instant validation in Google Reviews settings
* Added: "How to get an API key" link next to the API key field

= 2.0.2 =
* Fixed: All `$_POST` inputs now sanitized via `array_map('sanitize_text_field', wp_unslash())`
* Fixed: `embed_html` output wrapped with `wp_kses_post()` in all templates
* Fixed: `wp_nonce_url()` wrapped with `esc_url()` in X embed handling
* Fixed: Removed unused `Domain Path` header
* Fixed: `Stable tag` in readme.txt corrected

= 2.0.1 =
* Changed: Main plugin file renamed to `elplan-kuchikomi-wall.php`
* Changed: All shortcodes unified under `tmnl_` prefix (`[tmnl_kuchikomi_wall]`)
* Fixed: All `$_POST/$_GET` inputs sanitized (13 locations)
* Fixed: All `echo` outputs escaped (19 locations)
* Changed: Text domain updated to `elplan-kuchikomi-wall`

= 2.0.0 =
* Rebranded as Kuchikomi Wall
* Added Source Adapter architecture - easily extendable for new review sources
* Added X (Twitter) oEmbed support (no API key required)
* New dashboard UI with per-source management
* Added Slider and List display templates
* Added Dark and Auto color schemes
* Expanded shortcode parameters: `template`, `color`

= 1.0.0 =
* Initial release
* Google Reviews integration with 30-day cache
* Manual testimonial management (add/edit/delete)
* Card Grid display with responsive layout
* Shortcode `[tmnl_kuchikomi_wall]`

== External Services ==

This plugin connects to the following third-party services:

= Google Places API =
* **What it does:** Retrieves customer reviews and business information from Google Business Profile.
* **When data is sent:** Only when you manually trigger a review fetch in the admin dashboard, or automatically via WP-Cron if you enable the scheduled refresh option.
* **What data is sent:** Your Google Place ID and API key (stored locally on your server; sent to Google's API endpoint).
* **Service provider:** Google LLC
* [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms)
* [Google Privacy Policy](https://policies.google.com/privacy)

= X (Twitter) oEmbed API =
* **What it does:** Converts tweet URLs into embeddable HTML cards for display on your site.
* **When data is sent:** When a visitor views a page containing an X embed (the browser contacts Twitter's oEmbed endpoint to render the tweet).
* **What data is sent:** The tweet URL only. No personal user data is transmitted by this plugin.
* **Service provider:** X Corp.
* [X Terms of Service](https://twitter.com/en/tos)
* [X Privacy Policy](https://twitter.com/en/privacy)

== Upgrade Notice ==

= 2.1.4 =
Deactivate the free package before activating the Premium package.

= 2.1.3 =
Compatibility update for normal admin loading after the free package is updated.

= 2.1.2 =
Compatibility update for activating the Premium package after the free package is already active.

= 2.1.1 =
Compatibility update for sites switching from the free package to the Premium package.

= 2.0.0 =
Major update: new dashboard, X (Twitter) support, and display templates. Existing shortcodes continue to work.
