# 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#).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flowappz.com/home/webflow-popup-builder/existing-popup-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.