Existing Popup Integration

This guide explains how to properly configure your existing designed pop-up root container to work seamlessly with the Popup Builder application.

Overview

To integrate your existing popups with Popup Builder, your popup container must include specific attributes, classes, and embedded code. This ensures proper functionality and compatibility with our system.

Required Setup

1. Essential Attributes

Your popup root container must include these mandatory attributes:

<div 
  fa-popup-root="true"
  aria-hidden="false"
  fa-popup-config="{}"
  fa-template-addons="[\"\"]"
  class="flowappz-hide-popup">
  <!-- Popup content -->
</div>

2. CSS Hiding Behavior

Add this embedded <style> block to ensure proper popup visibility control:

<style>
/* Hides popup elements when not in Webflow Designer mode */
html:not(.wf-doc) .flowappz-hide-popup {
    display: none;
    opacity: 0;
    pointer-events: none;
    visibility: hidden;
    transition: opacity 0.2s ease;
}
</style>

Note: This CSS ensures your popup remains hidden on the live site while remaining visible in Webflow's Designer for editing.

3. Content Structure Attributes

Within your popup structure, add these specific attributes:

• Content Wrapper: Add fa-popup-content-wrapper="true" to your main content container

• Close Button: Add fa-popup-close-button="true" to your close button element

<div fa-popup-root="true" class="flowappz-hide-popup">
  <div fa-popup-content-wrapper="true">
    <!-- Your popup content -->
    <button fa-popup-close-button="true">×</button>
  </div>
</div>

Configuration Object

Basic Structure

The fa-popup-config attribute must contain a JSON configuration object with the following structure:

{
  "id": "unique-popup-id",
  "name": "Popup Name",
  "type": "modal",
  "status": "draft",
  "templateId": "template-number",
  "devices": ["desktop", "tablet", "mobile"],
  "style": { /* styling options */ },
  "userBehavior": { /* behavior settings */ },
  "target": { /* targeting rules */ },
  "frequency": { /* display frequency */ }
}

Complete Configuration Example

<details> <summary>Click to view full configuration example</summary>

{
  "id": "cvdjbkz1756708116133",
  "name": "First popup",
  "element": null,
  "contentWrapperElement": null,
  "type": "modal",
  "isHideFromDesigner": false,
  "status": "draft",
  "integration": false,
  "templateId": "3",
  "devices": ["desktop", "tablet", "mobile"],
  "includePages": [],
  "excludePages": [],
  "triggers": [],
  "displayOnce": true,
  "frequencyDays": 7,
  "isWebflowDataSubmission": false,
  "schedule": {
    "enabled": false,
    "start": "",
    "end": ""
  },
  "style": {
    "position": "center",
    "animationType": "fadeIn",
    "size": "small",
    "opacity": 0.6,
    "overlayColor": "#000000",
    "openAnimationSpeed": "normal",
    "closeAnimationSpeed": "normal",
    "closeAnimationType": "fadeIn",
    "isCustomPosition": false,
    "customPositionUnits": "px",
    "customPosition": {
      "top": 0,
      "left": 0,
      "right": 0,
      "bottom": 0
    }
  },
  "userBehavior": {
    "afterScrolling": {"unit": "none", "value": 1},
    "delay": 1,
    "exitIntent": {"active": false, "sensitivity": "low"},
    "showOnlyOnce": false,
    "inactiveTime": {"active": false, "time": "0"},
    "happyHour": {
      "active": false, 
      "date": "2025-09-01T06:28:36.133Z", 
      "start": "12:00:00", 
      "end": "12:00:00"
    },
    "frequency": {"active": false, "interval": 2, "unit": "weeks"},
    "elementPopupTrigger": {"active": false, "elementSelector": ""}
  },
  "target": {
    "urlBrowsing": {"all": true},
    "scheduleDateTime": {
      "from": "2025-09-01T06:28:36.133Z", 
      "to": "2025-09-01T06:28:36.133Z"
    },
    "userAction": {"actionType": "none", "elementSelector": ""},
    "showOnSpecificPages": {
      "specificPages": [],
      "excludePages": [],
      "isShowOnSpecificPages": false,
      "urlContains": [""],
      "urlMatchesExactly": [""]
    },
    "showOnCookies": {"cookieCondition": "none", "cookieName": ""},
    "referrerTargeting": {"isEnabled": false, "allowedReferrers": []},
    "customCondition": {"isEnabled": false, "condition": ""}
  },
  "frequency": {
    "displayFrequency": "display-every-session",
    "stopDisplaying": {
      "neverStop": true, 
      "emailSubmission": true, 
      "afterClosing": true, 
      "numberOfTime": 1
    },
    "escKey": true,
    "autoCloseXSeconds": {"active": false, "seconds": 0},
    "openPopupFormSubmission": false,
    "disablePopupClose": false,
    "closeOnPageNavigation": true
  },
  "countdownConfig": {
    "endDate": "2025-09-01T06:28:36.133Z",
    "endTime": "12:00:00",
    "timeZone": "UTC",
    "displayOptions": {
      "showDay": true, 
      "showHour": true, 
      "showMinute": true, 
      "showSecond": true
    }
  }
}

</details>

Optional Features

Countdown Timer

If your popup includes a countdown timer, add these attributes to the respective time display elements:

<span fa-day-count="true">00</span>
<span fa-hour-count="true">00</span>
<span fa-minute-count="true">00</span>
<span fa-second-count="true">00</span>

Implementation Checklist

Before integrating your popup, ensure you have:

• [ ] Added all required attributes to the root container

• [ ] Included the flowappz-hide-popup class

• [ ] Embedded the CSS hiding behavior

• [ ] Added content wrapper and close button attributes

• [ ] Configured the JSON settings object

• [ ] Added countdown attributes (if applicable)

• [ ] Tested visibility in both Designer and live site

Troubleshooting

Popup not appearing?

• Verify the CSS hiding behavior is correctly implemented

• Check that aria-hidden is set to "false"

• Ensure the configuration JSON is valid

Popup always visible?

• Confirm the flowappz-hide-popup class is applied

• Verify the embedded CSS is present in your page

Configuration not working?

• Validate your JSON syntax using a JSON validator

• Ensure all required fields are present in the configuration object

---

For additional support or questions about popup integration, please contact our support team or refer to our API documentation.