Overview

WooCommerce Google CSS Sync is a plugin that integrates your WooCommerce store with Google’s Comparison Shopping Services (CSS) API. Its primary goal is to keep your product data up-to-date within Google CSS so that any changes made to your WooCommerce products are quickly and accurately reflected in Google’s systems.

Key features include:

• Automatic Synchronization: Whenever a product is saved or updated in WooCommerce, the plugin automatically pushes the latest product information (including SKU, price, brand, etc.) to Google CSS.
• Manual Synchronization via Metabox: Each product edit page features a metabox button to sync that specific product on-demand, giving you greater control over individual products.
• Bulk Synchronization with WP-CLI: The plugin provides a WP-CLI command that enables you to synchronize all published products in one go—particularly useful for stores with a large product catalog.
• Easy Configuration: An admin settings page lets you add and manage your Google API credentials, along with your Google CSS Account ID, ensuring a straightforward setup process.
• Minimal Impact on Performance: The plugin only triggers synchronization on relevant events (product save/publish) and when you explicitly run the WP-CLI command, helping minimize overhead.

With WooCommerce Google CSS Sync, you can streamline your workflow, ensure data consistency, and reduce manual tasks, helping your products remain accurately listed across Google’s Comparison Shopping Services.

Installation & Activation

1. Prerequisites:

   • A working WordPress installation (recommended version: 5.0 or higher).
   • WooCommerce plugin (recommended version: 4.0 or higher).
   • PHP 7.0 or higher (with cURL enabled).
   • Valid Google API credentials (JSON key file) for accessing the Google CSS API.

2. Download and Upload the Plugin:

   • Option A – WordPress Admin:

     1. In your WordPress dashboard, go to Plugins > Add New.
     2. Click on Upload Plugin and select the ZIP file of “WooCommerce Google CSS Sync”.
     3. Click Install Now, then Activate once the installation is complete.

   • Option B – FTP/Manual Upload:

     1. Extract the plugin ZIP file on your computer.
     2. Upload the extracted folder to the /wp-content/plugins/ directory on your server.
     3. Go to Plugins in your WordPress dashboard and click Activate under “WooCommerce Google CSS Sync”.

3. Post-Activation Steps:

   • Once activated, a new menu item called “CSS Sync” will appear in the WordPress admin menu (or within the WooCommerce settings).
   • Navigate to this settings page to add your Google API JSON credentials and your Google CSS Account ID.
   • Make sure to save these settings so the plugin can authenticate with Google and sync product data successfully.

After these steps, the plugin is ready to automatically sync product data to the Google CSS API whenever products are created, updated, or manually synced.

Configuration

1. Access the Plugin Settings:

   • In the WordPress admin, navigate to CSS Sync (located in the main admin menu).
   • This page contains all the necessary fields for configuring your Google CSS integration.

2. Add Google API JSON Credentials:

   • Obtain the JSON key file from your Google Cloud Console.
   • Copy and paste the entire JSON content into the Google API Credentials (JSON) field.
     • Ensure the JSON is formatted properly (with no extra escape characters).

3. Enter Your Google CSS Account ID:

   • In the Google CSS Account ID field, input the account ID associated with your Google CSS account.
   • This value is required to correctly authenticate and send product data to the right CSS account.

4. Save Your Settings:

   • Click Save Settings to store the credentials and account ID in your WordPress database.
   • A confirmation message will indicate that your settings have been saved successfully.

5. Verify Connectivity (Optional):

   • Test the automatic sync by updating or creating a product in WooCommerce.
   • Check your logs or Google CSS dashboard to confirm the product update was received.

Once these configuration steps are complete, your WooCommerce store will be ready to automatically synchronize product data with Google CSS whenever products are added, updated, or synced manually.

Automatic Synchronization (on Product Changes)

Whenever a WooCommerce product is saved or updated, WooCommerce Google CSS Sync automatically sends the latest product details to the Google CSS API. Here’s how it works:

1. Trigger Point:

   • The plugin hooks into save_post_product, a WordPress action that fires when a product is created or updated in WooCommerce.
   • Only published products (with post_status set to publish) and products with a valid SKU are eligible for synchronization.

2. Data Sent to Google CSS:

   • The plugin constructs a product data array that includes key attributes:
     • Title
     • Description
     • SKU (GTIN)
     • Price and Currency
     • Brand
     • Image Link
     • Number of Offers
     • Links (e.g., the product page and “headline offer” link)
   • This data is formatted per Google CSS API specifications and sent via an authenticated HTTP POST request.

3. API Communication:

   • The plugin uses Google’s PHP Client Library to handle authentication.
   • An Access Token is obtained behind the scenes using the JSON credentials you provided in the plugin’s settings.
   • If authentication or communication fails, the plugin quietly aborts to avoid breaking the site; errors can be logged for troubleshooting.

4. Seamless & Timely Updates:

   • Changes such as price adjustments or edited titles are promptly reflected in Google CSS whenever the product is saved.
   • This ensures users see the most up-to-date product information across Google Shopping ads and comparison services.

Because synchronization is automatic, you can continue managing products as usual within WooCommerce without needing any extra steps for ongoing updates to be pushed to Google CSS.

Manual Synchronization (Product Metabox)

For greater control over individual products, WooCommerce Google CSS Sync provides a manual synchronization option directly in the product edit screen:

1. Locate the Metabox:

   • On the Edit Product page in WooCommerce, find the “Google CSS Sync” box (typically on the right side or under the Publish/Update area).

2. Sync Button:

   • This metabox includes a “Sync Product” (or similar) button.
   • Clicking the button initiates a manual sync for the current product.

3. Behind the Scenes (AJAX Request):

   • When you click the button, an AJAX request is sent to your WordPress site.
   • The plugin then processes and sends all relevant product details (SKU, title, price, brand, etc.) to Google CSS.

4. Status Messages:

   • A small status message appears in the metabox area, indicating whether the sync was successful or if an error occurred.
   • If any required product data (e.g., SKU) is missing, the request will fail with a corresponding error message.

5. Use Cases:

   • Immediate Updates: If you’ve made changes to a product and don’t want to wait for the automatic sync, this button ensures updates are pushed right away.
   • Testing & Verification: Useful for verifying your plugin configuration and checking that the data is correctly reaching Google CSS.

This manual sync feature lets you ensure critical product information is always accurate without needing to rely solely on automated triggers.

Bulk Synchronization (WP-CLI)

For stores with a large catalog or those preferring a command-line approach, WooCommerce Google CSS Sync supports bulk synchronization via WP-CLI:

1. Ensure WP-CLI is Installed:

   • WP-CLI is a command-line interface for WordPress.
   • Confirm it is installed on your server by running wp --info in your terminal.
   • If it’s not installed, refer to the official WP-CLI documentation (note: external access may be required).

2. Available Command:

   • The plugin introduces the wc_google_css_sync command with the subcommand sync_all.
   • Full syntax:
      

     wp wc_google_css_sync sync_all

3. What Happens on sync_all:

   • The command retrieves all published WooCommerce products (post_status = 'publish') that have a valid SKU.
   • Each product is processed and synced with the Google CSS API (using the same data fields as the automatic sync).

4. CLI Output:

   • As each product is synced, the command outputs a log line like:

     Synchronized product ID: 123

   • Once the process completes, you’ll see a success message:

     Success: All products have been synchronized.

5. Use Cases:

   • Initial Bulk Upload: Quickly push your entire product catalog to Google CSS after installing the plugin.
   • Periodic Maintenance: Manually run bulk sync to ensure every published product is in sync, especially if you manage a large or frequently updated store.

WP-CLI bulk synchronization provides a fast, scriptable way to keep all your products up to date without relying solely on automatic or single-product manual sync.

Technical Overview

The WooCommerce Google CSS Sync plugin is designed to seamlessly integrate with both WordPress and WooCommerce hooks, sending product data to Google CSS via the Google Content API. Here’s a high-level summary of how the plugin is structured and how it operates:

• Core Logic: Most functionality revolves around detecting when a product is saved or updated (save_post_product) and then dispatching relevant product data (SKU, price, etc.) to Google CSS.
• Manual & Bulk Sync: Beyond automatic updates, the plugin offers a metabox button for single-product sync and a WP-CLI command for bulk operations.
• Configuration & Authentication: A settings page (under CSS Sync in the WordPress admin) stores your Google API credentials and CSS Account ID, enabling secure communication with Google’s servers.
• Error Handling & Logging: If a required field (e.g., SKU) is missing or Google’s API returns an error, the plugin gracefully handles these issues without interrupting the rest of your site. You can check logs or browser console messages (in the case of manual sync) for troubleshooting.

Overall, the plugin leverages standard WordPress actions, filters, and the Google PHP Client library to ensure robust and reliable synchronization of product data.

File Structure

Below is a simplified view of how the WooCommerce Google CSS Sync plugin files are organized. Note that your actual directory might include additional files or folders depending on your development setup:

1. woo-google-css-sync.php (Main Plugin File)

   • Plugin Header & Metadata: Defines the plugin name, description, version, and author.
   • Hooks & Functions:
     • Registers admin menu settings.
     • Implements automatic product synchronization via save_post_product.
     • Defines the metabox for manual product sync.
     • Adds a WP-CLI command for bulk synchronization.
   • Google API Integration:
     • Loads credentials from plugin settings.
     • Authenticates requests to Google CSS using the JSON credentials.

2. vendor/

   • autoload.php:
     • Dynamically includes the required files from the Google API Client library.
   • Google API Libraries:
     • Contains the dependencies installed (commonly via Composer) needed to communicate with the Google CSS API.

3. README.md (Optional)

   • An optional documentation file that may detail installation steps, changelog entries, or general usage instructions for developers.

This layout keeps the plugin self-contained, separating the main plugin logic from third-party libraries, which simplifies updates and maintenance.

Key Functions & Hooks

Below is a high-level overview of the main functions and hooks that power WooCommerce Google CSS Sync. These elements work together to listen for product changes, process data, and communicate with the Google CSS API.

---

1. Admin Menu & Settings

• Hook: admin_menu

  • Function: wc_google_css_sync_admin_menu()
  • Purpose: Adds a new page under the WordPress admin for managing the plugin’s settings (Google API credentials and Google CSS Account ID).

• Function: wc_google_css_sync_settings_page()

  • Called From: wc_google_css_sync_admin_menu()
  • Purpose: Renders the admin settings form, processes updates, and saves credentials/account ID to the WordPress database.

---

2. Automatic Product Synchronization

• Hook: save_post_product

  • Function: wc_google_css_sync_product( $post_ID, $post, $update )
  • Purpose: When a WooCommerce product is saved or updated, this function retrieves the product data (SKU, price, brand, etc.) and initiates the sync process by calling the core function that sends data to Google CSS.
  • Condition: Only fires if the product is published and has a valid SKU.

• Function: wc_google_css_sync_send_product( $cssProduct )

  • Purpose: Performs the actual API call to Google CSS.
  • Process:
    1. Loads the stored JSON credentials and account ID from the database.
    2. Authenticates using the Google PHP Client library.
    3. Prepares a JSON payload with the product data.
    4. Sends a POST request to the Google CSS endpoint.

---

3. Manual Product Synchronization (Metabox & AJAX)

• Hook: add_meta_boxes

  • Function: wc_google_css_sync_add_meta_box()
  • Purpose: Registers a custom metabox on the WooCommerce product edit screen, allowing manual synchronization with a button click.

• Hook: wp_ajax_wc_google_css_sync_manual

  • Function: wc_google_css_sync_manual_handler()
  • Purpose: Handles the AJAX request sent when a user clicks the “Sync” button in the product metabox. It fetches the necessary product data and calls wc_google_css_sync_send_product().

---

4. Bulk Synchronization via WP-CLI

• Class: WC_Google_CSS_Sync_CLI

  • Method: sync_all()
  • Purpose: Fetches all published products with valid SKUs and sends them to Google CSS.
  • Usage: Invoked via the CLI command:
     

    wp wc_google_css_sync sync_all
  • Feedback: Outputs a status message for each product and a final success message once complete.

• Hook: WP_CLI::add_command( 'wc_google_css_sync', 'WC_Google_CSS_Sync_CLI' )

  • Purpose: Registers the custom wc_google_css_sync WP-CLI command with WordPress.

---

Overall, these functions and hooks work in tandem to ensure that your WooCommerce product data is reliably updated in Google CSS—whether automatically on product updates, manually via the product page, or in bulk through WP-CLI.

External Dependencies

WooCommerce Google CSS Sync relies on the following external components to function properly:

1. Google API PHP Client Library

   • Used for authenticating requests and communicating with the Google CSS API.
   • Typically installed via Composer and located in the vendor/ directory.
   • Ensures secure OAuth2 authentication and handles token generation for sending requests.

2. WordPress & WooCommerce

   • The plugin requires a working WordPress installation (5.0 or higher recommended) and the WooCommerce plugin (4.0 or higher recommended).
   • It leverages core WooCommerce hooks for product creation and updates.

3. PHP cURL Extension

   • Most modern WordPress installations include cURL by default.
   • Used under the hood by WordPress’ HTTP API (wp_remote_post) for sending data to Google CSS.

4. WP-CLI (Optional)

   • Required only if you plan to use bulk synchronization.
   • Provides command-line support for syncing all products in one go.

Make sure your server environment meets these dependency requirements to avoid errors or incomplete synchronization.

Troubleshooting & Common Issues

1. Products Not Syncing Automatically

   • Cause: Missing SKU or product not in “Published” status.
   • Solution: Ensure each product has a SKU and is set to publish.

2. Manual Sync Button Not Responding

   • Cause: JavaScript conflicts or disabled AJAX.
   • Solution: Check your browser console for errors and ensure AJAX is enabled on your site.
   • Tip: Temporarily disable other plugins or switch to a default theme to rule out conflicts.

3. Invalid Google API JSON Credentials

   • Symptom: Failed authentication, or “invalid grant” error when sending product data.
   • Solution: Verify your JSON file is copied correctly into the plugin’s settings.
   • Note: Be mindful of newline characters (n) in the private key.

4. Missing or Incorrect Brand Data

   • Cause: Product attribute brand not set, or brand is stored under a different attribute name.
   • Solution: Ensure the attribute slug is brand or modify the plugin code to match your store’s attribute naming. If empty, the plugin defaults to “Ingen brand” or “No brand”.

5. WP-CLI Command Failing or Not Found

   • Cause: WP-CLI not installed or not recognized by the server environment.
   • Solution: Confirm WP-CLI is installed and accessible via terminal. Use the wp --info command to verify.
   • Tip: Check file permissions or PATH issues if the command is not recognized.

6. Timeouts or Slow Performance on Bulk Sync

   • Cause: Large product catalog, slow server, or strict server timeout limits.
   • Solution: Increase PHP’s execution time limit or break up the bulk sync into smaller batches. You can also upgrade your hosting plan if server resources are insufficient.

7. General API Communication Errors

   • Cause: Network or firewall restrictions, incorrect permissions in Google Cloud console, or expired tokens.
   • Solution: Whitelist the plugin’s API calls, verify that your Google Cloud project is set up properly, and ensure that tokens are refreshing correctly.

License

WooCommerce Google CSS Sync is released under the GPLv2 (or later) license, which grants users the freedom to run, study, share, and modify the software under the terms defined by the GNU General Public License version 2.

Key points of the GPLv2 license include:

• You are free to use this plugin for both personal and commercial projects.
• You can modify the source code to suit your own needs.
• If you choose to redistribute the plugin (modified or unmodified), you must do so under the same GPLv2 license terms.

For more details, refer to the official GPLv2 License text.

Contact & Support

For any inquiries, troubleshooting assistance, or to request a quote for custom development services, please reach out to:

Email: info@avgroup.se

We strive to respond to all messages promptly and can provide further guidance, debugging help, or discuss new feature requests as needed.