Troubleshooting EngageBox

Published in EngageBox
Updated 11 Feb, 2022

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 Content Prepare 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.

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, 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.

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.