OptinMonster JavaScript Events API

The OptinMonster JavaScript Events API is extremely powerful, providing the tools needed to further extend OptinMonster to suit your specific needs.

Before You Start

Here are some things to know before you begin:

  • All Javascript events are asynchronous.
  • All campaign IDs should use your campaign’s Unique ID.

Use

It’s that simple! You can now run your desired actions within the specified event.

What’s Available

The following will give you all information about the campaign, as well as access to public JS methods for the campaign.

The event object passes information about the event and the OptinMonster campaign. You can then access those properties within your function.

Initializing OptinMonster Events

om.Api.init

Runs once per page when the API starts.

om.Main.init

Runs once before campaigns are requested.

om.Main.parseCampaigns

Runs once after campaigns are retrieved.

Initializing a Campaign Events

om.Campaigns.init

Runs once after the document DOM is ready, when campaigns object is initialized, but before the individual campaigns are initialized.

om.Types.init

Runs while a campaign is initializing and happens after initializing the campaign type object.

om.Analytics.init

Runs while a campaign is initializing and happens after initializing the Analytics object.

om.Sites.init

Runs while a campaign is initializing and happens after initializing the Sites object, but before the sites are matched against the current campaign.

om.Html.init

Runs while a campaign is initializing and happens after initializing the Html object, and, if applicable, before the campaign holder element is attached to the DOM.

om.Iframes.init

Runs while a campaign is initializing and happens after initializing the Iframes handler object.

om.Listeners.init

Runs while a campaign is initializing and happens after initializing the Listeners object, but before the event listeners are added.

om.Lock.init

Runs while a campaign is initializing and happens after initializing the Lock content-locking handler, but before locking/unlocking happens.

om.SoundEffects.init

Runs while a campaign is initializing and happens after initializing the SoundEffects object, but before any sound-effects are played.

om.Tags.init

Runs while a campaign is initializing and while initializing the Tags smart-tags handler, but before the tags are replaced.

om.Dtr.init

Runs while a campaign is initializing and after initializing the Dtr dynamic-text-replacement handler, and after the global text-replacement functions have been called.

Showing Events

om.Campaign.init

Runs once when a campaign is initialized.

In the following example, we’ll remove the campaign if a video is playing.

om.Campaign.normalize

Runs just before any split test elements are normalized.

om.Campaign.canLoad

Runs just after a successful check that a campaign is able to load. The campaign is not guaranteed to show.

om.DisplayRules.init

Runs when the campaign wants to show, just before checking if the display rules are passing.

om.Ruleset.init

Runs when the campaign rulesets are being processed just before determining if the Ruleset passes.

om.Group.init

Runs when the campaign rulesets are being processed just before determining if the Group in a Ruleset passes.

om.Rule.init

Runs when the campaign rulesets are being processed just before determining if the Rule in a Group in a Ruleset passes.

om.WebFonts.init

Runs when a campaign is being initiated and handles initializing the webfonts object, just before any font-loading/pre-loading occurs.

om.Html.images

Runs when a campaign is being initiated and just before any image-loading/pre-loading occurs.

om.Campaign.startShow

Happens before beginning the process of showing the campaign. Processes a couple more checks before showing, but has already passed the rules.

om.Campaign.canShow

Runs just after a successful check that a campaign can show on the page (e.g. no other campaign is currently visible).

om.Campaign.show

Runs before om.Campaign.load and before all campaign settings are initialized.

In this example, we’re going pause a video playing on the page if a certain campaign is about to show.

om.DisplayRules.actions

Runs right before any display rules actions are run for rules that have successfully passed.

om.Html.show

Runs right before the campaign form HTML is processed and appended.

om.Html.customVars

Runs while the campaign form HTML is being processed and before the smart-tags are replaced.

om.Html.shortcodes

Runs while the campaign form HTML is being processed and just before parsing any shortcodes for output on the page.

om.Html.append.before

Runs while the campaign form HTML is being processed and just before appending it to the DOM.

om.Html.scripts

Runs while the campaign form HTML is being processed and just before processing any scripts inside the HTML and adding them to the head of the page.

om.Html.inlineScripts

Runs while the campaign form HTML is being processed, once the external scripts have finished loading, and just before we inject the inline scripts.

om.Html.append.after

Runs when the campaign form HTML has been processed and appended to the DOM.

In this example, we’ll log a message when the main campaign container has been attached to the outer DOM.

om.Form.init

Runs when the campaign form HTML has been appended to the DOM and just before initializing the campaign form attributes.

om.PoweredBy.init

Runs when the campaign form HTML has been appended to the DOM and just before creating and appending the powered-by link.

om.Styles.init

Runs when the campaign form HTML has been appended to the DOM and just before updating the campaign styles for display and before applying any monster effects.

om.Actions.init

Runs when the campaign form HTML has been appended to the DOM and just before initializing the individual action events that are attached to elements in the campaign.

om.Action.init

Runs when the campaign form HTML has been appended to the DOM and just before initializing an individual action event that is attached to elements in the campaign.

om.Countdown.init

Runs when the campaign form HTML has been appended to the DOM and just before updating any countdown elements in the campaign.

om.Campaign.load

Runs just before the campaign actually becomes visible.

In this example, we’ll write to the browser’s console a message to confirm the successful loading of our campaign.

om.Campaign.afterShow

Runs just after a campaign becomes visible.

Closing Events

om.Campaign.startClose

Runs at the start of the close function before we check for any conflicts with actually closing.

om.Campaign.close

Runs at the end of the close function just before the close happens.

In this example, we’ll redirect users to a specific url when the campaign is closed.

om.Campaign.afterClose

Runs just after the close function.

In this example, we’ll play/resume a video on the page when the campaign closes.

om.Campaign.cleanup

Runs before we set cookies, but after a close.

Changing Views Events

om.Campaign.changeView

Runs right before any view is changed (e.g. Yesno to Optin).

om.Campaign.changeView.done

Runs right after any view is changed.

Optin Request Events

om.Optin.init

Runs at the start of a conversion attempting being triggered (e.g. click submit on a form before we check validation)

om.Optin.init.submit

Runs at the start of a conversion attempting being triggered (e.g. click submit on a form before we check validation)

In this example, we’ll add a custom redirect url (https://optinmonster.com/) if the subscriber uses a non-business email address such as yahoo, gmail, hotmail, etc.

om.Optin.error

Runs any time there is an error in the Optin conversion, but not during validation (e.g. MailChimp responds with test email not allowed).

In this example, we’ll redirect users to a specific url if there’s an error.

om.Optin.success

Runs after a successful conversion.

In this example, we’ll close the campaign after a successful conversion. This could be useful where the redirect url results in a direct file download and the campaign remains visible in the browser.

Analytics Events

om.Analytics.track

Runs any time we are tracking an impression or conversion.

In this example, we’ll log a message to the console to let us know our campaign has successfully tracked an impression or conversion.

And in this example, we’ll use Google Tag Manager to track a specific event in our Google Analytics account. If you’re unfamiliar with Google Tag Manager, consider reading The Definitive Guide to Triggering Custom Google Analytics Events Using Google Tag Manager and in Step 4 we’ll be triggering the tag event when om.Analytics.track fires and the event type is a conversion.

om.Analytics.impression

Runs any time we are attempting to track an impression. To actually know when an impression is tracked, you will need to use the om.Analytics.track event.

om.Analytics.conversion

Runs any time we are attempting to track a conversion. To actually know when a conversion is tracked, you will need to use the om.Analytics.track event.

Element Action Events

om.Action.redirect

Runs before a redirect action happens.

In this example, we’ll log a message in the browser’s console when the page is about to redirect to the Success URL.

om.Action.view

Runs before a view change happens based on an action.

om.Action.close

Runs before a close is supposed to happen based on an action.

In this example, we’ll close the campaign on success, then begin a direct file download.

om.Action.window

Runs before a new window is opened based on an action.

om.Action.refresh

Runs before a campaign closes and the page refreshes based on an action.

Miscellaneous Events

om.Campaign.reset

Runs when a manual campaign reset has been called. The API will never call reset itself.

om.Styles.positionPopup

Runs any time the campaign is positioned in the window. Runs only for Fullscreen and Lightbox campaigns.

In this example, we’ll make our Lightbox campaign draggable with the Dragon jQuery plugin once it’s been positioned on the page. Be sure to enqueue the required files, including jQuery. We recommend you review the readme file for the plugin.