1. 공지 팝업 관리 개요
DXCMS 관리자 패널의 [공지 팝업 관리] 메뉴는 사이트 방문자에게 공지사항, 이벤트, 마케팅 메시지 등을 팝업 창 형태로 표시하는 기능을 제어합니다. 팝업의 내용•크기•위치•노출 기간•대상 기기를 세밀하게 설정할 수 있습니다.📌 접근 경로: 관리자 대시보드 → 공지 팝업 관리 (또는 URL: /admin/popup)
1.1 팝업 동작 원리
DXCMS 팝업 시스템은 DxPopup 엔진 클래스를 통해 동작합니다. 페이지 하단(dx_body_bottom 훅)에 자동으로 팝업 HTML이 삽입되며, 다음 조건을 모두 만족하는 팝업만 실제 사이트에 표시됩니다.| 노출 조건 | 설명 |
| 활성화 상태 | status = 1 (ACTIVE)로 설정된 팝업만 표시됩니다. |
| 노출 기간 | 오늘 날짜가 start_date ~ end_date 범위 내에 있어야 합니다. 날짜 미설정 시 기간 제한 없이 상시 노출됩니다. |
| 대상 기기 | device 설정이 "전체"이거나, PC 전용이면 데스크톱, 모바일 전용이면 스마트폰/태블릿에서만 표시됩니다. 서버사이드 User-Agent 기반으로 판별합니다. |
| "다시보지않기" 쿠키 | 방문자가 "다시 보지 않기"를 체크하고 닫으면, 브라우저 쿠키(dx_popup_hide_{id})가 설정됩니다. 쿠키가 유효한 기간 동안은 해당 팝업이 표시되지 않습니다. |
1.2 팝업 화면 구성
관리자 팝업 관리 페이지는 상단의 현황 표시 및 신규 등록 버튼, 추가/수정 폼(등록•편집 시 표시), 그리고 팝업 목록 테이블로 구성됩니다.| 영역 | 설명 |
| 현황 배지 | 현재 등록된 전체 팝업 수를 표시합니다. (예: "전체 현황: 3개 활성") |
| 팝업 신규 등록 버튼 | [+ 팝업 신규 등록] 버튼 클릭 시 등록 폼(/admin/popup/add)으로 이동합니다. |
| 추가/수정 폼 | 신규 등록 또는 기존 팝업 수정 시 목록 위에 표시되는 상세 설정 폼입니다. |
| 팝업 목록 테이블 | 등록된 모든 팝업을 표로 나열. 순서·제목·기기·기간·상태·관리 버튼이 포함됩니다. |
1.3 팝업 성능 최적화 (캐싱)
DxPopup 엔진은 활성 팝업 목록을 60초간 캐시(DxCache)하여 매 페이지 접근마다 DB를 조회하는 부하를 방지합니다. 관리자가 팝업을 저장•수정•삭제•상태 변경할 때마다 캐시(popup_active_{날짜})가 자동으로 초기화되어 변경 사항이 최대 60초 내에 반영됩니다.
💡 DxCache가 비활성화된 환경에서는 캐싱 없이 매 요청마다 DB를 직접 조회합니다. 캐시 초기화가 필요하지 않습니다.
2. 팝업 목록 테이블
관리자 화면 하단의 팝업 목록 테이블에서 등록된 모든 팝업의 현황을 한눈에 확인하고 관리할 수 있습니다.
2.1 목록 컬럼 설명
| 컬럼 | 설명 |
| 순서 | 팝업 출력 우선 순서(sort_order). 숫자가 작을수록 먼저 표시됩니다. 마우스 오버 시 하늘색으로 강조됩니다. |
| 팝업 제목 / 크기 | 팝업 관리 제목(굵게 표시). 아래 줄에 팝업 너비×높이(PX), 화면 위치(pos_x, pos_y), 다시보기 쿠키 유지일이 요약됩니다. |
| 기기 | 출력 대상 디바이스 배지. PC/MOB(전체, 회색), PC ONLY(파란색), MOBILE(보라색)으로 색상 구분됩니다. |
| 기간 | 노출 시작일(파란색)과 종료일(빨간색)이 표시됩니다. 기간 미설정 시 "기간 제한 없음"으로 표시됩니다. |
| 상태 | Live(초록, 활성+기간 내 노출 중) / Wait(노란색, 활성이나 기간 미도래) / Idle(회색, 비활성)으로 실시간 상태 표시. |
| 관리 | Mute/Live 토글 버튼, 수정 버튼(✏️), 삭제 버튼(🗑) 3종 제공. |
2.2 팝업 상태 배지 상세
목록의 [상태] 컬럼에는 3가지 배지 중 하나가 표시되며, 실제 사이트에서 팝업이 노출되고 있는지를 즉시 파악할 수 있습니다.| 배지 | 조건 | 의미 |
| ● Live | status=1 AND 오늘이 기간 내 | 현재 사이트 방문자에게 팝업이 실제로 표시되고 있습니다. 빠르게 대응이 필요한 경우 [Mute] 버튼으로 즉시 숨길 수 있습니다. |
| ⏱ Wait | status=1 AND 기간 미도래 또는 종료 | 팝업은 활성 상태이나, 현재 날짜가 노출 기간에 해당하지 않아 표시되지 않습니다. 기간이 시작되면 자동으로 Live로 전환됩니다. |
| ⏸ Idle | status=0 | 관리자가 수동으로 비활성화한 팝업입니다. 기간에 관계없이 사이트에 표시되지 않습니다. [Live] 버튼으로 다시 활성화할 수 있습니다. |
2.3 목록 관리 버튼
| 버튼 | 기능 | 상세 설명 |
| Mute | 활성 → 비활성 | ACTIVE 상태의 팝업을 즉시 DISABLED로 전환합니다. 사이트에서 팝업이 사라지며, 캐시가 초기화됩니다. |
| Live | 비활성 → 활성 | DISABLED 상태의 팝업을 즉시 ACTIVE로 전환합니다. 노출 기간 범위 내라면 즉시 사이트에 표시됩니다. |
| ✏️ | 수정 | 해당 팝업 편집 폼(/admin/popup/{id})으로 이동합니다. 모든 설정을 변경할 수 있습니다. |
| 🗑 | 삭제 | "[팝업 제목] 팝업 정보를 영구 삭제할까요?" 확인 창 후 DB에서 완전 삭제합니다. 복구 불가능합니다. |
3. 팝업 등록 및 수정 폼 — 전체 필드 설명
[팝업 신규 등록] 버튼 클릭 시 또는 목록에서 [✏️ 수정]을 클릭하면 상세 설정 폼이 표시됩니다. 신규와 수정 폼의 구조는 동일하며, 수정 시 기존 값이 자동으로 채워집니다.
3.1 Domain 노출 범위
팝업을 어느 도메인(사이트)에서 표시할지 선택합니다. 멀티사이트 환경에서 사이트별로 다른 팝업을 운영할 때 사용합니다.| 선택 옵션 | 동작 설명 |
| ── 모든 사이트 공통 ── | site_domain이 빈 값으로 저장됩니다. 멀티사이트 환경에서 모든 도메인의 방문자에게 표시됩니다. |
| 특정 도메인 선택 | 선택한 도메인에 방문한 사용자에게만 팝업이 표시됩니다. 다른 도메인 방문자에게는 노출되지 않습니다. |
💡 단일 사이트 환경이라면 "모든 사이트 공통"을 선택하거나 현재 도메인을 선택하면 됩니다. 두 경우 모두 실제 동작은 동일합니다.
3.2 팝업 관리 제목 (필수)
팝업을 관리하기 위한 내부 식별 제목입니다. 실제 팝업 창에도 헤더 영역에 표시됩니다. 방문자가 팝업 헤더에서 보는 제목이기도 하므로, 명확하고 간결하게 작성하세요.
⚠️ 제목은 필수 항목입니다. 미입력 시 "제목을 입력하세요." 오류가 표시되며 저장되지 않습니다.
.3 팝업 이미지 URL (선택)
팝업 본문 상단에 표시할 이미지의 URL을 입력합니다. 이미지만으로 구성된 배너형 팝업을 만들 때 주로 사용합니다.| 입력 형식 | https:// 로 시작하는 완전한 URL. 외부 이미지 URL 또는 서버에 업로드된 이미지의 절대 경로. |
| 링크와 함께 사용 | 클릭시 이동 주소(link_url)를 함께 입력하면, 이미지 클릭 시 해당 URL로 이동하는 링크 이미지 팝업이 생성됩니다. |
| 이미지 단독 사용 | link_url 없이 이미지만 입력하면 클릭해도 이동하지 않는 단순 이미지 팝업이 됩니다. |
| 이미지 크기 | max-width:100% 스타일이 자동 적용되어 팝업 너비 내에서 자동으로 맞춰집니다. |
3.4 클릭 시 이동 주소 (선택)
팝업 이미지를 클릭했을 때 이동할 URL을 입력합니다. 이미지 URL이 설정된 경우에만 링크가 적용됩니다.| 외부 링크 | https://example.com 형태의 완전한 외부 URL. |
| 내부 링크 | /event 처럼 슬래시로 시작하는 사이트 내부 경로. |
| 이동 탭 설정 | "이동 브라우저 탭" 항목과 연동됩니다. _blank(새 창) 또는 _self(현재 탭) 선택. |
| 에디터 콘텐츠와 차이 | 에디터 본문 내에서 직접 링크를 삽입할 수도 있습니다. 이 필드는 이미지 전체에 링크를 씌울 때 사용합니다. |
3.5 노출 시작일 / 종료일
팝업이 사이트에 표시될 기간을 날짜 형식(YYYY-MM-DD)으로 지정합니다. 두 필드 모두 선택 사항이며, 입력하지 않으면 기간 제한 없이 상시 노출됩니다.| 설정 조합 | 동작 |
| 시작일 + 종료일 모두 입력 | 설정한 날짜 범위 안에서만 노출됩니다. 범위 벗어나면 status=1이어도 목록에서 Wait로 표시됩니다. |
| 시작일만 입력 | 시작일 이후로 종료일 없이 계속 노출됩니다. |
| 종료일만 입력 | 등록 즉시부터 종료일까지 노출됩니다. |
| 모두 비워두기 | 기간 제한 없이 status=1인 동안 상시 노출됩니다. 장기 공지나 상시 안내 팝업에 적합합니다. |
💡 이벤트성 팝업은 반드시 종료일을 설정하세요. 설정하지 않으면 이벤트 종료 후에도 계속 노출되어 방문자 경험에 영향을 줍니다.
3.6 팝업 표시 위치 (X축 / Y축)
팝업 창이 화면의 어느 위치에 표시될지를 픽셀(px) 단위로 지정합니다. CSS의 position:fixed 속성을 기반으로 화면 좌측 상단을 기준(0,0)으로 계산됩니다.| 항목 | 기본값 | 설명 |
| X 축 위치 (pos_x) | 20px | 화면 왼쪽 끝에서 팝업 왼쪽 끝까지의 거리. 0이면 화면 최좌측. 예: 20 입력 시 화면 왼쪽에서 20px 떨어진 위치에 표시. |
| Y 축 위치 (pos_y) | 100px | 화면 상단에서 팝업 상단까지의 거리. 0이면 화면 최상단. 예: 100 입력 시 화면 위에서 100px 아래에 표시. |
💡 팝업 여러 개를 동시에 운영할 경우, 위치가 겹치지 않도록 X•Y값을 조절하세요. 팝업은 드래그 이동이 가능하므로(마우스 드래그) 방문자가 직접 위치를 옮길 수 있습니다.
3.7 팝업 너비 / 높이
팝업 창의 크기를 픽셀(px) 단위로 지정합니다.| 항목 | 기본값 | 설명 |
| 팝업 너비 (width) | 400px | 팝업 창의 가로 너비. 최소값 100px. 이미지가 포함된 경우 이미지가 이 너비에 맞게 자동 조절됩니다. |
| 팝업 높이 (height) | 0 (자동) | 팝업 본문 영역의 세로 높이. 0 입력 시 콘텐츠 높이에 따라 자동으로 결정됩니다. 고정 높이가 필요하면 직접 입력하세요 (스크롤 발생 가능). |
💡 모바일 환경에서 팝업 너비가 화면 너비보다 넓으면 스크롤이 발생합니다. 모바일 전용 팝업은 너비를 300~360px로 설정하고, 모바일 대상 기기로 지정하세요.
3.8 출력 대상 디바이스
팝업을 표시할 기기 유형을 선택합니다. 서버사이드에서 HTTP User-Agent 헤더를 분석하여 모바일 여부를 판별합니다.| 옵션값 | 목록 배지 | 표시 대상 |
| 전체 (all) | PC/MOB | 모든 기기(PC, 스마트폰, 태블릿)에서 표시. 기본값. 대부분의 공지 팝업에 적합합니다. |
| PC 전용 (pc) | PC ONLY | Android, iPhone, iPad, iPod, BlackBerry, IEMobile, Opera Mini 기기 제외. 데스크톱/노트북에서만 표시됩니다. |
| 모바일 전용 (mobile) | MOBILE | 모바일 기기(Android, iPhone, iPad 등)에서만 표시됩니다. 모바일 전용 이벤트, 앱 설치 유도 팝업 등에 활용합니다. |
💡 PC와 모바일에서 서로 다른 디자인/내용의 팝업을 운영하려면, 같은 내용의 팝업을 2개 등록하고 각각 PC 전용•모바일 전용으로 설정하면 됩니다.
3.9 다시 보지 않기 기간 (hide_days)
팝업 하단에 표시되는 "N일 동안 보지 않기" 체크박스와 연동되는 쿠키 유지 기간입니다.| 설정값 | 동작 |
| 1 이상 | 팝업 하단에 "N일 동안 보지 않기" 체크박스와 닫기 버튼이 함께 표시됩니다. 방문자가 체크 후 닫으면 브라우저에 쿠키(dx_popup_hide_{id}=1)가 설정되어 지정 기간 동안 해당 팝업이 숨겨집니다. |
| 0 | 다시보기 거부 기능을 비활성화합니다. 팝업 하단에 닫기 버튼만 표시됩니다. 페이지를 새로고침하면 팝업이 다시 나타납니다. |
💡 쿠키는 팝업 ID별로 독립적으로 관리됩니다. 동일한 방문자라도 팝업 ID가 다르면 별도의 쿠키가 사용됩니다. 팝업을 삭제 후 같은 내용으로 재등록하면 새 ID로 쿠키가 생성되어, 이전에 "다시 보지 않기"를 선택했던 방문자에게도 다시 표시됩니다.
3.10 이동 브라우저 탭 (link_target)
| 새 창으로 열기 (_blank) | 이미지 클릭 시 링크 URL이 새 탭(새 창)에서 열립니다. 외부 사이트 링크나 프로모션 페이지로 이동할 때 권장합니다. |
| 현재 탭에서 이동 (_self) | 이미지 클릭 시 현재 탭에서 링크 URL로 이동합니다. 사이트 내부 페이지로 이동할 때 자연스러운 UX를 제공합니다. |
3.11 출력 정렬 순서 (sort_order)
팝업이 여러 개일 때 화면에 표시되는 순서를 결정합니다. 숫자가 작을수록 먼저 처리되며(낮은 Z-index 위에 쌓임), 같은 sort_order 값이면 팝업 ID 오름차순으로 정렬됩니다.
💡 팝업 여러 개를 동시에 표시할 때 sort_order 값으로 중요도 순서를 정할 수 있습니다. 가장 중요한 팝업을 가장 낮은 숫자(예: 1)로 설정하세요.
3.12 팝업 활성화 스위치 (status)
팝업의 공개 상태를 결정합니다. 라디오 버튼 형태로 두 가지 중 하나를 선택합니다.| ACTIVE (사용함) | status=1. 팝업이 활성화됩니다. 노출 기간 범위 내에 있으면 사이트에 표시됩니다. |
| DISABLED (중지함) | status=0. 팝업이 비활성화됩니다. 노출 기간과 관계없이 사이트에 표시되지 않습니다. |
💡 팝업을 미리 등록해두고 특정 시점에 노출하려면, 먼저 ACTIVE + 미래 시작일을 설정하거나 DISABLED로 등록해두었다가 원하는 시점에 Mute/Live 버튼으로 전환하세요.
3.13 팝업 상세 본문 콘텐츠 (에디터)
팝업 창 내부에 표시할 상세 내용을 에디터로 작성합니다. 이미지 URL 없이 텍스트만으로 구성된 팝업, 또는 이미지 아래 추가 설명이 필요한 경우에 활용합니다.| 이미지 URL과 동시 사용 | 이미지가 본문 상단에, 에디터 내용이 이미지 아래에 표시됩니다. 이미지 배너 + 텍스트 설명 조합의 팝업을 구성할 수 있습니다. |
| 에디터만 사용 | 이미지 URL 없이 에디터 내용만 입력하면 순수 텍스트/HTML 팝업이 생성됩니다. 공지문, 개인정보처리방침 변경 안내 등에 적합합니다. |
| 빈 상태 | 이미지와 에디터 모두 비워두면 팝업 헤더와 푸터만 있는 빈 팝업이 표시됩니다. 실제로는 이미지 또는 에디터 중 하나 이상을 반드시 입력하세요. |
| 보안 처리 | 에디터 입력 내용은 DxSanitizer::editorContent()를 통해 XSS 공격 방지 처리된 후 저장됩니다. |
4. 팝업 프론트엔드 동작 상세
실제 사이트 방문자에게 표시되는 팝업의 구조와 사용자 인터랙션 방식을 설명합니다.
4.1 팝업 HTML 구조
각 팝업은 다음 3개 영역으로 구성된 플로팅(position:fixed) 창으로 렌더링됩니다.| 영역 | 내용 |
| 헤더 (Header) | 어두운 배경(#1e293b)의 드래그 가능 영역. 왼쪽에 팝업 제목(title), 오른쪽에 [✕] 닫기 버튼이 표시됩니다. |
| 본문 (Body) | 이미지(img_url이 있는 경우)와 에디터 내용(content가 있는 경우)이 순서대로 표시됩니다. 높이가 지정된 경우 스크롤 가능. |
| 푸터 (Footer) | hide_days > 0이면 "N일 동안 보지 않기" 체크박스 + 닫기 버튼. hide_days = 0이면 닫기 버튼만 표시됩니다. |
4.2 드래그 이동
방문자는 팝업 헤더 영역을 마우스로 드래그하여 팝업 창을 화면의 원하는 위치로 이동시킬 수 있습니다. 팝업이 화면 밖으로 나가지 않도록 좌표값이 0 미만이 되지 않게 제한됩니다.
💡 드래그 이동은 페이지 단위로 적용됩니다. 페이지를 새로고침하거나 다른 페이지로 이동하면 팝업이 설정된 초기 위치(pos_x, pos_y)로 다시 표시됩니다.
4.3 쿠키 기반 "다시 보지 않기" 상세 동작
방문자가 팝업 하단의 "N일 동안 보지 않기"를 체크하고 닫기를 클릭하면 다음과 같이 동작합니다.
- 브라우저에 쿠키 dx_popup_hide_{팝업ID}=1 이 저장됩니다.
- 쿠키 만료 시간은 현재 시간으로부터 hide_days × 86,400,000 밀리초로 설정됩니다.
- 이후 같은 브라우저로 사이트 방문 시, 페이지 로드 직후 JavaScript가 쿠키를 확인하여 해당 쿠키가 있으면 팝업 요소를 즉시 숨김(display:none) 처리합니다.
- 쿠키가 만료되면 다시 팝업이 표시됩니다.
⚠️ 쿠키는 도메인•경로 기준으로 저장됩니다(path=/). 동일 브라우저에서 사이트의 모든 페이지에 쿠키가 유효하게 적용됩니다. 단, 다른 기기•다른 브라우저에서는 쿠키가 공유되지 않습니다.
4.4 팝업 Z-index
팝업 창의 z-index는 99990으로 고정되어 있어 대부분의 페이지 요소 위에 표시됩니다. 다른 오버레이 UI(모달, 메뉴 등)와 z-index 충돌이 발생하면 해당 요소의 z-index를 99991 이상으로 조정하세요.
5. 팝업 등록 • 수정 • 삭제 절차
5.1 새 팝업 등록 절차
- 관리자 대시보드에서 [공지 팝업 관리] 메뉴 클릭
- 상단 오른쪽 [+ 팝업 신규 등록] 버튼 클릭 → /admin/popup/add 이동
- Domain 노출 범위 선택 (공통 또는 특정 도메인)
- 팝업 관리 제목 입력 (필수)
- 팝업 이미지 URL 입력 (선택)
- 클릭 시 이동 주소 입력 (선택, 이미지 클릭 링크)
- 노출 시작일 / 종료일 설정 (비워두면 상시 노출)
- X축•Y축 위치(px) 설정
- 팝업 너비•높이(px) 설정
- 출력 대상 디바이스 선택 (전체/PC/모바일)
- 다시 보지 않기 기간(일) 설정
- 이동 브라우저 탭 선택 (_blank / _self)
- 출력 정렬 순서 숫자 입력
- 팝업 활성화 스위치 선택 (ACTIVE / DISABLED)
- 팝업 상세 본문 에디터에서 내용 작성 (선택)
- [새로운 팝업 생성 및 배포] 버튼 클릭 → 목록으로 자동 이동
5.2 기존 팝업 수정 절차
- 팝업 목록에서 수정할 팝업의 [✏️] 버튼 클릭 → /admin/popup/{id} 이동
- 기존 설정값이 자동으로 채워진 폼에서 변경할 항목 수정
- [팝업 설정값 저장] 버튼 클릭
- 저장 완료 후 목록 페이지로 자동 이동하며 "팝업이 수정되었습니다." 성공 메시지 표시
5.3 팝업 삭제 절차
- 팝업 목록에서 삭제할 팝업의 [🗑] 버튼 클릭
- "[팝업 제목] 팝업 정보를 영구 삭제할까요?" 확인 창에서 [확인] 클릭
- DB에서 팝업 레코드 완전 삭제 및 캐시 초기화
- "팝업이 삭제되었습니다." 메시지와 함께 목록 새로고침
🚨 팝업 삭제는 복구가 불가능합니다. 임시로 숨기고 싶다면 삭제 대신 [Mute] 버튼으로 비활성화하거나 status를 DISABLED로 변경하세요.
5.4 빠른 상태 전환 (Mute / Live)
목록에서 각 팝업 오른쪽의 토글 버튼으로 추가 페이지 이동 없이 즉시 상태를 전환할 수 있습니다.| 버튼 | 동작 |
| Mute | 현재 ACTIVE 상태의 팝업을 클릭 즉시 DISABLED로 전환합니다. 사이트에서 팝업이 즉시 숨겨집니다(캐시 60초 내 반영). |
| Live | 현재 DISABLED 상태의 팝업을 클릭 즉시 ACTIVE로 전환합니다. 노출 기간 범위 내라면 즉시 사이트에 표시됩니다(캐시 60초 내 반영). |
6. 실전 활용 예시
자주 사용되는 팝업 유형별 권장 설정을 안내합니다.
예시 1: 이벤트 배너 팝업 (기간 한정)
| 설정 항목 | 권장 값 |
| 팝업 관리 제목 | 봄맞이 특가 이벤트 안내 |
| 팝업 이미지 URL | https://cdn.example.com/event-spring.jpg |
| 클릭 시 이동 주소 | /event/spring (이벤트 상세 페이지) |
| 이동 브라우저 탭 | 현재 탭에서 이동 (_self) |
| 노출 기간 | 2026-03-01 ~ 2026-03-31 (이벤트 기간) |
| 팝업 너비 | 500px |
| 위치 | X: 20px, Y: 100px |
| 출력 대상 기기 | 전체 (PC + 모바일) |
| 다시 보지 않기 | 3일 (3일 동안 보지 않기) |
| 활성화 상태 | ACTIVE |
예시 2: 사이트 공지 팝업 (상시)
| 설정 항목 | 권장 값 |
| 팝업 관리 제목 | 서버 점검 안내 (4월 15일 02:00~06:00) |
| 팝업 이미지 URL | (미입력 — 텍스트 공지만 사용) |
| 본문 에디터 | 에디터에 공지 텍스트 상세 내용 작성 |
| 노출 기간 | 2026-04-14 ~ 2026-04-15 (점검 당일까지) |
| 팝업 너비 | 400px |
| 팝업 높이 | 0 (자동) |
| 다시 보지 않기 | 0 (매번 표시 — 중요 공지라 숨김 불가) |
| 활성화 상태 | ACTIVE |
예시 3: 모바일 앱 설치 유도 팝업
| 설정 항목 | 권장 값 |
| 팝업 관리 제목 | 앱 다운로드 안내 |
| 팝업 이미지 URL | 앱 스토어 배너 이미지 URL |
| 클릭 시 이동 주소 | https://play.google.com/... (앱 마켓 URL) |
| 이동 브라우저 탭 | 새 창으로 열기 (_blank) |
| 팝업 너비 | 320px (모바일 화면 최적화) |
| 위치 | X: 10px, Y: 150px |
| 출력 대상 기기 | 모바일 전용 (mobile) |
| 다시 보지 않기 | 7일 |
| 노출 기간 | (미설정 — 상시 노출) |
예시 4: 복수 팝업 동시 운영 (위치 분산)
이벤트 팝업과 공지 팝업을 동시에 운영하면서 위치가 겹치지 않도록 설정하는 예시입니다.| 팝업명 | 너비 | X 위치 | Y 위치 | sort_order |
| 이벤트 배너 | 500px | 20px | 100px | 1 |
| 점검 공지 | 400px | 550px | 100px | 2 |
💡 이벤트 배너(500px)를 X:20에 배치하면 오른쪽 끝이 520px 위치. 공지 팝업을 X:550에 배치하면 겹치지 않습니다. 화면 해상도에 따라 조정이 필요할 수 있습니다.
7. 자주 묻는 질문 (FAQ)
Q1. 팝업을 ACTIVE로 설정했는데 사이트에 표시되지 않습니다.
A. 다음을 순서대로 확인하세요: ① 노출 기간(start_date~end_date)을 설정했다면 오늘 날짜가 해당 범위 내인지 확인. ② 출력 대상 기기가 현재 접속 기기와 일치하는지 확인(PC에서 확인 중인데 모바일 전용으로 설정되어 있지 않은지). ③ 이전에 "다시 보지 않기"를 클릭한 경우 브라우저 쿠키(dx_popup_hide_{id})를 삭제 후 확인. ④ 캐시가 있다면 최대 60초 후 자동 반영됩니다.
Q2. "다시 보지 않기" 쿠키를 즉시 초기화하려면?
A. 방문자 측: 브라우저 개발자 도구(F12) → Application → Cookies에서 dx_popup_hide_{id} 쿠키를 직접 삭제하면 됩니다. 관리자 측에서 쿠키를 강제로 초기화하는 기능은 없습니다. 단, 팝업을 삭제 후 동일 내용으로 재등록하면 새로운 ID로 생성되어 기존 쿠키가 무효화됩니다.
Q3. 팝업 여러 개가 겹쳐서 표시됩니다.
A. 각 팝업의 X•Y 위치값을 팝업 너비+간격을 고려하여 조정하세요. 예: 500px 너비 팝업을 X:20에 배치하면 X:540 이상부터 다음 팝업을 배치해야 겹치지 않습니다.
Q4. 모바일에서 팝업이 화면을 벗어납니다.
A. 모바일 전용(mobile) 팝업의 너비를 화면 너비보다 작게 설정하세요(권장: 300~360px). X 위치도 10~20px로 설정하여 화면 왼쪽 여백을 확보하세요. 또는 PC 전용 팝업은 device를 pc로 설정하여 모바일에서는 표시되지 않게 하세요.
Q5. 팝업 이미지를 클릭해도 링크가 작동하지 않습니다.
A. 이미지 URL(img_url)과 링크 URL(link_url)이 모두 입력되어 있는지 확인하세요. 이미지 URL만 있고 링크 URL이 비어있으면 클릭해도 이동하지 않습니다. 에디터 본문에서 이미지에 링크를 직접 삽입하는 방식으로도 구현할 수 있습니다.
Q6. 팝업을 저장 후 바로 적용되지 않는 것 같습니다.
A. DxPopup 엔진은 활성 팝업 목록을 최대 60초간 캐시합니다. 저장 즉시 캐시가 초기화되나, 브라우저 캐시가 있는 경우 60초 내에 반영됩니다. 즉시 확인하려면 브라우저에서 강제 새로고침(Ctrl+Shift+R 또는 Cmd+Shift+R)을 하거나 시크릿 창에서 접속하세요.
Q7. 팝업 본문에 유튜브 영상을 삽입하고 싶습니다.
A. 에디터 본문 콘텐츠 영역에서 iframe 삽입 기능을 사용하여 YouTube 임베드 코드를 삽입할 수 있습니다. 팝업 높이(height)를 적절히 설정하여 영상이 잘리지 않도록 하고, 팝업 너비(width)도 임베드 영상 너비에 맞게 조정하세요.
Q8. 특정 페이지에서만 팝업을 표시하려면?
A. DXCMS 기본 팝업 기능은 모든 페이지에서 동일하게 표시됩니다. 특정 페이지에서만 표시하려면 테마 파일에서 DxPopup::render() 호출 조건을 수정하거나, 팝업 본문에 JavaScript를 작성하여 현재 URL을 확인 후 특정 경로가 아니면 자동으로 숨기는 방식을 사용할 수 있습니다.
8. 용어 정리
| 용어 | 설명 |
| status | 팝업 활성화 여부. 1: ACTIVE(사용함), 0: DISABLED(중지함). |
| start_date / end_date | 팝업 노출 시작일·종료일(YYYY-MM-DD). NULL이면 기간 제한 없음. |
| pos_x / pos_y | 화면 좌상단 기준 팝업 표시 위치. px 단위. CSS position:fixed 기반. |
| width / height | 팝업 창 크기. px 단위. height=0이면 콘텐츠에 따라 자동 결정. |
| device | 출력 대상 기기. all(전체) / pc(PC 전용) / mobile(모바일 전용). |
| hide_days | "다시 보지 않기" 쿠키 유지 기간(일). 0이면 기능 비활성화. |
| sort_order | 팝업 출력 우선순위. 낮을수록 먼저 처리됨. |
| site_domain | 팝업이 귀속된 도메인. 빈 값이면 모든 사이트 공통. |
| img_url | 팝업 본문 상단에 표시할 이미지의 완전한 URL. |
| link_url | 이미지 클릭 시 이동할 링크 URL. |
| link_target | 링크 이동 방식. _blank(새 창) / _self(현재 탭). |
| content | 에디터로 작성한 팝업 본문 HTML 콘텐츠. DxSanitizer로 XSS 방지 처리됨. |
| DxPopup::getActive() | 조건(status=1, 기간, 기기)에 맞는 활성 팝업 목록을 반환하는 메서드. 결과를 60초 캐시. |
| DxPopup::render() | 활성 팝업 HTML을 출력하는 메서드. dx_body_bottom 훅에서 자동 호출됨. |
| DxCache::deletePrefix() | 팝업 저장/수정/삭제 시 popup_active_ 프리픽스 캐시를 일괄 초기화하는 메서드. |
| dx_popup_hide_{id} | 방문자 브라우저에 저장되는 "다시 보지 않기" 쿠키명. 팝업 ID마다 독립 관리. |
| CSRF 토큰 | 폼 위조 공격 방지 토큰. 저장/수정/삭제/토글 모든 POST 요청에 자동 포함. |
| User-Agent 기반 기기 판별 | 서버사이드에서 HTTP_USER_AGENT를 분석하여 모바일(Android, iPhone 등) 여부를 판단. 기기 설정 적용의 기준. |
| Live 상태 | status=1 이고 오늘 날짜가 start_date~end_date 범위 내에 있어 실제 사이트에 팝업이 표시되는 상태. |
| Wait 상태 | status=1 이나 노출 기간이 미도래이거나 이미 종료된 상태. 기간이 시작되면 자동으로 Live로 전환. |
| Idle 상태 | status=0 으로 관리자가 수동 비활성화한 상태. 기간과 무관하게 표시되지 않음. |