Building Targeted Overlays with Permutive

We have just introduced Targeted Overlays, a Permutive add-on which enables you to show targeted overlays to the right users at the right time. The add-on can be enabled and configured in the dashboard. Once enabled, you can set up as many overlays as you like, with each one being targeted to users who fall into a specific segment.

We built this add-on to make deploying targeted overlays a fast and easy process with no development work required. But in fact, with a little development work, anyone can build personalized web elements that work with Permutive. In this article, we’ll explain how we implemented targeted overlays on top of our SDK and what goes on behind the scenes.

Modifying the DOM

We wanted to let people customize their overlays, with settings like overlay opacity (how transparent the overlay background is) and transition time (how long the overlay takes to fade in). In order for each overlay to have its own configuration, we have to inject CSS into the <head> section of the page for every overlay. The CSS looks something like this:

.permutive-overlay-1 { 
	transition:opacity 500ms;

.permutive-modal-1 { 

.permutive-modal-1 .content { 

.permutive-modal-1 .close { 
	transition:all 200ms;

.permutive-modal-1 .close:hover {

Note that we give each overlay its own unique class, such as permutive-overlay-1 and then we reference this class in the CSS selector to apply styling to a specific overlay. No sizes are specified for the modal or its content, and the content class has its overflow attribute so to 'auto'. This ensures that the modal will expand to fit the size of its inner content. Since we don’t want to show the overlay on page-load, the overlay’s visibility attribute is set to 'hidden'.

Similarly, we inject the actual overlay and modal to the into the <body> section of the page:

<div id="permutive-overlay-1" class="permutive-overlay-1">
  <div id="permutive-modal-1" class="permutive-modal-1">
    <a class="close" href="javascript:;">×</a>
    <div class="content">Your content gets inserted here!</div>

Detecting Segment State Changes

An interesting part of this add-on is how we detect changes in segment state. As soon as a user becomes a part of a segment which has been assigned to an overlay, we want to display the overlay.

Imagine that we want to display an email subscription popup to users who have visited our homepage at least five times. We could set up a Permutive query, IsRegularVisitor, to capture this segment of users:

SELECT COUNT(name = 'HomepagePageview') >= 5 AS result FROM events

Now, when a user makes their fifth visit to our homepage, the ‘result’ property of our query will change from false to true, as the user is now part of our target segment. The Permutive SDK provides an easy way to detect this change - the trigger function:

permutive.trigger(‘IsRegularVisitor’, ‘result’, function(state) {
  if (state[‘result’]) {

Here, we simply pass in our query name, the name of the property we want to watch and a handler function that Permutive should call when the property state changes. The handler function should expect a single argument: the state of the query. We are then able to check if the result property is true to determine whether to display our overlay.

Note that the function passed to trigger is only called when the query changes state. Therefore, the overlay will only be shown once: the first time a user enters a segment and the result property changes state from false to true.

Displaying the Overlay

Finally, we need a function to display our overlay. We use jQuery to select our overlay and set its CSS visibility attribute to 'visible'. Since our add-on handles dynamic content, we need an extra step here which sets position and size attributes on the inner modal’s CSS from javascript.

var showOverlay = function(overlayId) {
  var $div = $("#" + overlayId);
  var $modal = $div.find("div").first();
  $modal.css({"margin-left": -($modal.width()/2) + "px", "margin-top": -($modal.height()/2) + "px" });
  $div.css({'visibility': 'visible', 'opacity': 1});

That’s it! This demonstrates how easy it is to build personalized elements for any website on top of the Permutive SDK. Note that since our add-on needs to support multiple overlays that are configured dynamically, we have had to do some extra work here. This includes injecting custom CSS for each overlay and dynamically setting the position and size of the modal using javascript. In a more static setting, the process would be even easier as you wouldn’t need to worry about these things.