Tassos Marinos Developer of Joomla Extensions

Troubleshooting EngageBox

Published in EngageBox
Updated 20 Mar, 2024

Here's a troubleshooting guide to help you identify and fix issues with the EngageBox extension.

Fix setup issues

If you're having issues while setting up EngageBox, the following tips may help troubleshoot your issues.

  • Update to the latest version: Go to Extensions -> Manage -> Update section of your website and check if there are any updates available. If updates are available, click Update.
  • Update to the latest developer version: Check the Developer Releases section if there's a release candidate available that fixes your issue.
  • Deactivate potential conflicting plugins: To limit any potential conflicts with other plugins, temporarily deactivate other potential conflicting plugins one by one. It is recommended to deactivate security, firewall, optimization (JCH Optimize) and caching plugins (Page Cache). You can reactivate the plugins after you’ve successfully solved your issue.
  • Switch your active Joomla template: To avoid potential conflicts with your template, switch your template temporarily, preferably to a default Joomla template such as Protostar.
  • Disable any potential security/ad blocker or firewall software: Disable software such as firewall or security applications running on your computer or your web hosting provider.
  • Disable error reporting: To prevent PHP warnings and notices breaking the popup impressions tracker, set the Error Reporting option in your site's configuration page to None.
  • Install it with an incognito window: This ensures that any browser extensions and ad blockers are disabled. It also ensures a clean cache and cookies are turned off during the setup process.
  • Use a different computer to set it up: Sometimes local softwar, applications, or settings can impact a Joomla extension installation.
  • Meet minimum requirements: Ensure that your environment fulfills all minimum requirements.

If you’re still encountering issues, check the common issues section. If you don't see your issue listed, open a new support ticket with the relevant information related to your issue.

If you have created a popup and don't see it on the front-end, you may have one or more of the following issues.

  • Be sure the System - EngageBox Plugin is installed and enabled.
  • Be sure it is published
  • Be sure you assigned it to the correct pages
  • Be sure you've set the correct "Access Level"
    • If set to "Registered" you need to login
    • If set to "Guest" you need to log out
  • If the Trigger Point is set to on Scroll Depth, make sure you've scrolled the page down enough
  • If the Trigger Point is set to on Element Visibility, make sure the Trigger Element exists on the page
  • Be sure you are logged-in as a Super User if Test Mode is enabled.
  • Be sure you've set an appropriate Trigger Delay in milliseconds
  • Clear your cache if caching is enabled
  • If you're using a cache plugin that caches the whole page output such as Page Cache, Page Cache Extended or jSGCache try disabling it
  • If your site is on Offline Mode, make sure the Enable on Offline Mode option is enabled
  • If you are using JCH Optimize System Plugin try to disable the Combine Javascript Files or the Minify Javascript option.
  • In case you're experiencing a Javascript Error try disabling the Load Legacy Script option found in the extension configuration page.
  • Check the Developer Releases section if there's a release candidate available that fixes your issue.

Plugin shortcodes remain unparsed

If you have plugins installed that use special code (shortcodes) such as Sourcerer or Google Maps and you want to use them within your box, make sure the Prepare Content option found in the extension's configuration page is enabled. In case the shortcode remains still unparsed, you'll probably need to re-order the EngageBox System Plugin before the plugin the parses the shortcode via the Plugins Manager.

The Prepare Content option is only available in the Pro version of EngageBox.

Popup suddenly stopped showing up

If you accidentally clicked on the popup's close button, then a cookie stored on your browser is preventing the appearance of the box. Clear Your Browser's Cookies

The popup keeps showing up and ignores the "After Close Stay Hidden" and/or the "Limit Impressions" options

If the popup keeps showing up, you may have one or more of the following issues.

  • Joomla Cache: You're seeing an outdated version of the page because it's cached by a cache plugin like System - Page Cache, JotCache, Recache or jSGCache. These cache plugins are causing unexpected and random results on the front-end and it is recommended to be disabled. Instead use the Cache Settings available in the Global Configuration page. See Stop Using Cache Plugins - Switch to Progressive Cache.
  • Test Mode is enabled: While the popup is on Test Mode, the cookie that is meant to be stored in the visitor's browser to hide the popup, it doesn't get created. This happens to help you test the popup faster, the main reason behind the Test Mode.
  • Your site is not using an SSL: To determine how many times a user has seen a popup, EngageBox is using the cookie nrid to uniquely identify a user. That cookie is using the Secure Flag option which requires the site to be running under https (SSL certificate) in order to be stored in the visitor's browser. If that cookie is missing, EngageBox is unable to decide whether the popup should be displayed to the visitor or not.
  • Statistics is disabled: The Statistics option is disabled either in the extension's configuration page or in the popup's settings in the advanced tab. (Affects the Limit Impressions feature only)
  • Javascript Errors: A Javascript error is preventing the AJAX request responsible to track the popup impressions from being executed.
  • Your site blocks cookies: EngageBox relies on the cookie nrid to determine how many times a visitor has seen a popup. If that cookie is blocked or deleted during page load, then the popup you've configured to appear limited times is very likely to show up on every page load.

I am getting random device-detection results

This problem is probably caused by a Page-Cache plugin. See Stop Using Cache Plugins - Switch to Progressive Cache.

The JavaScript Events API calls don't work

Make sure you wrap your code with the onReady method

EngageBox.onReady(function() {
    // your code goes here

Find more details about the JavaScript Events API

PHP Fatal error: Cannot redeclare class Mobile_Detect

EngageBox is using Mobile_Detect, a lightweight PHP library for detecting visitor's device type. To avoid conflicts and PHP errors, the Mobile_Detect library is only loaded if it's not loaded by another extension already. However, there are many Joomla extensions out there which don't make this check, as a result, the following PHP fatal error.

Fatal error: Cannot redeclare class Mobile_Detect in Mobile_Detect.php on line X

Possible solution: Go to Joomla Plugins Manager and find the EngageBox System Plugin. Then try to re-order it at the end. If the problem persists, please contact the extension's support team and ask them to fix their poor coding.

This issue may affect only users who are using EngageBox < 4.2.0.

The <script> code changes to <s-cript> on save

This is added due to RSFirewall or any similar extension you might have installed. You should add an exception for EngageBox.

Read more details here.

Why do my boxes not appear correctly when LiteSpeed Cache plugin is enabled?

If you use the LiteSpeed Cache plugin, your boxes may not appear correctly and may sometimes not display at all.

To overcome this issues there are a few things you can do to get EngageBox to start working correctly:

  • Try reordering the LiteSpeed Cache plugin and move it at the end of your Plugins via Extensions > Plugins
  • Try excluding the URLs where the boxes are supposed to appear via the LiteSpeed Cache settings
  • Make sure you are using the latest version of LiteSpeed Cache plugin

If none of the above helps, See Stop Using Cache Plugins - Switch to Progressive Cache.

Your page is probably suffering from HTML errors like unclosed divs, nested forms elements or general parse errors. To check your page for HTML mistakes you may use the W3C Markup Validation Tool.

Stop Using Cache Plugins - Switch to Progressive Cache

If your site is using Cache plugins such as the Joomla built-in Page Cache plugin or the LiteSpeed Cache plugin, it’s highly likely to get unexpected and random results with your popups, and chances are you will be facing one or more of the following:

  • Popup appears when it should not.
  • Popup does not appear when it should.
  • Random popup appearance.
  • Outdated version of the popup’s content.
  • Inaccurate results with the Device (Mobile/Table/Desktop) Condition.

How Page-Cache plugins work

The aforementioned glitches are very common with cache plugins because they are designed to cache and serve the same output to all users.

Here's an example to understand how they work:

  • Let's say you have configured a popup to show up only on Mobile users.
  • The Joomla Cache is clean.
  • A mobile visitor visits your site and sees the popup correctly.
  • The Cache plugin creates a cached version of the page.
  • A minute later, another visitor visits your site using a Desktop.
  • The Cache plugin checks if there's a cached version of the page and serves the cached version to the visitor.
  • Issue: The Desktop user sees the popup (incorrectly) because the earlier cached version of the page included the popup.

The Cache plugins that behave in that way are:

  • Joomla Page Cache
  • LSCache (LiteSpeed)
  • JotCache
  • Recache
  • jSGCache

The Fix: Switch to Progressive Cache

Our recommendation is to stop using any of these plugins and switch from page-cache plugins to system cache that is more dynamic and flexible. Specifically using the Progressive Cache option available on your site's global configuration page will give your site's a performance boost while it prevents conflicts with 3rd party extensions.

Joomla Progressive Cache

To learn more details about the available Cache options in Joomla and how they work, JoomlaBeginner.com has a very detailed guide here How to enable Cache in Joomla.

Detecting Javascript Errors

View your site using Chrome or Firefox and press F12 to open up the Developer Tools. Then click on the "Console" tab which shows any Javascript errors that your site may be experiencing. If there is an error, it will include a filename and line number. If the filename is within a plugin, try deactivating that plugin and reload the page. This first step is critical, so don’t overlook it.

I can't create a new popup/view the list of templates

In some cases, the templates library may not display the list of templates, and instead, throw an error. This is a known issue and will be fixed in a future release of EngageBox.

Below you can find a few cases on why this may happen, and temporary workarounds:

  • You have SP Page Builder installed, and have "Lazy Loading" enabled. This seems to cause an issue with some SVGs loading on our library. Try disabling this setting and re-try.
  • It's very likely that your server has Apache's ModSecurity enabled, using a restrictive set of rules. In this case you should increase the rule called SecResponseBodyLimit to at least 2MB(Megabytes). Instructions for doing so vary depending on your host's enviroment and provided tools. Please consult your host's support center if no such option seems to be availiable to you.

Error "403 Forbidden" when trying to access the "Display Conditions" section

Similarly to the previous problem, Apache's ModSecurity is usually the cultrip. Again, raising SecResponseBodyLimit to at least 2MB(Megabytes) should fix this problem.

Popup doesn't appear in Nicepage

If you are using Nicepage and your popups do not appear on the front-end of your site, try re-ordering the EngageBox system plugin after the Nicepage plugin.

EngageBox 6.3.0+ breaks my Joomla 3 site (Fabrik issue)

If, after installing EngageBox 6.3.0+ on your Joomla 3 site, your site breaks and doesn't work anymore, and you also have Fabrik installed, the issue lies in how Fabrik overrides some Joomla core classes.

You should open the file /administrator/components/com_fabrik/classes/310/FormField.php, and add the following PHP snippet before abstract class FormField.

if (class_exists('Joomla\CMS\Form\FormField'))

Your site should now be back up and running. Note that this may produce unexpected behavior on your site, so we strongly suggest contacting Fabrik to resolve this issue.

Contact Support

If you have progressed through the previous steps but have not been able to resolve your issue, then you are ready to reach out for support. Here’s how to help our support team provide the best possible assistance:

  • Please be specific as to both the problem and your desired functionality for EngageBox, and provide any URL(s) being discussed.
  • Please be concise. If you have multiple questions or a longer message, consider using bullets or numbers to help keep your questions clear and distinct.

Log into your account first and then submit a support ticket through this form.