# 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:

```html
<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:

```html
<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

```html
<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:

```json
{
  "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>

```json
{
  "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:

```html
<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](https://claude.ai/chat/fe4763ae-b5f6-467c-8d7a-77938d5e9146).