=== TopPosts for Google Analytics ===
Contributors: itxiplugins
Tags: Top Posts, Google Analytics, Most Read, Most Popular, Most Viewed
Requires at least: 5.9
Tested up to: 7.0
Stable tag: 1.5.0
Requires PHP: 7.2.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

TopPosts for Google Analytics relies on your site's analytics to identify and showcase your website's most visited posts.

== Description ==
TopPosts for Google Analytics allows you to easily retrieve and showcase the most visited posts on your website based upon your site's analytics. Link your site with your GA property using your free account at GATopPosts.com. Start free and upgrade your plan right from your WordPress dashboard whenever you need more — nothing new to download, install, or activate.

### Easy Setup
Press the get API Key button and follow the wizard on our platform to grant viewer access to your Google Analytics account. Link your WordPress site with GATopPosts.com with a simple API key and you're ready to go! No complex configurations or coding required.

### Lightweight & Fast
TopPosts for Google Analytics is built for speed, ensuring it doesn't slow down your website's performance.

### Custom Post Types Support
Display top content from any post type on your WordPress site, not just standard blog posts.

### Content Filtering
Want to see only top posts from the past month, or focus on a specific category? You've got complete control! Refine your top content results with custom filters, save them and use them across your site.

### Customizable Appearance
* Select the Category and Data Type relevant to your results.
* Choose between two presets or customize your own by modifying typography, colors and padding.
* Choose between single or two column layouts.
* Display images as full-width covers or position them left/right for flexible visual presentation.
* Customize badge appearance with overlay numbers on images and custom background colors.
* Add icons next to post titles for enhanced visual appeal.

### Flexible Integration
Integrate seamlessly with WordPress through a dedicated Gutenberg block, a short code, and a widget allowing you to showcase top content anywhere on your site.

### Free Version Limitations
* Supports one Post type only
* Posts are limited to 5
* Single content filter

== External Services ==

This plugin relies on the GATopPosts.com service (https://www.gatopposts.com, API endpoint: https://app.gatopposts.com), operated by the plugin authors, to provide its core features. A free or paid GATopPosts.com account and API key are required — the plugin cannot retrieve your top posts without connecting to this service.

The plugin contacts the service in the following situations:

1. **API key verification** (`POST /scf/validateKey`) — when you save your API key in the plugin settings. Sends your API key and the installed plugin version.
2. **Creating or updating a filter** (`POST /updateFilter`) — when you create or edit a Top Posts filter, including the default filter created on first setup. Sends your API key, the installed plugin version, and the filter configuration (your site URL, selected content types, date range, and language settings).
3. **Retrieving Top Posts results** (`GET /getFilters`, `GET /getFilter`) — when the plugin loads or refreshes your Top Posts lists, both in the WordPress dashboard and on the front end of your site. Sends your API key, the installed plugin version, and the filter ID; the service returns the ranked post data generated from the Google Analytics property you connected on GATopPosts.com.
4. **Deleting a filter** (`POST /deleteFilter`) — when you delete a filter from the plugin settings. Sends your API key, the installed plugin version, and the filter ID.
5. **Plugin version and site status checks** (`GET /version`) — when plugin admin pages load and during throttled background checks. Sends your API key and the installed plugin version.

The plugin does not transmit personal data of your site's visitors. Analytics data is processed by the GATopPosts.com service from the Google Analytics account you explicitly authorize on GATopPosts.com.

Privacy Policy: https://www.gatopposts.com/privacy

== Frequently Asked Questions ==

= Do I need to be a developer to use GA Top Posts? =
Absolutely not! You don’t need to write any fancy queries or even a single line of code to use this plugin. Once you connect and give access to your Google Analytics property, your top content will be retrieved automatically. You can then filter the results according to your needs and feature the content using predefined layout through Gutenberg blocks and widgets.

= Do I need a different plugin to unlock all features? =
No. GA Top Posts is a **single plugin**. Some features are locked by default and are unlocked when you upgrade your plan — there is nothing new to download, install, or activate.

= How do I unlock features? =
Click the **Upgrade** button anywhere inside the plugin — you'll find it in the sidebar and on any locked feature. This opens the subscription wizard directly inside your WordPress dashboard. Follow the on-screen steps to complete your plan upgrade. Once confirmed, the plugin automatically refreshes your plan status and unlocks all features immediately — nothing extra to do.

If features are still locked after upgrading, use the refresh button in the Top Posts Manager or visit the Configuration tab to re-verify your API key.

= Can I customize the appearance of the GA Top Posts Widget? =
Yes. GA Top Posts gives you a wide range of display options:

* **Number of posts** — set how many top posts to show.
* **Separator lines** — toggle dividers between post cards.
* **Content elements** — show or hide post title, excerpt, category, tag, and image.
* **Card style** — choose the overall visual style of each card.
* **Image layout** — display the featured image as a full-width cover above the post, or position it to the left or right of the content.
* **Numbered badge** — show a rank number directly on the post image, with a customisable badge background colour.
* **Title icon** — optionally display an icon alongside the post title.

All options are available in the widget settings, the Gutenberg block inspector, and the Elementor widget panel.

= I have installed the plugin and connected my Google Analytics property. What happens next? =
Upon your first access of the Top Posts Manager tab, a default “Top Posts” filter is automatically created to retrieve data from Google Analytics. You can customize this filter according to your needs.

= Can I display only posts or only pages through GA Top Posts? =
Yes, you can select either posts or pages separately when editing a filter, rather than having one combined option for both.

= Is GA Top Posts compatible with Elementor? =
Absolutely. We’ve added an Elementor widget that allows you to display a filter in a section on your page. It includes similar customization options as those available on the widget page. If you don’t see the widget, please make sure to update to the latest version of GA Top Posts.

= I am using the shortcode to display my top posts. Can I still limit the number of posts to display? =
Yes. When you copy a filter’s shortcode, the limit set for that filter is included as a parameter in the shortcode. You can modify this limit if needed for display purposes.

= How can I manage the display of categories and tags in the plugin? =
On the configuration tab, under “display options per content type”, you can select the content type you are targeting and enable or disable the display of categories and tags.

= How often is the data refreshed from Google Analytics? =
You have the option of refreshing the Google Analytics data every 1 hour, 2 hours, or 6 hours. This can be adjusted from the plugin’s configuration page.

= How can I exclude a post from being displayed in the list of my top posts? =
You can easily exclude any post from being displayed by hovering over it and clicking the “Exclude” button. To include the post again, simply hover over it and click the button once more.

= Is there a way to pin a post to the top of the displayed posts? =
Yes, you can pin a post to the top by hovering over it and clicking the “Pin” button. Similarly, you can unpin it by hovering and clicking the “Unpin” button.

= Which metric from Google Analytics does this plugin use for ranking? =
The plugin tracks page views using the `screenPageViews` metric which is defined by Google as “The number of app screens or web pages your users viewed. Repeated views of a single page or screen are counted. (`screen_view + page_view` events).”  This may not necessarily match up to a page view number you see in Google Analytics dashboard. 

= Can I have multiple widgets and filters on my site? =
Yes. With an upgraded plan, you can create multiple filters with different criteria such as date range, scope (content type), language (if your site is multilingual using the [WPML](https://wpml.org/) Plugin), and the number of items to display. You can also add multiple widgets using these filters.
On the free plan, you can only set one filter, but you can still display it in multiple widgets.

= Can I place different widgets on different pages and locations of my site? =
Yes. You can place widgets in different areas of your site with different options. You can:

- Add a WordPress widget and select the filter you want to display.
- Use the Gutenberg block and choose a filter to show the top posts within post pages.
- Copy the filter shortcode and place it anywhere in your theme or page.

= Can I control what kind of content goes into each widget and filter? =
Yes. Each filter allows you to choose which posts to display. You can select from different post types (e.g., posts, pages, or any custom post type registered on your site) and taxonomies (categories, tags, or any custom taxonomies registered on your site).

= Can I filter down to a specific post type within a certain category or tag? =
Not yet. This feature is on our backlog and may be added in a future release.

= Can I try the full feature set before committing to an upgrade? =
Yes. Reach out to us and we’ll provide you with a 7-day trial code to unlock all features.

= Does GA Top Posts work with Google Analytics 4 (GA4)? =
Yes. GA Top Posts is built exclusively for **Google Analytics 4 (GA4)** and uses the GA4 Data API to retrieve page view metrics. Universal Analytics (UA) properties are not supported, as Google retired Universal Analytics in July 2023.

= What features are locked and what can I unlock by upgrading? =
By default, the plugin lets you get started with one filter showing up to 5 posts of a single post type. It is available for free on [wordpress.org](https://wordpress.org/plugins/topposts-for-google-analytics/).

Upgrading your plan removes those limits and unlocks:

* Unlimited filters and higher post display limits
* All post types and custom post types
* Custom date ranges for analytics data
* Multilingual filtering via WPML
* Priority support

Visit our [website](https://www.gatopposts.com) for full pricing and feature details.

= Can I use a custom date range for the analytics data? =
Yes. When creating or editing a filter, you can choose from preset date ranges (e.g., last 7 days, last 30 days, last 90 days) or use the custom date picker to define a specific start and end date. This lets you rank posts over any period — for example, a particular campaign window or the past calendar year. Custom date ranges are available on all plans.

= Does GA Top Posts affect my website’s page load speed? =
No. GA Top Posts is built to be lightweight and fast. Analytics data is fetched from Google on the server side and cached in your WordPress database, so visitors never trigger a live API call — they always read from the cache. You control how often the cache refreshes (every 1, 2, or 6 hours) from the plugin’s configuration page. Thumbnail images are used instead of full-sized images for faster load times on the frontend.

= Does the plugin support custom post types? =
Yes. With an upgraded plan, any custom post type registered on your WordPress site (e.g., products, recipes, events) appears as a scope option when creating or editing a filter. On the free plan, one post type is supported at a time — you can choose between posts, pages, or any single custom post type, but you cannot combine multiple types in one filter.

= Is the plugin compatible with caching plugins? =
Yes. Because GA Top Posts caches analytics data server-side in the WordPress database, it is compatible with page caching plugins such as WP Super Cache, W3 Total Cache, LiteSpeed Cache, and Kinsta Cache. The frontend widget reads from the database cache and does not make live API calls, so it works correctly even when full-page caching is active.

= Does the plugin support dark mode? =
Yes. The GA Top Posts widget and the admin pages both support dark mode. The plugin respects your site’s colour scheme preference and switches between light and dark themes accordingly, so the widget blends naturally with your site’s design whether visitors are browsing in dark mode or light mode.

= What happens if I deactivate or uninstall the plugin? =
**Deactivating** the plugin hides its widgets from the frontend but leaves all settings and cached data intact. Reactivating restores everything without needing to reconnect your Google Analytics property.

**Deleting (uninstalling)** the plugin removes the plugin files from your server. Your settings and cached data stored in the WordPress database are retained unless you manually delete them. Your site remains connected on the GATopPosts.com platform, so you can reinstall and re-enter your API key to pick up right where you left off.

= Why is "No posts found" showing in my widget? =
The "No posts found" empty state can appear for a few reasons:

* Your Google Analytics property has not collected enough data for the selected date range yet.
* The filter’s scope (post type) or taxonomy criteria do not match any published posts on your site.
* All matching posts have been manually excluded from display.
* The cached data has expired and a fresh fetch from Google Analytics is still pending.

To troubleshoot, open the Top Posts Manager, check your filter settings, and use the refresh button to trigger a new data fetch from Google Analytics.

= Can I display top posts in a two-column layout? =
Yes. GA Top Posts lets you switch between a single-column and a two-column layout directly in the widget, Gutenberg block, or Elementor widget settings. A two-column layout works well in wider content areas, while a single column is ideal for sidebars and narrower spaces.

= Does the plugin support multilingual sites? =
Yes. GA Top Posts integrates with [WPML](https://wpml.org/), the popular multilingual plugin for WordPress. When WPML is active on your site, you can create filters that are scoped to a specific language. The plugin will then retrieve and display top posts in that language only, so each language version of your site shows the most visited content for its own audience.

= Does the plugin support RTL (right-to-left) languages? =
Yes. GA Top Posts fully supports RTL languages such as Arabic and Hebrew. The plugin detects your site’s text direction automatically and adjusts the card layout accordingly — including image positioning, badge placement, and text alignment — so everything renders correctly without any manual configuration.

= What card and image layout options are available for displaying my top posts? =
GA Top Posts offers three image layout options for your post cards:

* **Cover image** — the featured image spans the full width of the card above the title and content.
* **Left image / Right image** — the featured image sits beside the title and excerpt, on the side of your choice.
* **No image** — a text-only card with no featured image.

Within these layouts you can also toggle a numbered rank badge directly on the image and pick a custom badge background colour to match your site’s branding.

= What happens if my Google Analytics account has no data yet? =
If no data has been returned from Google Analytics yet — for example, right after connecting a brand-new property — the plugin will show an empty state to let you know that data is still being retrieved. Analytics data is fetched on the first visit to the Top Posts Manager and then automatically refreshed at the interval you configure in the plugin settings (every 1, 2, or 6 hours). Once Google Analytics has enough traffic data, your top posts will appear automatically.

== Installation ==
1. Upload TopPosts for Google Analytics plugin to your WordPress instance and activate it.
2. Follow the link in the configuration tab to register and access your Dashboard.
3. Follow the instructions to connect your Google Analytics property and grant access to the plugin.
4. Copy your generated API Key from your Dashboard and paste it in the Configuration tab.

== Support ==
For assistance, please visit our Support Page, contact us via email at support@gatopposts.com, or use our live chat support available on our [website](https://www.gatopposts.com).

== Changelog ==

= 1.5.0 =

Release date: 2026-08-08

* New Features
  - One plugin for everyone: the free and premium editions are now a single wordpress.org plugin. Upgrade your plan from inside your WordPress dashboard — no separate download, install, or activation.
  - Automatic migration for existing standalone Premium users: your API key, settings, filters, and premium features carry over on their own, and the legacy Premium plugin is deactivated for you.
  - Redesigned, fully localized settings experience with a cleaner Top Posts Manager and Configuration screens.

* Improvements
  - Legacy Gutenberg blocks and widgets created by older versions continue to work unchanged — existing content is migrated automatically.
  - Clearer upgrade prompts on locked features, including Elementor widgets and the two-column layout.
  - WordPress 7.0 Ready: fully tested and confirmed compatibility with the latest WordPress version.
  - Accessibility, security, and code-quality hardening across the plugin.

* Fixes
  - Restored error handling when deleting a filter fails.
  - Fixed a stuck loading state on the settings page.
  - Fixed popover and card-style display glitches.
  - Resolved wordpress.org plugin-check warnings and false positives.

= 1.4.2 =

Release date: 2026-02-19

* New Features
  - Flexible Image Layouts: You can now position images to the left, right, or as a full-width "Cover" image above your content for a bolder visual impact.
  - Enhanced Badge Styling: Added the ability to display numbered badges directly on images. Includes custom background colors and support for Right-to-Left (RTL) language positioning.
  - Title Icons: New option to display decorative icons next to post titles to grab reader attention.
  - Smart Tag Display: Added automatic "overflow" detection for posts with many tags. Hidden tags are now accessible via a tooltip to keep your layout clean.

* Improvements
  - Performance Boost: Implemented advanced caching for large cover images to ensure faster page load times.
  - WordPress 6.9 Ready: Fully tested and confirmed compatibility with the latest WordPress version.
  - Accessibility: Updated color contrasts to meet WCAG standards, making your content more accessible to all visitors.
  - Editor Experience: Modernized the block architecture for a smoother editing experience in the backend.

* Fixes
  - Stability: Improved compatibility with older and newer PHP versions (7.2.5+).
  - Infinite Scroll: Fixed an issue where infinite scroll would occasionally stall or lag.
  - User Interface: Added clearer notifications if copying text to the clipboard fails.

= 1.4.1 =

Release date: 2025-08-29

* New Features
  - Dark mode support has been added for the widget and page UI, allowing users to switch between light and dark themes.
  - A "Configure" link has been added to the plugin options page for easier access to settings.
  - The "Change API" button is now hidden after a successful API key verification to prevent accidental changes.

* Improvements
  - We've improved the customization options for search result cards, allowing you to select the number of description lines.
  - Thumbnail images are now used instead of full-sized images to improve page load speed on the top posts page and widget.
  - To simplify the display settings, we've removed the Fetch Limit. The Display Limit is now set by default to 5, with a range of 1 to 30. The fetch limit will now be automatically set based on the display limit.
  - You can now choose to hide the date per post type, giving you more control over the display.

* Fixes
  - We've corrected issues with Arabic post alignment when WPML plugin is not active.
  - Mixed results no longer occur for posts that have the same slug but are in different languages.
  - Fixed issue that caused a wrong API update-settings call when a user tried to verify an incorrect API key.
  - We have also resolved a bug where no empty state was shown when there were no posts to display.


= 1.4.0 =

Release date: 2025-04-23

* New Features
  - Enroll, manage and upgrade your site directly from your GA Top Posts plugin.
  - Get instant support without leaving wordpress

* Improvements
  - Minor UI/UX improvements:
     - Reorganized the Configuration screen
     - Added a cog icon to the Top Posts Manager for quick access to Display Options.

* Fixes
  - Customizable cards now display as per configured line numbers on the frontend.

= 1.3.3 =

Release date: 2025-03-25

* Bug Fixes
  - Fixing Elementor widget

= 1.3.1 =

Release date: 2025-03-14

* Improvements
  - UI improvement for Display Options dialog in Search Results card
  - Enhance excerpt display control on the Customizable Card
  - Remove API Key masking when user pastes it
  - Ingest API Key in plugin to trigger verification on Top Posts plugin
* Bug Fixes
  - Resolve data type not showing on Posts Manager page
  - Optimize filter results rendering for compatibility with GTranslate plugin
  - Fix excerpt not displayed for Pages in Top Posts results
  - Correct pinning post functionality

= 1.3.0 =

Release date: 2025-01-20

* New Features
  - Enhance Widget UI with additional display options.
  - Automatically create and display "Top Posts" filter on first access to the plugin page.
  - Separate selection capability for posts and pages in WordPress plugin.
  - Setup an Elementor widget for Top Posts filters.
* Improvements
  - Include filter limit in shortcode parameters for copy action.
  - Enable hide/show functionality for category & tag in display options.
  - Modify frequency options and remove the "Default" label from settings.
  - Include plugin version in request headers.
  - Increased options for selecting frequency of data refresh from Google Analytics
* Bug Fixes
  - Resolve issue where plugin reset does not clear data and save functionality fails.

= 1.2.6 =

* Release date: 2025-01-13
* Bug Fixes:
  - Fixed a bug causing errors when saving filters if the homepage URL is among the top data.

= 1.2.5 =

* Release date: 2025-01-12
* Bug Fixes:
  - Fixed a bug causing errors when saving filters.

= 1.2.4 =
* Release date: 2025-01-10
* Improvements:
  - Add custom start and end date input fields for the date range picker.
  - Change notifications UI for enhanced user experience.
  - Improve the functionality of the refresh button for better efficiency.
* Bug Fixes:
  - Resolved an issue where selecting the same language displayed an incorrect reset button.
  - Fixed a problem where excluded content settings reset after updating the Top Posts plugin.
  - Addressed a UI error occurring when a filter page is deleted.
* New Features:
  - Optimize API calls by implementing the `nextGASync` header check.


= 1.2.3 =

Release date: 2024-12-09

- Strip HTML Entities from Descriptions, tags and Titles
- Fix label name for post name in display options modal
- Show Custom Date Range option in Date Range popover
- Enable Free Version Users to Select and Change Post Type Display Options Without Locking
- Disable Future Dates in Date Range Picker Popover
- Fix Popover is not closing after clicking outside
- Start sending supported_languages with the updateFilter API call
- Handle the different cases of sending the language field with updateFilter API

= 1.2.2 =

Release date: 2024-12-04

Fixed toggle filter disabling issue for non-existent pages.
Improved reset button functionality.
Cleaned up unnecessary placeholder in the rich text editor.
Corrected language tag redirection in Top Posts Widget.
Resolved empty state display when adding new filters.
Set default values for Scope and Language in filters.
Optimized language parameter handling without WPML.
Adjusted visibility of reset button for default filters.    

= 1.2.1 =

Release date: 2024-11-29

Enhancements:
Made titles in the Top Posts Widget clickable.
Enhanced Free Plugin Version to support post type selection.
Merged posts and pages into a unified scope selection.
Added page privacy toggle to the Top Posts Plugin.
Disabled link title feature for private pages, ensuring accurate page status reflections.
Enhanced UI with tooltips and addressed filter page layout inconsistencies.
Bug Fixes:
Optimized the application by eliminating redundant API calls.
Rectified issues with popovers and inaccurate UI filter limit displays.
Ensured top posts shortcode displays post types by default.

= 1.1.5 = 

Release date: 2024-10-22

Resolved an alignment issue in the widget editor page when viewed in RTL Language.
Enhanced the Fancy Card to display the entire title if an image is not available.
Fixed an issue where post types were not being displayed on the frontend page.
Updated the filter manager page to reflect changes made in the Top Posts block for better accuracy and usability.

= 1.1.4 = 

Release date: 2024-10-14

Implemented wp_enqueue functions for JavaScript and CSS to ensure proper inclusion and management of scripts and styles.
Added a unique prefix to all functions and classes to prevent potential conflicts with other plugins or themes.
Enhanced security by adding protection against direct file access for all PHP files.
Renamed the main plugin file to maintain consistency with WordPress file-naming conventions.

= 1.1.3 =

Release date: 2024-10-11

Filter Management: Introduced a Filter Info Component to manage filter slug, title, and subtitle efficiently.
UI and UX Enhancements: Updated the UI for the Top Posts Manager page, and introduced a rich text editor for filter descriptions.
Performance Boost: Improved performance on both the frontend and manager pages by implementing cached results and optimizing API calls.

= 1.1.2 =

Release date: 2024-09-12

Add a skeleton loader for TopPosts block while loading content.
Add subtitle for API Key section in configuration page.
Enhancements and bug fixes

= 1.0.0 =

Release date: 2024-05-05

Initial release of TopPosts for Google Analytics Plugin.
Integration with Google Analytics Reporting API.
Widget and shortcode support.
Basic filter and refresh functionality.


== Upgrade Notice ==
= 1.5.0 =
Free and Premium are now one plugin on wordpress.org. Upgrading is seamless: your API key, settings, filters, and widgets carry over automatically, and any legacy Premium install is deactivated for you. Recommended for everyone.

= 1.4.2 =
Major visual enhancements: cover image layouts, badge customization, and image positioning. Includes WordPress 6.9 compatibility, Block API v3 upgrade, and security improvements. Highly recommended upgrade.

= 1.2.4 =
This update includes enhancements in date range input flexibility, UI improvements, and API optimization that enhance overall user experience and performance. It also addresses certain bugs related to language selection and filter page UI errors.
