System - Google Preferred Documentation

Overview

System - Google Preferred is a Joomla system plugin that displays a Bootstrap toast notification inviting your site visitors to add your domain as a Google Preferred Source. When a visitor clicks through and adds your site, Google prioritizes your content in their personal search results, Top Stories, and AI-powered search responses.

Requirements

• Joomla 4.x or 5.x
• PHP 8.x
• A domain that Google recognizes as a news/content source (see Finding Your Domain below)

Installation

1. Download the plugin package (.zip file).
2. In your Joomla admin, go to System → Extensions → Install.
3. Upload the zip file and click Install.
4. Go to System → Plugins, search for Google Preferred, and enable it.
5. Open the plugin settings and configure your domain (see below).

Finding Your Domain

Before enabling the plugin, you need to know which domain Google associates with your site. This is not always obvious — Google may recognize example.com but not www.example.com, or vice versa.

To find the correct domain:

1. Open the plugin settings and enter your domain in the Preferred Domain field.
2. Click the Test Preferred Domain link that appears below the field.
3. Google will open a page showing your site's favicon and domain name if it recognizes it.
4. If you don't see your site listed, try removing www. or any subdomain and test again.

If Google doesn't recognize your domain at all, the plugin will still work — but visitors who click through won't see your site listed on Google's preference page. Make sure you have the right domain before going live.

Configuration

The plugin settings are organized into three tabs: Basic, Style, and Toast.

Basic Tab

Preferred Domain The domain Google should recognize — for example, richeyweb.com. Do not include https:// or a trailing slash. Use the test link (described above) to confirm this is correct.

Style Tab

Toast Preview A live preview of your toast appears at the top of this tab. Changes to the fields below update the preview in real time.

Favicon The URL to your site's favicon, used as the icon in the toast header. This is typically favicon.ico (relative to your site root) or a full URL like https://example.com/favicon.ico. Leave blank to show no icon.

Position Where the toast appears on screen. Nine options are available:

Toast Background Class The Bootstrap color class applied to the entire toast. Options: Default (no class), Primary, Secondary, Success, Danger, Warning, Info, Light, Dark.

Toast Button Class The Bootstrap button class applied to the "Add now" button. Options: Primary (default), Secondary, Success, Danger, Warning, Info, Light, Dark.

Toast Width Maximum width of the toast. Accepts CSS values: px, em, rem, or %. Default is 350px. Leave at default unless you need to adjust for your layout.

Toast Tab

Auto Hide Whether the toast automatically disappears after a delay. Default: Yes. If set to No, the visitor must close it manually.

Show Delay How many milliseconds to wait after the page loads before showing the toast. Default: 1500 (1.5 seconds). Increase this if the toast appears before your page has finished rendering visually.

Hide Delay How many milliseconds to wait before the toast auto-hides (only applies if Auto Hide is enabled). Default: 5000 (5 seconds).

Dismiss Days How many days to wait before showing the toast again to a visitor who closed it. Default: 30. The dismissal is stored in the visitor's browser as a cookie — nothing is stored on your server.

How the Toast Behaves

1. The page loads and the toast HTML is embedded as a hidden <template> element.
2. After the Show Delay, the toast is cloned from the template and appended to the page body.
3. The toast appears using Bootstrap's built-in toast animation.
4. If Auto Hide is on, the toast disappears after the Hide Delay.
5. If the visitor closes the toast (via the × button or auto-hide), a cookie is set. The toast will not appear again for the number of days set in Dismiss Days.
6. If the visitor clicks Add now, they are taken to https://www.google.com/preferences/source?q=yourdomain.com in a new tab, where they can add your site as a Preferred Source.

Troubleshooting

The toast doesn't appear.

• Make sure the plugin is enabled.
• Check that you're viewing the front end of your site, not the admin panel — the plugin only runs on the site front end.
• Open your browser's developer console and look for JavaScript errors.
• If you recently dismissed the toast, the dismissal cookie may be active. Clear your browser cookies for your domain and reload.

The toast appears but the "Add now" link shows a blank or error page. Your domain is not recognized by Google. Go back to the Basic tab, use the Test link to find the correct domain, and update the Preferred Domain field.

The toast appears behind other elements. Adjust the Position setting, or add a custom CSS rule to increase the z-index of #plg_system_googlepreferred_toast.

The live preview in the admin panel isn't updating. Make sure JavaScript is enabled in your browser and that no admin extensions are blocking scripts on the plugin configuration page.

Uninstalling

Go to System → Extensions → Manage, find System - Google Preferred, and click Uninstall. This removes all plugin files. No database tables are created by this plugin, so no cleanup is needed beyond the uninstall.