Smart Favicon: setup and help

Requirements

Requires PrestaShop 1.6.0.4 or later and PHP 7.1 or later.

Browser features depend on JavaScript and the active theme’s standard header/media hooks.

Upload the release ZIP through Modules > Module Manager > Upload a module and install it. Open Favicon > Configuration, or click Configure in Module Manager. Select a specific shop in multistore before editing normal settings.

Enable Smart Favicon starts on. The count badge and background nudge also start on. Prefix the tab title with the count starts off. With no uploaded icon, the module can use the shop's existing favicon for the badge.

Icon files

Set Light-mode favicon and Dark-mode favicon. You can upload ICO, PNG, SVG or WebP. Use a square PNG of at least 32 by 32 pixels for a basic icon. Use a larger raster source when you want larger generated app icons.

Uploads are limited to 1 MB. PNG/WebP images must not exceed 1,024 pixels in either dimension. SVG files need a viewBox or explicit width and height; the sanitizer rebuilds the accepted SVG before storage. Unsupported or unsafe files are rejected.

Click Save and check Current light icon and Current dark icon. Uploads are stored in img/mprfavicon/ under new filenames to avoid reusing the previous cached URL. The directory must be writable by the web server.

Use Remove light icon on save or Remove dark icon on save to remove a variant. These removal switches start off.

Scheme behavior

Browsers that support favicon media queries select the light/dark links through prefers-color-scheme. The module also follows system color-scheme changes. A scheme without its own upload falls back to the shop's native favicon. With neither uploaded, the module adds no replacement scheme links; the active badge can still produce a managed icon.

The generator uses the first decodable raster source, checking light before dark. It creates 16, 32, 48, 180, 192, 256 and 512 pixel PNGs and a multi-size ICO. The storefront can emit 16/32/48 icon links, an Apple touch icon and the manifest's 192/512 icons. The module serves the manifest with the content type required for a web manifest.

Image generation needs GD with the relevant PNG/WebP decoder. If the back office reports that a raster source is needed, upload a PNG or WebP and save again.

Global root icon in multistore

There is one root favicon.ico for the installation. It can affect every shop sharing that root. The shop that enables the override owns it. Another shop cannot replace or restore the owner's file through its own settings.

The module backs up the original before replacing it. The owner can disable the switch and save to request restoration. In All shops, Release global favicon.ico ownership releases the shared ownership and attempts restoration. Normal per-shop settings are edited in a specific shop context.

If someone changed the root icon outside the module, recovery keeps that newer file. If backup, ownership, locking or restoration fails, the module preserves recovery state and reports the problem. Do not delete the backup to clear an error.

Search services decide which icon they display and when they refresh it.

Custom back-office favicon starts on. Upload Back-office favicon for a dedicated admin icon, or leave it empty to reuse the light icon. If neither exists, the native admin icon remains available.

Check Current admin icon after saving. Use Remove admin icon on save to remove the dedicated file. The back-office icon does not display a storefront cart badge.

Other modules can add source switches. Disable sources you do not want counted. The badge, count prefix and default nudge use the selected combined count, so another enabled source can keep them active with an empty cart.

On PrestaShop 1.7/8/9 the runtime listens to cart events. On PrestaShop 1.6 it observes the legacy cart counter and wraps supported ajaxCart methods. Test add, remove and quantity changes with your theme.

Count prefix

Enable Prefix the tab title with the count when you want the count in the title. Title format starts as ({count}) {title}. Keep {title} in the format so the page's title remains present. An empty format or one without {title} falls back to the default.

Background nudge

Attention nudge when the tab is in the background starts on. Fill Nudge messages for each shop language, one message per line. The supplied English messages are “🛒 Still thinking it over?” and “Your items are waiting”; supplied translations are used where available.

Rotation interval starts at 4 seconds and is limited to 2 through 60 seconds. The default nudge runs while the tab is blurred and the selected count is positive. Returning focus stops the nudge and restores the normal title, including the current count prefix if enabled.

Title changes happen in JavaScript after page load. The server-rendered title is unchanged. The runtime skips detected bots and browsers reporting navigator.webdriver, so test with an ordinary browser session as well as automated tools.

Open Favicon > Engagement campaigns to add custom engagement rules. The basic badge, scheme and title settings do not require a campaign.

Set Name, choose a Trigger, then select Match mode as All conditions or Any condition. Use the builder's available condition and action lists. Set Minimum re-entry delay on this page in milliseconds; it starts at 0 and resets on navigation. Priority starts at 0, with higher values winning exclusive action channels. Its accepted range is -1000 through 1000. New campaigns start disabled; turn Enabled on after reviewing the rule and click Save.

Campaigns belong to the selected shop. Test the trigger and check for overlap with the default title and favicon actions. Disable a campaign from the list when you want to keep its configuration without running it.

Register an enabled source

Register your provider module on actionRegisterFaviconBadge and return a descriptor:

public function hookActionRegisterFaviconBadge($params)
{
    return [
        'id' => 'tickets',
        'label' => $this->l('Unread replies'),
        'script' => 'modules/yourmodule/views/js/source.js',
    ];
}

Source IDs use lowercase letters, digits, _ or -, up to 40 characters. Do not use the reserved cart ID. A script path is optional and must be shop-root relative. The module creates a switch for the declared source; contributed sources start enabled.

Register the matching counter in the script:

window.mprFavicon.registerSource('tickets', function () {
    return 3; // A number or a Promise resolving to a number.
});
window.mprFavicon.update();

Call update() after the underlying value changes. The server's enabled-source list is authoritative. Registering an arbitrary JavaScript source alone does not add it to that list or bypass a merchant-disabled source. The same source ID must be declared, enabled and registered at runtime.

First check

1. Save your icons and inspect their back-office previews.
2. Open the shop in a normal browser, add a product and check the badge.
3. Change quantity, remove the product and confirm the badge clears.
4. Switch system light/dark mode and check the base icon.
5. With a positive count, blur the tab, check the nudge and return to confirm the title restores.
6. If enabled, test the count prefix, admin icon, generated links and manifest separately.

Common problems

• An uploaded icon seems unchanged. Hard-refresh and reopen the tab. Browsers cache favicons independently of page content.
• The badge does not update on PrestaShop 1.6. Check that the theme has a supported block-cart counter or ajaxCart integration.
• A custom source is ignored. Check its PHP descriptor, merchant switch, source ID and runtime registration.
• The icon set is absent. Check the raster source, GD support and writable img/mprfavicon/ directory. ICO/SVG remain usable as source icons but cannot produce the generated set.
• The root icon cannot be changed. Read the ownership message, switch to the owner shop and check filesystem permissions. Use the All shops release action when you intend to release global ownership.
• Nothing happens during automation. The runtime intentionally skips WebDriver and detected bot user agents. Verify the result manually.
• Infrastructure is missing. Open Favicon > Integrity.

Disable the root override from its owner shop and confirm recovery before removing the module if you want to check restoration explicitly. Uninstall also attempts root recovery and removes normal favicon configuration/files when that transition succeeds.

If recovery cannot finish, uninstall preserves the configuration and backup files needed to retry and logs the issue. A file replaced externally is kept. Check /favicon.ico and any reported recovery error after uninstalling; do not assume every filesystem operation succeeded.