1장. DX 채팅 시스템 개요

DXCMS의 실시간 채팅은 dx-socket 플러그인이 제공합니다. 단순 채팅을 넘어 실시간 접속자 추적, 알림 벨, 댓글 실시간 삽입, 게시글 목록 실시간 갱신, 1:1 쪽지(DM)까지 하나의 WebSocket 연결로 처리하는 통합 실시간 엔진입니다.

1.1 DX Socket 플러그인 버전 및 기능 목록

plugins/dx-socket/plugin.php — v3.9.2 (소켓 코어 v1.7.0)
 

기능 모듈	기능 키	그룹	설명
실시간 접속자 추적	tracker	base	접속자 수 표시, 관리자 모니터, URL 추적
관리자 대시보드 위젯	admin_widget	base	대시보드에 실시간 접속 현황 위젯 표시
실시간 알림	notify	notify	좋아요·댓글·친구 등 실시간 알림 벨 + 토스트
댓글 실시간	comment_live	board	다른 사람이 댓글 작성 시 즉시 DOM 삽입
게시글 목록 실시간	post_live	board	새 글 작성 시 목록 상단에 즉시 표시
실시간 채팅	chat	chat	우측 하단 실시간 오픈 채팅방
실시간 메모(쪽지)	dm	notify	회원 간 1:1 쪽지 — 비접속 시 DB 보관

💡 기능 모듈 확장 설계
DX_SOCK_FEATURES 상수에 항목을 추가하기만 하면:
  → 관리자 소켓 설정 UI에 토글 자동 생성
  → settings 테이블에 자동 저장/로드 (plugin_dx-socket_use_{key})
  → DX_SOCKET.features.{key} 로 JS에서 분기 가능
새 기능을 추가해도 기존 코드를 수정할 필요 없습니다.

1.2 전체 아키텍처

┌─────────────────────────────────────────────────────────┐
│                  DXCMS 사용자 브라우저                    │
│  DX_SOCKET (JS 전역 변수)                               │
│    wsUrl: "wss://designonex.com:14147"                 │
│    group: "dxk_xxxxx_..." (API 키 = 소켓 그룹명)       │
│    mbId:  "user123" (로그인 아이디)                      │
│    features: { tracker, notify, chat, dm, ... }        │
└───────────────────┬─────────────────────────────────────┘
                    │ WebSocket (wss://)
┌───────────────────▼─────────────────────────────────────┐
│       소켓 서버 (wss://designonex.com:14147)             │
│  - group 단위로 클라이언트 격리                            │
│  - join / leave / chat / notify / dm / post_live 등     │
│  - /broadcast HTTP API (관리자 기능 업데이트용)           │
└───────────────────┬─────────────────────────────────────┘
                    │ API 키 검증
┌───────────────────▼─────────────────────────────────────┐
│       DXCMS 서버 (PHP)                                   │
│  dx_api_keys 테이블 — api_key (dxk_...) 발급            │
│  plugin_dx-socket_ws_url 설정 — 소켓 서버 URL            │
│  dx_notifications 테이블 — 알림 DB 보관                   │
│  dx_dm_messages 테이블 — DM 메시지 DB 보관               │
└─────────────────────────────────────────────────────────┘

1.3 소켓 그룹 격리 구조 (멀티사이트 지원)

소켓 서버는 group 파라미터로 사이트를 완전히 격리합니다. group은 dx_api_keys 테이블의 api_key 값(dxk_...)을 사용합니다. 따라서 도메인마다 독립된 채팅•알림 공간이 생성되며, 한 소켓 서버가 여러 DXCMS 사이트를 동시에 지원할 수 있습니다.

// 소켓 연결 시 그룹 파라미터 포함
ws = new WebSocket("wss://designonex.com:14147/?group=dxk_abc123&t=1234567890");

// 같은 group을 사용하는 클라이언트끼리만 통신
// → 사이트 A: group=dxk_aaa, 사이트 B: group=dxk_bbb  → 완전 격리

2장. WebSocket 이벤트 메시지 구조

모든 WebSocket 메시지는 JSON 형식입니다. type 필드로 이벤트 종류를 구분합니다.

2.1 클라이언트 → 서버 (송신) 이벤트

type	설명 및 주요 필드
join	접속 신고. mb_id, ip, url, is_mobile
update	URL 이동 시 위치 갱신. mb_id, ip, url, is_mobile
leave	탭 닫기/이동 시 퇴장 신고. mb_id, ip
chat	오픈 채팅 메시지 전송. mb_id, ip, uuid, message, is_mobile
notify	알림 전송. to_mb_id, from_mb_id, notif_type, message, url, time
comment_live	댓글 실시간 브로드캐스트. comment_id, post_url, from_mb_id, time
comment_update	댓글 수정 브로드캐스트. comment_id, post_url, content, from_mb_id
comment_delete	댓글 삭제 브로드캐스트. comment_id, post_url, from_mb_id
post_live	새 글 브로드캐스트. post_id, board_key, from_mb_id, time
dm	1:1 쪽지 전송. to_login_id, from_name, content_preview
dm_invite	1:1 채팅 초대. to_login_id, from_name, from_login_id, room_id
dm_invite_accept	초대 수락. to_login_id, room_id, mb_id
dm_invite_reject	초대 거절. to_login_id, room_id, mb_id
dm_chat	1:1 채팅 메시지. room_id, message, from_mb_id

2.2 서버 → 클라이언트 (수신) 이벤트

type	설명 및 처리 방식
init	연결 직후 현재 접속자 목록 + 최근 채팅 히스토리 (chat_history 배열)
join / update	접속자 activeUsers Map 갱신 → 접속자 수 업데이트
leave	activeUsers에서 해당 IP 제거
chat	채팅 메시지 수신 → addMsg() → 미읽음 배지 증가
notify	내 mb_id로 온 알림만 처리 → 벨 배지 증가 + 토스트 표시
comment_live	타인이 댓글 작성 → 현재 페이지 URL 확인 후 DOM 삽입
comment_update	타인의 댓글 수정 → DOM 인라인 업데이트
comment_delete	타인의 댓글 삭제 → DOM에서 제거
post_live	새 글 등록 → dxOnPostLive() 콜백 호출
dm	쪽지 수신 → 뱃지 증가 + 수신 모달 표시
dm_invite	1:1 채팅 초대 수신 → 초대 모달 표시
dm_invite_accept	상대방이 초대 수락 → 토스트 표시
dm_invite_reject	상대방이 초대 거절 → 토스트 표시
features_update	관리자가 기능 ON/OFF 변경 시 실시간 반영
global_notice_update	전체공지 변경 시 실시간 갱신

3장. dx-socket 플러그인 파일 구조

3.1 전체 파일 트리

plugins/dx-socket/
  ├── plugin.php              ← 메인 진입점. 기능 레지스트리 + 훅 등록
  ├── socket-core.js.php      ← WebSocket 클라이언트 JS 엔진 (PHP 포함 JS)
  │
  ├── chats/                  ← 채팅 UI 스킨 폴더
  │   ├── README.txt          ← 스킨 제작 가이드
  │   ├── default/            ← 기본 다크 채팅 스킨
  │   │   ├── chat.json       ← 스킨 메타 정보
  │   │   ├── chat.php        ← 채팅 UI HTML
  │   │   └── style.css       ← 채팅 전용 CSS
  │   └── bubble/             ← 카카오톡 스타일 말풍선 스킨
  │       ├── chat.json
  │       ├── chat.php
  │       └── style.css
  │
  └── admin/                  ← 관리자 전용 파일
      ├── settings.php        ← 소켓 설정 페이지 (/admin/plugins → 소켓)
      └── widget.php          ← 대시보드 실시간 접속 위젯

3.2 파일별 역할

파일	역할
plugin.php	기능 레지스트리 정의(DX_SOCK_FEATURES), API 키 조회, dx_head/dx_body_bottom 훅 등록
socket-core.js.php	WebSocket 연결 관리, 모든 이벤트 핸들러(chat/notify/dm/comment/post_live), 알림 토스트·모달 렌더링
chats/{스킨}/chat.php	채팅 버튼 + 채팅창 HTML 구조. plugin.php의 dx_body_bottom 훅에서 include
admin/settings.php	관리자 소켓 설정 UI (활성화, ws_url, 기능별 ON/OFF 토글)
admin/widget.php	대시보드 실시간 접속 현황 위젯 (접속자 수, 회원/비회원 비율)

3.3 로딩 시점 및 훅 흐름

// index.php → load_plugins() → plugins/dx-socket/plugin.php 실행

// 훅 1: dx_head (priority=5) — <head> 안쪽에 DX_SOCKET JS 변수 주입
var DX_SOCKET = {
  wsUrl:      "wss://designonex.com:14147",
  group:      "dxk_abc123...",   // API 키 = 소켓 그룹명
  mbId:       "user123",          // 로그인 아이디 (비로그인="")
  userIp:     "1.2.3.4",
  initUnread: 3,                  // 초기 미읽음 알림 수
  features: {
    tracker: true, notify: true, chat: true, dm: true,
    comment_live: true, post_live: true, admin_widget: true
  }
};

// 훅 2: dx_body_bottom (priority=99) — </body> 직전
// ① chats/{스킨}/chat.php include → 채팅 UI HTML 출력
// ② socket-core.js.php include → JS 엔진 출력 → connectWebSocket() 호출

4장. 오픈 채팅 기능 상세

4.1 오픈 채팅 동작 원리

오픈 채팅은 같은 소켓 그룹(같은 사이트)에 접속한 모든 사용자가 참여하는 공개 채팅방입니다. 최대 100개 메시지를 메모리에 유지하며, 새 접속자는 init 이벤트로 최근 히스토리를 받습니다.

[사용자A가 채팅 버튼 클릭]
    ↓ dxChatToggle() → dx-chat-box 표시
[메시지 입력 후 Enter 또는 전송 버튼]
    ↓ dxChatSend()
    ↓ sendEvent({ type:"chat", mb_id:"user123", uuid:"u1234...", message:"안녕!", ... })
    ↓ WebSocket → 소켓 서버
    ↓ 소켓 서버 → 같은 group 전체 브로드캐스트
[사용자B 수신]
    ↓ ws.onmessage → data.type === "chat" → addMsg(data, true)
    ↓ 채팅창이 닫혀 있으면 unreadCount++ → 빨간 배지 표시

4.2 채팅 설정 옵션

설정 키 (DB)	설명 및 값
plugin_dx-socket_use_chat	채팅 기능 ON/OFF. "1"=활성, "0"=비활성
plugin_dx-socket_chat_position	채팅 버튼 위치. "right"(기본) 또는 "left"
plugin_dx-socket_chat_login_only	"1"이면 로그인 사용자만 메시지 전송 가능. "0"이면 비로그인도 가능
plugin_dx-socket_chat_skin	채팅 스킨. "default"(다크) 또는 "bubble"(말풍선)

4.3 모바일 채팅 최적화

isMobile 판별 후 모바일에서는 채팅창이 전체화면으로 표시됩니다.

• visualViewport 대응 — 키보드 올라와도 채팅 입력창이 가려지지 않음
• overflow:hidden — 채팅창 열림 시 body 스크롤 차단
• 전체화면 모드 — width:100%, height:visualViewport.height, position:fixed
• 닫힘 시 복원 — 원래 인라인 스타일 및 body.overflow 복원

4.4 채팅 메시지 최대 개수

var MAX_MSG = 100; // 최대 100개 유지
// 100개 초과 시 가장 오래된 메시지(chatMsgs[0]) DOM에서 제거
// 새 접속자는 소켓 서버에서 최근 히스토리를 init 이벤트로 받음

5장. 채팅 스킨 시스템

5.1 기본 제공 스킨

스킨 폴더명	이름	특징
default	기본 채팅	다크 테마. 배경 #1e293b, 텍스트 #f1f5f9. 파란 전송 버튼
bubble	버블 채팅	카카오톡 스타일 밝은 말풍선. 내 메시지 파란 말풍선, 상대 흰 말풍선

5.2 채팅 스킨 파일 구조

plugins/dx-socket/chats/{스킨명}/
  ├── chat.json    ← 스킨 메타 정보 (필수)
  ├── chat.php     ← 채팅 UI HTML (필수)
  └── style.css    ← 전용 CSS (선택)

5.3 chat.json 형식

{
    "name":        "내 채팅 스킨",
    "description": "커스텀 채팅 UI",
    "version":     "1.0.0",
    "author":      "개발자명",
    "preview":     "우측 하단 채팅창 설명"
}

5.4 chat.php 사용 가능 변수

변수	타입 및 설명
$pos	string — 위치 CSS. "right:20px" 또는 "left:20px"
$canChat	bool — 메시지 전송 가능 여부. chat_login_only + 로그인 상태 종합
$loginOnly	bool — 로그인 전용 여부 (chat_login_only 설정값)
$mbId	string — 현재 로그인 아이디. 비로그인이면 빈 문자열

5.5 chat.php 필수 HTML ID

HTML ID	역할
dx-chat-wrap	전체 래퍼 div. position:fixed, z-index:99999
dx-chat-box	채팅창 div. 반드시 display:none으로 시작
dx-chat-messages	메시지 목록. addMsg()가 여기에 div 추가
dx-chat-input	텍스트 입력란. onkeydown Enter → dxChatSend()
dx-chat-btn	채팅 토글 버튼.>
dx-chat-online	접속자 수 표시 span. "N명 접속중" 자동 업데이트
dx-chat-badge	미읽음 배지. display:none으로 시작. 자동 증감

5.6 커스텀 채팅 스킨 만들기

1. plugins/dx-socket/chats/ 폴더에 새 폴더 생성 (예: my-chat/)
2. chat.json 생성 (name, description 입력)
3. chat.php 작성 (위 필수 ID 모두 포함, dxChatToggle/dxChatSend 연결)
4. 관리자 → 실시간 소켓 → 설정에서 채팅 스킨 선택 후 저장

⚠️ 필수 ID 누락 시 문제
dx-chat-messages가 없으면: addMsg()가 메시지 추가 불가 → 채팅 표시 안 됨
dx-chat-btn이 없으면: 채팅 버튼이 화면에 표시되지 않음
dx-chat-badge가 없으면: 미읽음 카운트 표시 불가
dxChatToggle() 미연결 시: 채팅창 열기/닫기 불가

6장. 실시간 알림 시스템

6.1 알림 흐름

[사용자A가 게시글에 좋아요/댓글 클릭]
    ↓ 댓글/좋아요 API 응답에 notify_targets 배열 포함
    ↓ dxSockNotify(apiResp) 호출 (view.php의 JS)
    ↓ sendEvent({ type:"notify", to_mb_id:"글쓴이", notif_type:"like", ... })
    ↓ 소켓 서버 → 해당 to_mb_id가 접속 중인 경우 라우팅
[글쓴이(사용자B) 수신]
    ↓ ws.onmessage → data.type === "notify" && data.to_mb_id === MB_ID
    ↓ dxNotifReceive(data)
    ↓ ① dxNotifCount++ → 벨 배지 증가
    ↓ ② dxNotifToast() → 우측 상단 토스트 3.5초 표시
    ↓ ③ DxNotifV540.setBadge() → 헤더 벨 아이콘 동기화

// 동시에 DB에도 저장 (dx_notifications 테이블)
// → 알림 패널 열 때 /api/notification 으로 조회

6.2 알림 타입별 토스트 아이콘

notif_type	이모지	메시지 형식
comment	💬	{MB_ID}님이 댓글을 남겼습니다.
comment_reply	↩️ (답글)	{MB_ID}님이 답글을 남겼습니다.
like	❤️	{MB_ID}님이 좋아요를 눌렀습니다.
scrap	⭐	{MB_ID}님이 글을 스크랩했습니다.
friend	👥	{MB_ID}님이 친구를 추가했습니다.

6.3 알림 DB 구조 (dx_notifications)

소켓으로 전달하는 동시에 dx_notifications 테이블에도 저장합니다. 비접속 상태 사용자도 로그인 후 알림 패널에서 확인 가능합니다.

-- dx_notifications 테이블 주요 컬럼
id          : 알림 ID
member_id   : 수신자 회원 ID
type        : comment|like|scrap|friend 등
message     : 알림 메시지
url         : 클릭 시 이동할 URL
is_read     : 0=미읽음, 1=읽음
created_at  : 생성일시

6.4 알림 API

엔드포인트	설명
GET /api/notification?_sub=list&limit=20	알림 목록 조회 (최신 20개, 미읽음 수 포함)
POST /api/notification (_sub=read)	개별 알림 읽음 처리. id 파라미터 필요
POST /api/notification (_sub=read_all)	전체 알림 읽음 처리

7장. 1:1 쪽지(DM) 시스템

7.1 DM 두 가지 방식

방식	설명
소켓 DM (쪽지)	상대방이 접속 중이면 WebSocket dm 이벤트로 즉시 전달. 비접속 시 DB 보관 → 로그인 후 마이페이지 메모함에서 확인
1:1 채팅 초대	상대방이 접속 중일 때 dm_invite 이벤트로 실시간 채팅창 연결. room_id 기반 독립 채팅방. 대화 내용 dm_messages 테이블에 저장

7.2 쪽지(DM) 흐름

[사용자A가 마이페이지 → 메모함에서 쪽지 작성]
    ↓ POST /api/dm (쪽지 DB 저장)
    ↓ 소켓: sendEvent({ type:"dm", to_login_id:"userB", from_name:"A", content_preview:"안녕!" })

[사용자B 수신 — 접속 중인 경우]
    ↓ ws.onmessage → data.type === "dm" && data.to_login_id === MB_ID
    ↓ dxDmBadgeIncr() — 마이페이지 메모 탭 뱃지 증가
    ↓ dxDmModal() — "새 메모가 도착했습니다" 모달 팝업
    ↓ "메모 확인" 클릭 → /auth/mypage?tab=memo&mbox=received 이동

7.3 1:1 채팅 초대 흐름

[사용자A가 접속자 목록에서 B에게 "1:1 채팅" 클릭]
    ↓ sendEvent({ type:"dm_invite", to_login_id:"userB",
                  from_name:"A", from_login_id:"userA", room_id:"room_xxx" })

[사용자B 수신]
    ↓ dxDmInviteModal("A", "userA", "room_xxx") — 초대 모달 팝업
    ↓ "대화 참여" 클릭:
        ① sendEvent({ type:"dm_invite_accept", to_login_id:"userA", room_id }) → A에게 수락 알림
        ② dxOpenDmChat("userA", "A", "room_xxx") — 1:1 채팅창 열기
    ↓ "대화 거절" 클릭:
        ① sendEvent({ type:"dm_invite_reject", to_login_id:"userA", room_id }) → A에게 거절 알림

7.4 DM 채팅 메시지 DB 구조

-- dx_dm_messages 테이블 (API 호출 시 자동 생성)
id         : BIGINT — 메시지 ID
chat_group : VARCHAR(32) — MD5 그룹 키 (두 사용자 ID의 조합)
member_id  : INT — 발신자 회원 ID
message    : TEXT — 메시지 내용 (최대 2000자)
created_at : DATETIME

7.5 DM 채팅 API

엔드포인트	설명
GET /api/chat_dm?group=MD5&after=ID	MD5 그룹의 메시지 조회 (after ID 이후 50개)
POST /api/chat_dm (_sub=send)	메시지 저장. group, message 필수. 최대 2000자

8장. 접속자 추적 및 댓글•게시글 실시간

8.1 접속자 추적

tracker 기능이 ON이면 모든 페이지에서 join/update 이벤트를 소켓 서버로 전송합니다.
 

// History API 후킹 (SPA 동작 지원)
history.pushState  → reportLocationUpdate()
history.replaceState → reportLocationUpdate()
window.popstate    → reportLocationUpdate()

// reportLocationUpdate(): 현재 URL 소켓 서버에 전송
sendEvent({ type:"update", mb_id, ip, url:location.pathname+location.search, is_mobile })

// 탭 닫기 시
window.beforeunload → gracefulDisconnect()
  → ws.send({ type:"leave" }) + navigator.sendBeacon("/ws-leave")

activeUsers Map: IP를 키로 사용. 회원 정보(mb_id)가 있으면 비회원 데이터보다 우선. 관리자 대시보드 위젯에서 실시간 접속자 목록 표시.

8.2 댓글 실시간 삽입 (comment_live)

다른 사람이 댓글을 작성하면 현재 같은 게시글 페이지를 보고 있는 모든 사용자의 화면에 댓글이 실시간으로 삽입됩니다.

[댓글 등록 후 /api/comment 응답]
    ↓ dxSockNotify(apiResp) → comment_live 브로드캐스트

[다른 사용자의 ws.onmessage]
    ↓ data.type === "comment_live"
    ↓ 현재 페이지 pathname === data.post_url? → 일치하면 처리
    ↓ GET /api/comment?_sub=get&id={comment_id} → 댓글 HTML 요소 생성
    ↓ data-depth / data-parent 속성 기반으로 올바른 계층 위치에 insertBefore
    ↓ 2초간 노란 하이라이트 + scrollIntoView(smooth)
    ↓ 댓글 수 +1 업데이트

8.3 게시글 목록 실시간 (post_live)

새 글이 등록되면 같은 게시판 목록 페이지를 보고 있는 사용자의 화면에 실시간으로 새 글이 표시됩니다.

[글 저장 완료 후]
    ↓ dxSockPostNew(postId, boardKey) 호출
    ↓ sendEvent({ type:"post_live", post_id, board_key, from_mb_id, time })

[다른 사용자의 ws.onmessage]
    ↓ data.type === "post_live" && from_mb_id !== MB_ID (내 글 제외)
    ↓ dxOnPostLive(data.post_id, data.board_key) 호출
    ↓ 현재 페이지가 해당 게시판 목록이면 목록 상단에 새 글 삽입

9장. API 키(dxk_) 관리

소켓 연결에는 dxk_ 접두사의 API 키가 필수입니다. 이 키가 없으면 소켓 연결이 차단됩니다. 키는 dx_api_keys 테이블에 도메인별로 저장됩니다.

9.1 API 키 발급 단계

1. 관리자 → 실시간 소켓 메뉴 클릭
2. "API 키 관리" 탭 클릭
3. 도메인 선택 (멀티사이트: 드롭다운에서 도메인 선택)
4. 사이트 이름, 메모 입력 후 "키 발급" 버튼 클릭
5. dxk_{도메인MD5 앞8자}_{랜덤24자hex} 형식의 키 생성
6. dx_api_keys 테이블에 저장 + 중앙서버 push (실패해도 DXCMS는 정상 동작)
7. "키 발급됨" 초록 배지 확인

9.2 dx_api_keys 테이블 주요 컬럼

컬럼	타입	설명
api_key	VARCHAR(64)	발급된 소켓 그룹 키. "dxk_" 접두사. UNIQUE
site_domain	VARCHAR(191)	사이트 도메인 (포트 제거, 소문자)
site_name	VARCHAR(191)	사이트 표시 이름
site_url	VARCHAR(300)	사이트 대표 URL
platform	VARCHAR(10)	"web" 또는 "android"/"ios" (DXMB 앱 등록 시)
app_package	VARCHAR(191)	앱 패키지명 (DXMB 안드로이드: com.domain.app)
app_key_hash	VARCHAR(255)	안드로이드 서명 키해시 / iOS Team ID
status	TINYINT	0=비활성, 1=활성, 2=정지
expires_at	DATETIME	NULL=영구 유효. 날짜 지정 시 만료

9.3 멀티사이트 도메인별 독립 소켓

dx_sites 테이블에 등록된 멀티사이트 환경에서는 도메인 셀렉트박스로 각 도메인의 소켓 키를 독립 관리합니다.

// plugin.php에서 현재 서버 도메인 기준 키 조회
$domain = strtolower(preg_replace("/:d+$/", "", $_SERVER["HTTP_HOST"]));
$row = $db->row(
    "SELECT api_key FROM dx_api_keys WHERE site_domain=? AND status=1 LIMIT 1",
    [$domain]
);
$apiKey = ($row && strpos($row["api_key"],"dxk_") === 0) ? $row["api_key"] : "";
// 키가 없으면 return → 소켓 로드 자체를 차단

10장. 관리자 설정 사용방법

10.1 관리자 → 실시간 소켓 메뉴

관리자 → 실시간 소켓 (/admin/socket)에는 두 가지 탭이 있습니다.
 

탭	기능
모니터 & 설정	실시간 트래픽 모니터 (접속자 현황, 회원/비회원, 모바일%) + WebSocket 서버 설정 + 기능별 ON/OFF 토글
API 키 관리	도메인별 dxk_ 키 발급, 상태 변경, 삭제

10.2 모니터 & 설정 탭 상세

• 실시간 트래픽 모니터 — 접속자 총계, 회원수, 비회원수, 모바일 비율 실시간 표시. ALL/MEMBER/GUEST 필터
• WebSocket 서버 URL — 기본값: wss://designonex.com:14147. 자체 소켓 서버 운영 시 변경
• 중앙서버 URL — 기본값: https://designonex.com. API 키 발급 시 push 대상
• 플러그인 활성화 — 전체 소켓 기능 ON/OFF (개별 기능 토글과 별개)
• 기능별 ON/OFF 토글 — 기반(tracker, admin_widget), 알림(notify, dm), 게시판(comment_live, post_live), 채팅(chat) 그룹별 토글

10.3 기능별 토글 저장 방식

// settings 테이블 저장 형식
plugin_dx-socket_enabled           = "1"  (전체 활성화)
plugin_dx-socket_ws_url            = "wss://designonex.com:14147"
plugin_dx-socket_use_tracker       = "1"
plugin_dx-socket_use_chat          = "1"
plugin_dx-socket_use_notify        = "1"
plugin_dx-socket_use_dm            = "1"
plugin_dx-socket_use_comment_live  = "1"
plugin_dx-socket_use_post_live     = "1"
plugin_dx-socket_use_admin_widget  = "1"

// 저장 즉시 소켓 서버로 features_update 브로드캐스트
// → 현재 접속 중인 모든 클라이언트의 DX_SOCKET.features 실시간 업데이트

10.4 플러그인 설정 (소켓 설정 관리)

관리자 → 플러그인 → 모듈 설정 탭에서 "소켓" 드롭다운에서 "DX 실시간 소켓"을 선택하면 플러그인이 활성화됩니다. 이후 관리자 → 실시간 소켓 메뉴에서 세부 설정을 진행합니다.

10.5 채팅 세부 설정

1. 관리자 → 실시간 소켓 → 모니터 & 설정 탭
2. "채팅 세부 설정" 섹션에서 아래 항목 설정
3. 채팅 버튼 위치: 우측 하단(기본) 또는 좌측 하단
4. 로그인 전용: ON이면 비로그인 사용자 메시지 전송 불가
5. 채팅 스킨: default(다크) 또는 bubble(말풍선) 선택
6. 저장 후 즉시 적용 확인

11장. DXMB 모바일 앱 연동

DXMB는 DXCMS 기반 사이트의 웹뷰 앱(Android/iOS)입니다. DXCMS의 소켓 시스템과 연동되어 웹과 동일한 실시간 기능(채팅, 알림, DM)을 앱에서도 이용할 수 있습니다.

11.1 DXMB 앱이란

• 플랫폼 — Android / iOS 네이티브 웹뷰 앱
• 핵심 기능 — DXCMS 사이트의 웹 콘텐츠를 앱으로 포장. 소켓 연동, 푸시 알림, 앱 스토어 배포
• 소켓 연동 방식 — WebSocket URL(wss://)과 API 키(dxk_)를 웹뷰에서 그대로 사용
• API 키 등록 — dx_api_keys 테이블에 platform="android"/"ios"로 별도 키 등록 가능

11.2 DXMB 앱용 API 키 등록

앱 전용 API 키는 dx_api_keys 테이블에 직접 INSERT하거나, 향후 관리자 소켓 UI에서 앱 키 발급 기능을 통해 등록합니다.

-- 앱 전용 키 등록 예시 (직접 SQL)
INSERT INTO dx_api_keys
  (id, api_key, site_domain, site_name, site_url, platform, app_package, status, issued_by, created_at)
VALUES
  (UNIX_TIMESTAMP(), "dxk_xxxxxxxx_yyyyyyyy",
   "mysite.com", "내 사이트", "https://mysite.com",
   "android", "com.mysite.app", 1, "admin", NOW());

-- 조회: 해당 도메인의 앱 키
SELECT api_key FROM dx_api_keys
WHERE site_domain="mysite.com" AND platform="android" AND status=1;

11.3 DXMB와 DXCMS 소켓 연동 흐름

[앱 실행]
    ↓ 웹뷰에서 DXCMS URL 로드
    ↓ dx-socket plugin.php → dx_head 훅 → DX_SOCKET JS 변수 주입
    ↓ socket-core.js.php → connectWebSocket()
    ↓ wss://designonex.com:14147/?group=dxk_xxx

[앱 내 실시간 기능]
    ↓ 채팅: 웹과 동일한 채팅창 (chat.php HTML)
    ↓ 알림: 소켓 notify 이벤트 → 앱 내 토스트 표시
    ↓ DM: 쪽지 수신 시 dxDmModal() 팝업

[푸시 알림 (별도 구현)]
    ↓ FCM(Firebase) 또는 APNs 연동으로 앱 백그라운드 알림
    ↓ dx_after_write, dx_after_comment 훅에서 푸시 발송 플러그인 연결

11.4 DXMB 앱 핵심 설정 체크리스트

• [ ] DXCMS dx-socket 플러그인 활성화 및 API 키(dxk_) 발급 완료
• [ ] 소켓 서버 URL (wss://designonex.com:14147) 접근 가능 여부 확인
• [ ] 앱 웹뷰 JavaScript 허용 설정
• [ ] 앱 웹뷰 WebSocket 연결 허용 (AndroidManifest.xml: usesCleartextTraffic 설정)
• [ ] DXCMS 설정: site_url이 HTTPS로 올바르게 설정되어 있는지 확인
• [ ] CSP (Content-Security-Policy) 헤더가 wss:// 연결 차단하지 않는지 확인
• [ ] 채팅 로그인 전용 설정 확인 (앱 사용자 로그인 여부)

11.5 DXMB 관련 API 엔드포인트

엔드포인트	설명
POST /api/receive_socket_key	앱에서 API 키 수신·저장. api_key, site_domain 필수. dxk_ 접두사 검증
GET /api/chat_dm	앱 내 1:1 DM 채팅 메시지 조회
POST /api/chat_dm	앱 내 1:1 DM 메시지 저장
GET /api/notification	앱 내 알림 목록 조회

12장. 자주 묻는 질문 (FAQ)

Q1. 소켓 연결이 안 됩니다. 어떻게 확인하나요?

① 관리자 → 실시간 소켓에서 "키 없음" 표시되면 API 키를 먼저 발급하세요. ② 브라우저 DevTools → Network → WS 탭에서 WebSocket 연결 상태를 확인하세요. ③ wss://designonex.com:14147 접근이 방화벽에서 차단되지 않은지 확인하세요.

Q2. 채팅 스킨을 새로 만들었는데 관리자에서 선택이 안 됩니다.

chat.json 파일이 없거나 JSON 형식 오류인 경우입니다. chats/{스킨명}/chat.json 파일이 올바른 JSON으로 존재하는지 확인하세요. 관리자 소켓 설정에서 채팅 스킨 드롭다운이 자동으로 갱신됩니다.

Q3. 댓글 실시간 기능(comment_live)이 동작하지 않습니다.

① 관리자 → 실시간 소켓 → "댓글 실시간" 기능이 ON인지 확인하세요. ② 댓글 등록 API 응답에 dxSockNotify()를 호출하는 JS 코드가 있는지 확인하세요. ③ 수신 측: ws.readyState === WebSocket.OPEN 상태인지 확인하세요.

Q4. 알림이 오는데 벨 배지에 표시가 안 됩니다.

헤더에 id="dx-notif-badge" 요소가 있는지 확인하세요. 또는 window.DxNotifV540.setBadge() 함수가 정의되어 있지 않은 경우입니다. 테마의 layout/main.php에 알림 벨 아이콘과 배지 HTML이 포함되어 있어야 합니다.

Q5. 자체 소켓 서버를 운영하고 싶습니다.

관리자 → 실시간 소켓 → WebSocket 서버 URL 필드를 자체 서버 주소(예: wss://myserver.com:8080)로 변경하면 됩니다. 소켓 서버는 group 파라미터로 사이트를 격리하고, /broadcast 엔드포인트로 features_update 이벤트를 수신할 수 있어야 합니다.

Q6. DXMB 앱에서 푸시 알림을 받으려면?

dx-socket 플러그인의 소켓 알림은 앱이 포그라운드일 때만 동작합니다. 백그라운드 푸시 알림은 FCM(Firebase Cloud Messaging) 또는 APNs 연동 플러그인을 별도로 개발해야 합니다. dx_after_comment, dx_after_write 훅에서 FCM API를 호출하는 방식으로 구현합니다.

Q7. 채팅 참여자가 많을 때 성능 이슈가 있나요?

소켓 서버(designonex.com:14147)는 group 단위로 클라이언트를 관리합니다. 클라이언트 수가 많아지면 broadcast 부하가 증가할 수 있습니다. 최대 채팅 메시지 유지 수(MAX_MSG=100)는 클라이언트 메모리에만 영향을 줍니다. 대규모 운영 시 자체 소켓 서버 운영을 권장합니다.