# 구독 위젯
**구독 위젯**은 웹사이트 방문자에게 푸시 알림 구독을 권유하는 런처 벨과 프롬프트입니다. [푸시 구독 버튼](/ko/developer/pushwoosh-sdk/web-push-notifications/push-subscription-button/), [사용자 정의 구독 팝업](/ko/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/), [구독 프롬프트](/ko/developer/guides/messaging-channels/subscription-prompt/) 위젯을 하나의 컴포넌트로 대체합니다. 이 위젯이 활성화되어 있는 동안에는 이 세 가지 중 어느 것도 페이지에 로드되지 않으므로, 방문자는 서로 경쟁하는 두 개의 요청을 보는 일이 없습니다.
아직 결정하지 않은 방문자에게는 요청이 표시됩니다. 이미 알림을 차단한 방문자에게는 대신 차단을 해제하는 방법에 대한 설명이 표시됩니다.
## 사전 요구 사항
웹사이트에 Pushwoosh Web SDK 3.0을 구현했는지 확인하세요. 이를 위해 [통합 가이드](/ko/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration)를 따르세요.
## 1. 위젯 활성화
WebSDK 초기화에 `subscriptionWidget` 매개변수를 추가하고 `enable`을 `true`로 설정합니다:
```javascript
Pushwoosh.push(['init', {
//...
subscriptionWidget: {
enable: true,
}
}]);
```
아래의 각 필드는 선택 사항입니다. 생략된 필드는 기본값으로 대체됩니다. init 스니펫에서는 범위를 벗어난 숫자가 콘솔 경고 없이 가장 가까운 경계값으로 조용히 제한되며, 유효하지 않은 열거형 값도 콘솔 경고 없이 기본값으로 조용히 대체됩니다. 아래에 설명된 Control Panel 양식은 유효하지 않은 값을 즉시 거부하고 저장을 거부합니다.
## 2. 프롬프트 구성
```javascript
Pushwoosh.push(['init', {
//...
subscriptionWidget: {
enable: true,
prompt: {
layout: 'card', // 'card' | 'bar' | 'modal'
position: 'bottom-right',
iconUrl: 'https://url-image.png',
borderRadius: 12, // 0–32
overlay: false,
},
launcher: {
enabled: true,
position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
offset: 20, // 0–100
size: 48, // 32–80
},
display: {
trigger: 'auto', // 'auto' | 'launcher' | 'manual'
delay: 5, // seconds, 0–3600
cappingCount: 3, // auto-shows per visitor, 0–100, 0 = unlimited
cappingInterval: 24, // hours between auto-shows, 0–8760
},
texts: {
title: 'Stay in the loop',
message: 'Get notified about news and updates.',
acceptText: 'Allow',
declineText: 'Not now',
closeText: 'Close',
blockedTitle: 'Notifications are blocked',
blockedMessage: 'Enable notifications in your browser settings to stay updated.',
launcherLabel: 'Subscribe to notifications',
launcherBlockedLabel: 'Notifications are blocked',
},
colors: {
background: '#ffffff',
accent: '#4285f4',
text: '#000000',
textSecondary: '#666666',
},
}
}]);
```
### 레이아웃과 위치
`prompt.layout`은 프롬프트의 형태를 설정합니다:
- **`card`** — 가장자리나 모서리에 고정된 컴팩트한 카드입니다. `prompt.position`은 `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`를 허용합니다.
- **`bar`** — 페이지 전체 너비에 걸친 바입니다. `prompt.position`은 `top` 또는 `bottom`만 허용합니다.
- **`modal`** — 페이지 중앙에 위치한 창입니다. `prompt.position`은 항상 `center`입니다.
위치를 선택하기 전에 설정한 레이아웃에 대해 위 목록을 확인하세요. init 스니펫에서는 현재 레이아웃이 지원하지 않는 위치가 조용히 해당 레이아웃의 기본값으로 대체됩니다. Control Panel 양식은 대신 해당 조합을 거부합니다.
### 표시 시점
`display.trigger`는 무엇이 프롬프트를 여는지 제어합니다:
- **`auto`** — 페이지가 로드된 후 `display.delay`초 후에 자동으로 열리고, 방문자가 아직 결정하지 않았다면 `display.cappingInterval`시간마다 다시 열리며, 총 `display.cappingCount`회까지 열립니다(`0`은 제한 없음을 의미합니다).
- **`launcher`** — 방문자가 벨을 클릭할 때만 열립니다.
- **`manual`** — 아래에 설명된 `Pushwoosh.moduleRegistry.subscriptionWidget`을 통해서만 열립니다.
`display.delay`, `display.cappingCount`, `display.cappingInterval`은 `auto` 트리거에만 적용됩니다.
### 런처 벨
`launcher.enabled`는 `display.trigger`와 무관하게 방문자가 구독하지 않는 동안 떠 있는 벨을 표시합니다 — `trigger: 'auto'`인 경우에도 벨은 계속 표시되어, 방문자가 프롬프트를 닫은 후 다시 열 수 있습니다. `launcher.position`은 네 모서리 중 하나에 벨을 배치합니다. `launcher.offset`(가장자리로부터의 픽셀 오프셋)과 `launcher.size`(벨의 픽셀 단위 지름)는 위치를 세밀하게 조정합니다.
### 텍스트와 색상
브라우저가 방문자가 알림을 차단했다고 보고하면, 요청 대신 `texts.blockedTitle`, `texts.blockedMessage`, `texts.closeText`가 표시됩니다 — 이 상태에서는 `texts.acceptText`와 `texts.declineText`가 절대 나타나지 않습니다. `texts.launcherLabel`과 `texts.launcherBlockedLabel`은 각 상태에서 벨의 툴팁입니다. 모든 텍스트 필드는 최대 300자까지 허용됩니다.
`colors.accent`, `colors.background`, `colors.text`, `colors.textSecondary`는 16진수 값 또는 CSS 색상 이름을 받습니다. Control Panel 양식은 각 필드를 이런 방식으로 최대 64자까지 검증합니다. init 스니펫은 이 필드들에 대해 형식이나 길이를 확인하지 않고 비어 있지 않은 모든 문자열을 허용합니다.
## Control Panel에서 관리하기
패널 관리 애플리케이션에서 **Settings → Configure platforms → Web**으로 이동하여 **Subscription widget** 카드를 엽니다. 카드의 배지는 위젯이 **On**인지 **Off**인지를 보여줍니다.
**Configure**를 클릭하면 위에서 설명한 것과 동일한 필드를 **Prompt**, **When to show**, **Bell**, **Texts**, **Colors**로 그룹화하여 편집할 수 있으며, 미결정 방문자 상태와 차단된 방문자 상태를 모두 보여주는 실시간 미리보기도 함께 제공됩니다. 저장하면 패널의 위젯 구성 사본이 대체됩니다. 사이트의 WebSDK init 스니펫에는 영향을 주지 않습니다.
애플리케이션이 패널 관리 상태인 동안에는 이 카드에 저장된 값이 사이트 init 스니펫의 동일한 키를 재정의합니다. 사이트를 패널 구성으로 전환하는 것은 패널의 스위치 하나로 이루어지며, 사이트 코드 변경은 필요하지 않습니다.
## 3. 코드에서 위젯 제어하기
위젯 번들이 로드되면 `Pushwoosh.moduleRegistry.subscriptionWidget`에서 API를 게시합니다:
```javascript
Pushwoosh.moduleRegistry.subscriptionWidget.show(); // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.hide(); // Closes the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(); // Toggles the current state
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true); // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.isVisible(); // Returns whether the prompt is open
```
이미 구독한 방문자에게는 `show()`가 아무 효과가 없습니다. 프롬프트를 열면 `show-subscription-widget` 이벤트가 발생합니다. 닫으면 `hide-subscription-widget`이 발생합니다:
```javascript
Pushwoosh.addEventHandler('show-subscription-widget', function() {
console.log('Triggered event: show-subscription-widget');
});
Pushwoosh.addEventHandler('hide-subscription-widget', function() {
console.log('Triggered event: hide-subscription-widget');
});
```
## 이전 위젯에서 마이그레이션
`subscriptionWidget.enable`이 설정되지 않았거나 `false`로 유지되는 한, 푸시 구독 버튼, 사용자 정의 구독 팝업, 구독 프롬프트는 각자의 페이지에 문서화된 대로 계속 작동합니다. 이를 `true`로 설정하면 스니펫으로 구성된 애플리케이션과 패널 관리 애플리케이션 모두에서 세 가지 모두의 로드가 중지됩니다.