G7 사용자 동의 관리 플러그인 - Glitter GDPR

개요

glitter-gdpr는 그누보드7(G7) 환경에서 쿠키 및 개인정보 관련 사용자 동의를 관리하는 독립 GDPR 플러그인입니다.

단순히 쿠키 동의 배너를 표시하는 데서 끝나지 않고, 사이트가 실제 사용하는 동의 항목과 방문자의 선택, 정책 변경에 따른 재동의, 동의 전 외부 resource 차단을 하나의 흐름으로 관리합니다.

또한 현재 방문자의 동의 상태를 Public Consent Runtime Contract로 제공하여 다른 template / module / plugin이 GDPR 플러그인의 database, cookie 또는 session 구조를 직접 알지 않고도 동일한 consent 상태를 재사용할 수 있도록 구성했습니다.

주요 범위는 다음과 같습니다.

• 필수 / 기능 / 분석 / 마케팅 동의 관리
• 사이트별 consent category 활성 / 비활성 설정
• 회원 / 게스트 동의 상태 관리
• 정책 버전 및 재동의 흐름
• 동의 전 외부 추적 차단
• frontend consent snapshot 조회
• consent 상태 변경 subscription
• 로그인 / 로그아웃에 따른 visitor identity 동기화
• 사이트별 쿠키 배너 문구 설정
• category별 한국어 / 영어 사용자 안내 문구 설정
• Admin에서 default / override effective 문구 확인
• 다른 G7 확장에서 사용할 수 있는 public runtime contract

이 기능을 하나의 독립적인 consent provider 계층으로 연결합니다.

관리자 설정
    ↓
Visitor Consent UI
    ↓
Consent State
    ↓
Effective Consent
    ↓
Public Runtime / Auto Blocker

현재 버전은 v0.5.2입니다.

이 플러그인은 기존 프로젝트에서 커스텀하여 사용하던 sirsoft-gdpr 구현에서 출발했지만, 현재는 identifier, namespace, route, permission, settings, frontend runtime, asset, cookie, database identity를 분리한 독립 플러그인 계보로 유지보수합니다.

공식 SIRSOFT 또는 공식 GnuBoard7 GDPR 플러그인 릴리스가 아닙니다.

---

주요 기능

사용자 동의 관리

현재 다음 consent category를 기준으로 사용자 동의를 관리할 수 있습니다.

• Necessary
• Functional
• Analytics
• Marketing

Necessary는 서비스 제공에 필요한 필수 category이며 항상 활성화됩니다.

Functional, Analytics, Marketing은 사이트에서 실제 사용하는 기능에 따라 관리자가 각각 활성화하거나 비활성화할 수 있습니다.

예를 들어 Analytics나 Marketing 기능을 사용하지 않는 사이트라면 해당 category를 OFF로 설정할 수 있습니다.

비활성화된 category는 단순히 화면에서만 숨겨지는 것이 아니라,

• 방문자 consent 선택 UI에서 제외
• effective consent를 false로 강제
• 과거에 저장된 true consent를 현재 정책에 자동 적용하지 않음
• runtime blocker에서는 fail-closed 유지

원칙으로 처리합니다.

구조는 다음과 같습니다.

Category Availability
        ↓
Consent UI
        ↓
Consent State
        ↓
Effective Consent
        ↓
Runtime / Auto Blocker

즉, 현재 사이트가 실제 사용하는 category와 방문자가 동의한 category를 함께 판단합니다.

Category Availability

관리자는 사이트에서 실제 사용하는 선택적 consent category를 설정할 수 있습니다.

Necessary
Functional
Analytics
Marketing

Necessary는 항상 ON이며 비활성화할 수 없습니다.

나머지 category는 사이트 운영 정책에 따라 ON/OFF할 수 있습니다.

예를 들어 다음과 같이 운영할 수 있습니다.

Necessary  : ON
Functional : ON
Analytics  : OFF
Marketing  : OFF

이 경우 방문자에게는 Necessary와 Functional만 표시됩니다.

Analytics와 Marketing은 선택 UI에 나타나지 않으며 effective consent 역시 항상 false입니다.

category를 OFF로 설정한다는 것은

동의 없이 사용해도 된다

는 의미가 아닙니다.

정확한 의미는

현재 사이트에서는 이 category를 사용하지 않는다

입니다.

따라서 비활성 category에 해당하는 resource가 발견되어도 blocker는 이를 자동 허용하지 않고 fail-closed 원칙을 유지합니다.

회원 / 비회원 동의 처리

회원과 비회원의 consent 상태를 각각 현재 visitor 기준으로 처리합니다.

Frontend consumer는 내부적으로 사용되는

• 회원 ID
• guest UUID
• cookie identifier
• consent record ID
• 내부 session key

등을 직접 알 필요가 없습니다.

확장 기능은 현재 방문자에게 적용되는 consent 결과만 public runtime을 통해 사용할 수 있습니다.

---

Public Consent Runtime Contract

glitter-gdpr는 다른 frontend extension이 현재 consent 상태를 안정적으로 재사용할 수 있도록 public runtime contract를 제공합니다.

현재 주요 API는 다음과 같습니다.

getSnapshot()
refresh()
subscribe()
invalidate()

getSnapshot()

현재 frontend runtime이 알고 있는 consent snapshot을 즉시 반환합니다.

refresh()

현재 visitor identity를 기준으로 서버의 consent 상태를 다시 확인하고 snapshot을 갱신합니다.

subscribe()

동의 상태가 변경될 때 이미 mount된 template / module / plugin component가 변경을 구독하고 다시 판단할 수 있도록 합니다.

invalidate()

로그인 / 로그아웃처럼 현재 visitor identity가 변경되는 경우 기존 snapshot을 무효화하고 새로운 visitor 기준 상태를 다시 확인할 수 있도록 합니다.

---

Consent Snapshot

Public runtime은 extension consumer가 필요한 최소 consent 정보만 노출하는 방향으로 구성되어 있습니다.

category contract는 다음 네 개의 boolean key를 유지합니다.

{
  "categories": {
    "necessary": true,
    "functional": true,
    "analytics": false,
    "marketing": false
  }
}

전체 snapshot에서는 개념적으로 다음과 같은 상태를 함께 다룹니다.

status
contractVersion
categories
needsRenewal
currentPolicyVersion

내부 visitor 식별 정보는 public contract에 노출하지 않습니다.

따라서 다른 G7 확장 기능은 glitter-gdpr의 database, cookie 또는 session 구현에 직접 결합하지 않고 consent 결과만 사용할 수 있습니다.

---

Fail-closed 구조

비동기 consent 상태 확인 과정에서는 페이지 최초 진입 시 아직 상태를 알 수 없는 시점이 존재할 수 있습니다.

glitter-gdpr는 이 상태를 임의로 동의한 상태로 처리하지 않습니다.

개념적으로 다음과 같은 흐름을 사용합니다.

unknown
   ↓
Consent API 확인
   ↓
ready

API 오류나 malformed response가 발생하는 경우에도 임의로 consent를 허용하지 않고 안전한 상태를 유지합니다.

외부 SDK를 사용하는 consumer에서는 다음과 같은 방식으로 활용할 수 있습니다.

unknown
→ 기능 실행하지 않음

ready + category=false
→ 기능 실행하지 않음

ready + needsRenewal=true
→ 기능 실행하지 않음

ready + required category=true
→ consumer 정책에 따라 실행

즉, GDPR 플러그인은 현재 consent 상태를 제공하고, 실제 기능을 실행할지는 각 extension이 판단합니다.

---

Auto Blocking

glitter-gdpr는 동의가 필요한 resource가 consent 이전에 실행되는 것을 방지하기 위한 enforcement 구조를 제공합니다.

특히 Analytics / Marketing과 같은 선택 category는 현재 effective consent가 허용되지 않았다면 실행하지 않는 방향으로 처리합니다.

비활성 category 역시 예외가 아닙니다.

Category OFF
      ↓
현재 사이트에서 사용하지 않음
      ↓
Effective Consent = false
      ↓
Resource 자동 허용 금지
      ↓
Fail-closed

따라서 category availability와 runtime blocking은 서로 다른 역할을 가지면서도 일관된 consent 결과를 사용합니다.

---

로그인 / 로그아웃과 Consent 동기화

SPA 환경에서는 guest 상태에서 읽은 consent snapshot이 로그인 후에도 잠시 남아 있을 수 있습니다.

glitter-gdpr는 G7 Core AuthManager의 authStateChange와 consent runtime을 연결하여 visitor identity 변경 시 snapshot을 다시 동기화합니다.

구조는 다음과 같습니다.

AuthManager
      ↓
authStateChange
      ↓
Consent Snapshot invalidate
      ↓
unknown
      ↓
현재 visitor 기준 refresh
      ↓
새 Consent Snapshot

이 과정에서도 실제 회원 ID나 guest identifier를 frontend extension에 노출하지 않습니다.

G7 Core는 인증 상태 변경만 알리고, glitter-gdpr가 자신의 consent API를 통해 현재 visitor 상태를 다시 판단합니다.

---

비동기 Race Condition 보호

로그인 / 로그아웃 도중 기존 consent 요청이 늦게 응답하는 경우 이전 visitor의 결과가 새 identity의 snapshot을 덮어쓰면 안 됩니다.

예를 들어:

Guest consent refresh 시작
        ↓
사용자 Login
        ↓
새 identity refresh 시작
        ↓
새 응답 도착
        ↓
이전 Guest 응답이 늦게 도착

와 같은 상황을 고려합니다.

glitter-gdpr는 identity generation 기준으로 오래된 async response가 새로운 visitor 상태를 덮어쓰지 않도록 보호합니다.

동일 identity에서 여러 component가 동시에 refresh()를 호출하는 경우에는 in-flight request를 공유하여 중복 요청도 줄입니다.

---

Enforcement와 Provider Runtime 분리

glitter-gdpr는 consent provider와 실제 방문자 enforcement를 분리해서 사용할 수 있습니다.

enforcement_enabled 설정을 통해 visitor-facing enforcement를 비활성화할 수 있습니다.

비활성화되는 항목은 다음과 같습니다.

• public consent banner
• pre-blocking
• storage / cookie interceptor
• cleanup
• response cookie filtering

반면 다음 기능은 유지됩니다.

• public consent provider
• consent status runtime
• public consent API

즉,

Consent Provider
        ≠
Visitor Enforcement

구조로 사용할 수 있습니다.

---

Public Consent Overlay

glitter-gdpr는 G7의 public extension 구조를 통해 consent banner와 관련 overlay UI를 제공합니다.

Public consent UI는 특정 사용자 template이 자체적으로 GDPR 배너를 구현할 필요가 없도록 plugin-owned UI로 구성되어 있습니다.

활성 template이 공식 user_global_overlay extension point를 제공하면 해당 target을 우선 사용합니다. extension point가 없는 template에서는 top-level component 구조를 검사하여 자식 layout을 안전하게 수용할 수 있는 structural host가 유일하게 확인되는 경우에만 layout contribution을 사용합니다.

Active User Template
        ↓
user_global_overlay 존재
    ├─ YES → 공식 overlay target 사용
    └─ NO  → structural host 판정
                 ├─ 유일하고 안전함 → layout contribution
                 └─ 없거나 모호함  → plugin-owned DOM fallback

따라서 특정 template, route 또는 root component 이름을 전제로 하지 않습니다. 안전한 layout host를 판단할 수 없는 경우에는 플러그인이 소유하는 DOM fallback이 동일한 canonical consent renderer를 사용하여 배너를 렌더링합니다.

SPA route transition에서는 layout이 일시적으로 사라지는 transient DOM 상태를 최종 부재로 오인하지 않도록 stable layout commit 이후 렌더링 경로를 reconcile합니다. layout banner가 존재하면 plugin fallback root를 제거하고, 기존 중복 상태가 발견되어도 하나의 rendering path만 남도록 self-heal합니다.

정상 layout 경로의 runtime invariant는 다음과 같습니다.

#gdpr_cookie_banner = 1
[data-glitter-gdpr-root] = 0

실제 fallback 경로에서는 다음 상태를 유지합니다.

#gdpr_cookie_banner = 0
[data-glitter-gdpr-root] = 1

두 경로가 동시에 존재하는 상태는 regression으로 간주합니다.

현재 public overlay는 사용자 template에서 다음 최소 component를 사용할 수 있으면 layout path로 렌더링할 수 있도록 구성되어 있습니다.

A
Div
P
Span

동의 action과 category 선택 control은 특정 template의 Button 또는 Checkbox 구현에 의존하지 않도록 portable A 기반 control 구조를 사용합니다.

또한 비필수 장식용 Icon 의존성을 제거하여 Icon component를 등록하지 않는 사용자 template에서도 public consent overlay가 렌더링될 수 있도록 했습니다.

Chrome E2E 검증

v0.5.2는 https://hub.glitter.kr/의 실제 Chrome 시크릿 환경에서 다음 흐름을 수동 E2E로 검증했습니다.

• fresh guest 최초 진입
• SPA 내부 navigation
• Browser Back / Forward
• layout / fallback 상호 배제
• 동의 없이 진행 후 배너 제거 및 새로고침 지속성
• 모두 동의 후 배너 제거 및 새로고침 지속성
• 사이트 데이터 삭제 후 fresh guest 상태와 배너 재등장

서버 환경의 headless Chromium은 시스템 라이브러리 제약으로 실행하지 못했지만, 실제 Chrome 브라우저 검증은 완료했습니다.

---

사이트별 쿠키 배너 문구

v0.3.0부터 사이트 운영자는 public consent banner의 제목과 안내 문구를 한국어와 영어별로 재정의할 수 있습니다.

구조는 다음과 같습니다.

Plugin Translation Default
          ↓
Host KO / EN Override
          ↓
Effective Banner Content

운영자가 custom 값을 입력하면 해당 문구를 사용합니다.

값이 없거나 빈 문자열 또는 공백만 입력되어 있으면 plugin 기본 translation으로 fallback합니다.

KO와 EN은 서로 독립적으로 동작합니다.

예를 들어:

KO custom 있음
EN custom 없음

이라면 한국어에서는 custom 문구를 사용하고 영어에서는 plugin 기본 영어 문구를 사용합니다.

Banner title/message override는 category availability 및 category description과 독립적으로 관리됩니다.

Admin Effective Preview

v0.5.0부터 관리자 설정 화면에서는 입력된 raw override와 실제 방문자에게 적용되는 effective 문구를 분리해서 확인할 수 있습니다.

각 banner title/message와 category description은 개념적으로 다음 상태를 가집니다.

{
  "raw": null,
  "effective": "쿠키 사용 안내",
  "source": "default"
}

raw가 비어 있거나 공백뿐이면 plugin 기본 translation을 사용하며, custom 값이 있으면 해당 값을 effective content로 사용합니다.

관리자 preview와 public UI는 동일한 effective content resolver를 사용합니다.

Raw Override
      ↓
Effective Content Resolver
      ├─ Admin Preview
      └─ Public Consent UI

따라서 관리자는 입력란에 기본 문구를 저장하지 않은 상태에서도 현재 방문자에게 실제 표시되는 문구와 default / override source를 확인할 수 있습니다.

---

Category별 사용자 안내 문구

v0.4.0부터 각 consent category의 사용자 안내 문구도 사이트별로 재정의할 수 있습니다.

대상은 다음 네 category입니다.

Necessary
Functional
Analytics
Marketing

각 category마다 한국어와 영어를 독립적으로 설정할 수 있으므로 총 8개의 optional description override를 제공합니다.

Necessary  : KO / EN
Functional : KO / EN
Analytics  : KO / EN
Marketing  : KO / EN

동작 원칙은 다음과 같습니다.

Custom Description 존재
        ↓
Custom 사용

Custom 없음 / empty / whitespace
        ↓
Plugin 기본 Translation 사용

기존 설치에서는 별도의 custom description을 입력하지 않아도 기존 plugin 기본 문구를 그대로 사용합니다.

Necessary

Necessary의 사용자 안내 문구는 사이트에서 실제 사용하는 필수 cookie와 기능의 목적에 맞게 재정의할 수 있습니다.

다만 description을 변경하더라도 Necessary category 자체는 항상 ON이며 비활성화할 수 없습니다.

Disabled Category

Analytics 또는 Marketing이 OFF라면 해당 category에 custom description이 저장되어 있더라도 방문자 consent 선택 UI에는 표시되지 않습니다.

즉,

Description Override
        ≠
Category Availability

입니다.

운영자가 문구를 작성했다는 사실만으로 해당 category가 활성화되지는 않습니다.

---

Policy Version과 재동의

glitter-gdpr는 단순히 저장된 consent 값만 확인하지 않고 현재 policy version과 consent 의미의 변화를 함께 관리합니다.

v0.4.0에서는 활성 category의 effective description도 consent 의미의 일부로 취급합니다.

활성 Category의 설명 변경

현재 활성화된 category의 effective description이 실질적으로 변경되면 material policy change로 처리합니다.

Active Category
      +
Effective Description 변경
      ↓
Material Policy Change
      ↓
새 Policy Version
      ↓
Returning Visitor Renewal

KO 또는 EN 중 하나의 실질적인 설명 변경도 material change가 될 수 있습니다.

불필요한 Policy Version 방지

다음처럼 effective 의미가 실제로 변하지 않는 경우에는 불필요한 새 version을 만들지 않습니다.

• whitespace-only equivalent 변경
• custom 문구가 기본 문구와 결과적으로 동일
• 빈 custom 값
• disabled category의 description만 변경

Disabled Category를 다시 ON으로 변경

OFF 상태의 category description을 수정하는 것만으로는 현재 방문자에게 보이는 consent surface가 변하지 않으므로 즉시 새 policy를 발행하지 않습니다.

이후 해당 category를 ON으로 변경하면 현재 effective description을 포함한 새 material policy가 발행됩니다.

과거에 해당 category에 true consent가 있었더라도 자동으로 복원하지 않습니다.

방문자는 현재 policy를 기준으로 다시 판단하게 됩니다.

---

운영자 문구의 보안 처리

Banner title/message와 category description override는 일반 text로만 취급합니다.

예를 들어 다음과 같은 문자열을 입력하더라도:

<script>alert(1)</script>
<img src=x onerror=alert(1)>
<b>hello</b>

HTML element나 실행 가능한 script로 해석하지 않고 일반 text로 렌더링합니다.

운영자가 수정할 수 있는 것은 사용자에게 보여줄 설명입니다.

다음과 같은 plugin contract 영역은 별도로 유지됩니다.

• category key
• category 기본 이름
• Necessary availability
• 자동 차단 대상 설명
• 대표 도구 예시
• blocker 동작 contract

---

사용자 템플릿 CSS와 분리

Public consent banner에 필요한 CSS는 glitter-gdpr 자체 public bundle에서 제공합니다.

따라서 활성 사용자 template의 Tailwind scan 대상에 GDPR layout class가 포함되어 있지 않아도 banner styling을 유지할 수 있습니다.

배포 asset은 다음과 같습니다.

dist/js/plugin.iife.js
dist/css/plugin.css

이를 통해 GDPR UI가 특정 host template의 frontend build 설정에 강하게 결합되는 문제를 줄였습니다.

---

정책 및 개인정보처리방침 연동

Consent banner는 개인정보처리방침과 같은 정책 페이지로 연결할 수 있습니다.

예를 들어 기본 privacy policy slug가 privacy인 경우 G7의 managed page 구조와 함께 다음 형태로 사용할 수 있습니다.

/page/privacy

실제 정책 콘텐츠는 사이트 운영자가 관리하며, glitter-gdpr는 consent 정책과 해당 정책 페이지로 연결되는 흐름을 제공합니다.

---

관리자 설정 사용법

플러그인을 설치하고 활성화한 뒤 관리자에서 Glitter GDPR 설정 화면으로 이동합니다.

1. Enforcement 설정

방문자에게 실제 consent banner와 blocking enforcement를 적용하려면 enforcement 설정을 확인합니다.

Enforcement를 비활성화하면 public consent provider/runtime은 유지하면서 visitor-facing banner와 blocker 계층을 분리해서 운영할 수 있습니다.

2. Category Availability 설정

사이트가 실제 사용하는 category만 활성화합니다.

예:

Necessary  : ON
Functional : ON
Analytics  : OFF
Marketing  : OFF

Necessary는 항상 ON입니다.

Google Analytics와 같은 분석 기능을 사용하지 않는 사이트라면 Analytics를 OFF로 둘 수 있습니다.

광고 pixel이나 marketing tracker를 사용하지 않는다면 Marketing을 OFF로 둘 수 있습니다.

사이트가 실제로 사용하는 기능을 기준으로 설정하는 것이 중요합니다.

3. 쿠키 배너 문구 설정

한국어와 영어별로 cookie banner 제목과 안내 문구를 설정할 수 있습니다.

별도의 문구가 필요하지 않다면 입력란을 비워 둡니다.

empty
→ plugin default translation

사이트별 표현이 필요한 경우에만 override를 사용하는 것을 권장합니다.

4. Category 사용자 안내 문구 설정

각 category 영역의 사용자 안내 문구에서 한국어와 영어 custom description을 입력할 수 있습니다.

예를 들어 Functional category가 실제로 어떤 사용자 설정을 저장하는지 사이트에 맞게 설명할 수 있습니다.

Custom 설명이 필요하지 않다면 비워 둡니다.

KO empty
→ KO plugin default

EN empty
→ EN plugin default

Necessary 역시 설명은 수정할 수 있지만 category 자체를 OFF로 변경할 수는 없습니다.

5. Analytics / Marketing을 사용하지 않는 경우

단순히 안내 문구를 지우는 것이 아니라 해당 category 자체를 OFF로 설정합니다.

Analytics : OFF
Marketing : OFF

그러면 해당 category는 visitor 선택 UI에서 숨겨지고 effective consent도 false가 됩니다.

6. Effective 문구 확인

v0.5.0부터 각 banner 및 category 문구에서 현재 적용되는 effective content와 source를 확인할 수 있습니다.

입력란이 비어 있어도 관리자 preview에는 plugin 기본 translation이 표시되며, 실제 public UI와 동일한 resolver 결과를 사용합니다.

기본 문구를 그대로 사용하는 경우에는 override 입력란을 채울 필요가 없습니다.

7. Policy Renewal 주의

현재 활성 category의 사용자 안내 문구를 실질적으로 변경하면 기존 방문자에게 재동의가 필요할 수 있습니다.

이는 문구가 단순 decoration이 아니라 사용자가 무엇에 동의하는지를 설명하는 consent 의미의 일부이기 때문입니다.

따라서 production에서는 category 설명을 실제 정책 변경과 같은 관점에서 관리하는 것을 권장합니다.

---

방문자 사용 흐름

신규 방문자는 현재 활성화된 category를 기준으로 consent UI를 보게 됩니다.

Public consent UI에서는 현재 정책에 따라 필요한 category 설명과 선택 항목을 확인하고, 전체 동의 또는 필수 항목만 허용하는 방식으로 선택할 수 있습니다.

정책 version이 변경되어 재동의가 필요한 기존 방문자도 현재 policy를 기준으로 consent UI를 다시 확인하게 됩니다.

예를 들어:

Necessary  : ON
Functional : ON
Analytics  : OFF
Marketing  : OFF

라면 선택 화면에는 Necessary와 Functional만 표시됩니다.

모두 동의

활성화된 선택 category에 대해서만 동의합니다.

{
  "necessary": true,
  "functional": true,
  "analytics": false,
  "marketing": false
}

동의 없이 진행

필수 category만 허용합니다.

{
  "necessary": true,
  "functional": false,
  "analytics": false,
  "marketing": false
}

Analytics와 Marketing이 OFF인 사이트에서는 과거 consent 여부와 관계없이 현재 effective consent가 false로 유지됩니다.

---

기존 sirsoft-gdpr와의 관계

glitter-gdpr는 공식 sirsoft-gdpr의 새로운 공식 버전이 아닙니다.

기존 프로젝트에서 커스텀하여 사용하던 sirsoft-gdpr 구현을 기반으로 필요한 기능을 검증한 뒤, 공식 확장과 사용자 커스텀 확장의 계보를 명확하게 분리하기 위해 독립 플러그인으로 전환했습니다.

현재 구조는 다음과 같습니다.

Official G7 / sirsoft-gdpr
        ↓
공식 계보 유지

glitter-gdpr
        ↓
Glitter.kr 독립 유지보수
        ↓
Glitter Template / Module / Plugin

G7 Core와 공식 sirsoft-gdpr를 직접 수정하지 않고 필요한 consent runtime 기능을 독립 확장에서 유지하는 것이 현재의 기본 방향입니다.

---

기존 데이터 전환

glitter-gdpr는 별도의 데이터 identity를 사용합니다.

주요 소유 영역은 다음과 같습니다.

glitter_gdpr_* tables
glitter_gdpr_session cookie
glitter-gdpr settings
glitter-gdpr permissions
glitter-gdpr routes
glitter-gdpr frontend runtime

최초 설치 시 기존 sirsoft-gdpr 계열에서 사용하던 gdpr_* 데이터가 존재하는 경우 기존 레코드를 삭제하거나 이동하지 않고 새 Glitter 저장소로 멱등 복제할 수 있도록 호환 경로를 제공합니다.

유효한 기존 gdpr_session cookie도 전환 과정에서 읽어 새 Glitter session cookie로 이어갈 수 있도록 구성되어 있습니다.

따라서 기존 consent 데이터를 제거하는 destructive migration을 전제로 하지 않습니다.

---

중복 Enforcement 주의

기존 sirsoft-gdpr와 glitter-gdpr는 서로 다른 identifier를 가진 독립 플러그인입니다.

두 플러그인을 동시에 visitor-facing enforcement 주체로 활성화하면

• consent banner 중복
• cookie/storage interceptor 중복
• tracking blocker 중복
• 정책 UI 중복

등이 발생할 수 있습니다.

따라서 glitter-gdpr로 전환한 환경에서는 기존 sirsoft-gdpr의 활성 상태를 확인하는 것을 권장합니다.

구조적으로는 다음과 같이 한 개의 consent enforcement provider를 사용하는 것이 적절합니다.

sirsoft-gdpr
      OR
glitter-gdpr

기존 플러그인의 데이터나 설치본을 즉시 삭제할 필요는 없으며, 정상적인 G7 plugin lifecycle을 통해 활성 상태를 관리하는 것을 권장합니다.

---

역할 분리

glitter-gdpr

• 사용자 consent 저장 및 조회
• category별 consent 관리
• category availability 관리
• 정책 버전 관리
• 재동의 여부 판단
• 회원 / guest consent 처리
• public consent snapshot
• refresh() / subscribe() / invalidate()
• AuthManager identity synchronization
• stale async response protection
• consent banner 및 public overlay
• 사이트별 banner content override
• category별 KO/EN description override
• consent enforcement
• 동의 전 tracking 차단

Template / Module / Plugin Consumer

• 필요한 consent category 확인
• 자신의 기능 활성화 여부 판단
• 외부 SDK 로딩 여부 판단
• analytics / marketing / advertising 기능 실행

G7 Core

• Authentication
• Auth state signal
• Extension lifecycle
• Host runtime

즉, glitter-gdpr는 다른 확장의 기능을 직접 실행하지 않고 현재 visitor의 consent 상태와 정책 enforcement를 담당합니다.

---

활용 사례

• 사이트별 실제 cookie category 선언
• 기능성 cookie에 대한 사용자 선택 제공
• 광고 SDK의 Marketing Consent 확인
• Analytics SDK 실행 조건 판단
• 외부 채팅 / 고객지원 SDK consent gate
• 개인화 기능 실행 조건 판단
• 외부 iframe / media embed 제어
• 선택적 storage 사용 제어
• SPA 환경에서 consent 상태 변경 반영
• 로그인 / 로그아웃 이후 consent snapshot 재평가
• 여러 G7 확장에서 동일 consent 상태 공유
• G7 template / module / plugin 간 consent provider 표준화
• 사이트별 consent 설명 및 정책 운영

---

기술 스택

• PHP 8.2+
• Laravel 12.x
• GnuBoard7 Plugin Architecture
• JSON Layout
• TypeScript
• Public Consent Runtime Contract
• G7 AuthManager Integration
• Static Frontend Bundle

---

요구 사항

• GnuBoard7 >=7.0.6
• PHP 8.2+

현재 plugin.json 기준:

Plugin ID : glitter-gdpr
Version   : 0.5.2
Vendor    : Glitter.kr
License   : MIT
G7        : >=7.0.6

---

관리자 페이지에서 설치

1. GitHub 저장소에서 설치 (권장)

관리자 → 플러그인 관리 → 수동 설치 → GitHub

아래 저장소 URL을 입력합니다.

https://github.com/glitter-node/glitter-gdpr

설치가 완료된 후 Glitter GDPR (일반 데이터 보호 규정) 플러그인을 활성화합니다.

2. ZIP 패키지 설치

GitHub Release에서 ZIP 패키지를 다운로드합니다.

https://github.com/glitter-node/glitter-gdpr/releases/tag/v0.5.2

Release package를 사용하는 경우 GitHub Releases에서 현재 공개된 버전을 확인한 뒤 ZIP 패키지를 다운로드합니다.

관리자 → 플러그인 관리 → 수동 설치 → 파일 업로드

방식으로 설치할 수 있습니다.

---

CLI 설치 및 활성화

필요한 경우 G7 plugin lifecycle을 통해 설치하고 활성화할 수 있습니다.

php artisan plugin:install glitter-gdpr
php artisan plugin:activate glitter-gdpr

기존 sirsoft-gdpr가 활성화되어 있다면 glitter-gdpr 설치 및 검증 후 중복 enforcement 방지를 위해 정상 lifecycle을 통해 비활성화합니다.

php artisan plugin:deactivate sirsoft-gdpr

실제 PHP CLI 경로는 설치 환경에 맞게 사용하면 됩니다.

---

설치 후 권장 설정

설치 직후 다음 순서로 설정하는 것을 권장합니다.

1. glitter-gdpr 활성화
        ↓
2. 기존 consent provider 중복 여부 확인
        ↓
3. Enforcement 설정 확인
        ↓
4. 사이트에서 실제 사용하는 Category 설정
        ↓
5. 개인정보처리방침 연결 확인
        ↓
6. Banner KO/EN 문구 확인
        ↓
7. Category별 KO/EN 사용자 설명 확인
        ↓
8. Fresh Guest에서 consent UI 확인
        ↓
9. Accept / Reject 결과 확인
        ↓
10. Analytics / Marketing 등 consumer 동작 확인

기본 translation이 사이트의 실제 운영 내용을 충분히 설명한다면 banner와 category description override는 비워 두어도 됩니다.

반대로 사이트에서 사용하는 cookie나 기능의 목적을 더 정확하게 설명해야 한다면 해당 문구만 override할 수 있습니다.

---

Public Runtime 사용 구조

Frontend extension에서는 개념적으로 다음 구조로 consent 상태를 사용할 수 있습니다.

glitter-gdpr
      ↓
Public Consent Runtime
      ↓
getSnapshot()
      ↓
Consent Category 확인
      ↓
Template / Module / Plugin
      ↓
각 확장의 기능 정책에 따라 실행

예를 들어 광고 기능에서는 다음과 같이 사용할 수 있습니다.

Advertising Configuration
        ↓
glitter-gdpr Consent Snapshot
        ↓
Marketing Consent
        ↓
Production Gate
        ↓
Advertising Loader
        ↓
Ad Slot

Marketing Consent가 허용되었다는 사실 자체가 외부 SDK의 자동 실행을 의미하지는 않습니다.

실제 기능 실행은 consumer의 별도 조건을 만족해야 합니다.

---

Public Runtime의 범위

Public contract에는 현재 visitor의 consent 판단에 필요한 최소 정보만 제공합니다.

다음과 같은 내부 정보는 extension consumer가 직접 알 필요가 없습니다.

• user ID
• guest UUID
• signed guest identifier
• consent database row ID
• 내부 cookie 이름
• storage path
• authentication token
• 내부 API 구현 세부사항

따라서 향후 glitter-gdpr의 내부 저장 구조가 변경되어도 public runtime contract를 기준으로 extension 간 결합도를 낮출 수 있습니다.

---

저장소

GitHub

https://github.com/glitter-node/glitter-gdpr

Release

GitHub 저장소의 Releases에서 현재 공개된 패키지를 확인할 수 있습니다.

---

버전별 주요 변경

v0.5.2

• SPA route transition 중 transient layout absence를 최종 부재로 오인해 fallback을 중복 mount하던 race condition 수정
• 실제 mutation 이후 stable layout commit을 확인한 뒤 fallback을 reconcile
• layout banner가 존재하면 plugin-owned fallback root를 자동 제거
• 반복 SPA navigation과 Back/Forward에서도 layout/fallback mutual exclusion 유지
• 실제 Chrome 시크릿 환경에서 initial, SPA, Back/Forward, consent persistence, site-data reset E2E 검증 완료

v0.5.1

• ID가 있는 첫 top-level component를 선택하던 unsafe root fallback 제거
• 유일한 structural children host만 안전한 layout target으로 사용
• 호환 가능한 host가 없거나 모호하면 plugin-owned DOM fallback 사용
• 특정 custom template/component identifier에 의존하지 않는 fallback 계층으로 개선

v0.5.0

• Admin에서 banner 및 category의 현재 effective content preview 제공
• raw override와 effective content를 분리하여 default / override source 표시
• Admin preview와 public UI가 동일한 effective content resolver를 사용하도록 SSoT 정리
• 빈 값 / 공백-only override는 DB에 기본 번역을 저장하지 않고 기존 fallback 유지
• banner KO/EN 및 category KO/EN locale isolation 유지
• 운영자 문구를 plain text로 렌더링하여 Admin/Public에서 HTML/script 실행 방지
• consent overlay target을 활성 사용자 template 구조에 맞게 resolve하도록 개선
• 공식 user_global_overlay가 있으면 우선 사용하고, 없으면 실제 _user_base root를 resolve
• 서로 다른 사용자 template에서도 consent 선택 UI와 action surface를 유지하도록 overlay 호환성 개선
• policy publication 및 renewal의 기존 material-change 규칙 유지

v0.4.0

• Necessary / Functional / Analytics / Marketing 사용자 안내 문구의 KO/EN별 optional override 추가
• 각 locale별 custom 값이 없으면 plugin 기본 translation으로 fallback
• 활성 category의 effective description 변경을 material policy change로 처리
• 비활성 category description 변경만으로는 불필요한 policy version을 발행하지 않음
• OFF→ON 시 현재 effective description을 포함한 새 policy 적용
• 과거 true consent의 자동 복원 방지
• 운영자 description을 plain text로 렌더링하여 HTML/script 실행 방지

v0.3.0

• 사이트별 cookie banner 제목과 안내 문구 KO/EN override 추가
• locale별 custom / default fallback 지원
• public settings에 현재 locale의 effective banner content 제공
• 운영자 banner content의 plain-text rendering 적용

v0.2.0

• Functional / Analytics / Marketing category availability 설정 추가
• Necessary 항상 활성
• 비활성 category를 visitor 선택 UI에서 제외
• 비활성 category effective consent를 false로 강제
• category availability 변경 시 material policy publication
• OFF→ON 과정에서 과거 consent 자동 복원 방지
• 선택 category가 없는 경우 불필요한 선택 UI 생략
• 4-key consent snapshot contract 유지
• 분석/마케팅 사용을 전제하지 않는 중립적인 기본 banner 문구 적용

v0.1.5

• 공통 _user_base의 user_layout_root에 consent banner를 주입하도록 변경
• 별도 user_global_overlay를 제공하지 않는 template에서도 신규 방문자 banner 표시

v0.1.4

• Icon을 등록하지 않는 사용자 template에서도 public consent overlay의 모든 노드가 렌더링되도록 비필수 장식 icon 의존 제거

v0.1.3

• Public consent banner의 cookie-bite Icon 의존을 작은 Span notice mark로 교체
• Icon 미등록 사용자 template과의 호환성 개선

v0.1.2

• Public consent banner 제목 영역의 시각적 accent 조정

v0.1.1

• Public consent banner 제목을 동의 설명 위로 복원
• 기존 consent banner의 정보 계층 유지

v0.1.0

• glitter-gdpr 독립 플러그인 계보 시작
• Public Consent Runtime 추가
  • getSnapshot()
  • refresh()
  • subscribe()
  • invalidate()
• G7 Core AuthManager authStateChange 연동
• visitor identity 변경 시 consent snapshot invalidate / refresh
• stale generation 보호
• 동일 identity의 in-flight refresh 공유
• enforcement_enabled 기반 provider / enforcement 분리
• 사용자 template Tailwind scan과 독립적인 public banner CSS
• 독립 namespace / route / permission / settings / frontend identity 적용
• 독립 cookie / database identity 적용
• 기존 sirsoft-gdpr 데이터와 guest session을 삭제하지 않는 전환 호환 경로 추가

---

개발 상태

v0.5.2 --- Custom Template / SPA 렌더링 안정화 및 Chrome E2E 검증 완료

glitter-gdpr는 기존 맞춤 sirsoft-gdpr 구현에서 검증한 consent runtime과 enforcement 구조를 독립적인 G7 Plugin으로 분리하고, 사이트별 category 운영과 consent 설명, Admin effective preview에 더해 custom template 및 SPA 환경의 독립적인 banner rendering fallback까지 확장했습니다.

초기 버전에서는 Public Consent Runtime과 enforcement 경계를 만드는 데 집중했다면, 이후 버전에서는 실제 사이트 운영자가

무엇을 사용하는가
        ↓
Category Availability

어떻게 전체 동의를 설명하는가
        ↓
Banner Content

각 동의 목적을 어떻게 설명하는가
        ↓
Category User Description

변경된 동의 의미를 어떻게 다시 확인받는가
        ↓
Policy Renewal

까지 관리할 수 있도록 범위를 확장했습니다.

현재 핵심 구조는 다음과 같습니다.

Host Configuration
├─ Category Availability
├─ Banner Content
└─ Category User Description
        ↓
Effective Content Resolver
├─ Admin Preview
└─ Public Consent UI
        ↓
Consent State
        ↓
Effective Consent
        ↓
Public Runtime
        ↓
Runtime / Auto Blocker

즉, 단순한 쿠키 배너에서 끝나는 것이 아니라 사이트가 실제 사용하는 consent category와 방문자의 선택, 정책 변경, runtime enforcement를 하나의 contract로 연결하는 것을 목표로 합니다.

v0.5.2에서는 공식 overlay extension point가 없는 custom template, 안전한 structural host가 없는 경우의 plugin-owned DOM fallback, SPA route transition의 중복 방지까지 회귀 테스트와 실제 Chrome E2E로 검증했습니다.

---

최적의 설치

이 버전은 ZIP 설치보다 GitHub 저장소 설치를 권장합니다.

G7 관리자에서 GitHub 저장소 URL을 이용하면 플러그인 설치와 이후 업데이트 흐름을 유지하기 쉽습니다.

https://github.com/glitter-node/glitter-gdpr

Release package를 이용해야 하는 경우에는 GitHub Releases에서 현재 공개된 패키지를 확인한 뒤 사용할 수 있습니다.

기존 sirsoft-gdpr를 사용하고 있는 환경에서는 먼저 glitter-gdpr를 설치하고 정상 동작을 검증한 뒤, 중복 enforcement가 발생하지 않도록 기존 플러그인의 활성 상태를 확인하는 것을 권장합니다.

---

핵심 구조

glitter-gdpr의 핵심은 단순히 쿠키 동의 배너를 출력하는 것이 아니라,

현재 사이트가 어떤 consent category를 사용하는지 선언하고, 현재 방문자가 무엇에 동의했는지를 독립된 provider가 판단하며, template / module / plugin이 그 결과를 public contract를 통해 재사용할 수 있도록 하는 것

입니다.

즉,

누가 현재 visitor인지, 사이트가 어떤 category를 사용하는지, 어떤 category에 동의했는지, 현재 정책에 재동의가 필요한지, 각 category를 사용자에게 어떻게 설명하는지, 로그인 또는 로그아웃으로 identity가 변경되었는지, 이미 실행 중인 frontend component가 consent 변경을 어떻게 반영할지

를 GDPR provider 계층에서 일관되게 관리합니다.

이를 통해 각 G7 확장이 GDPR plugin의 DB, cookie, session 또는 내부 API 구현을 직접 알지 않고도 현재 consent 상태를 사용할 수 있으며,

사이트의 consent 정책 설정 → 사용자 설명 → 동의 → effective consent → 실제 runtime enforcement

의 책임을 명확하게 연결할 수 있도록 구성했습니다.

---

라이선스

MIT License.

Copyright (c) 2026 Glitter.kr

---