# 구독 위젯

**구독 위젯**은 웹사이트 방문자에게 푸시 알림 구독을 권유하는 프롬프트와 런처 벨이며, `subscriptionWidget`으로 함께 구성하지만 독립적으로 켤 수 있습니다. 프롬프트만, 벨만, 또는 둘 다 켤 수 있습니다. 둘 중 하나를 켜면 [푸시 구독 버튼](/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` 매개변수를 추가하고 `prompt.enabled` 및/또는 `launcher.enabled`를 `true`로 설정합니다:

```javascript
Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);
```

<Aside type="caution" title="단일 최상위 스위치 없음">
최상위 `subscriptionWidget.enable`은 읽지 않습니다. 이 필드만 설정하면 아무것도 켜지지 않습니다. 아래의 [이전 위젯에서 마이그레이션](#migrating-from-the-older-widgets)을 참조하세요.
</Aside>

아래의 각 필드는 선택 사항입니다. 생략된 필드는 기본값으로 대체됩니다. init 스니펫에서는 범위를 벗어난 숫자가 콘솔 경고 없이 가장 가까운 경계값으로 조용히 제한되며, 유효하지 않은 열거형 값도 콘솔 경고 없이 기본값으로 조용히 대체됩니다. 아래에 설명된 Control Panel 양식은 각 필드를 검증하며 유효하지 않은 값의 저장을 거부합니다.

## 2. 프롬프트와 벨 구성

```javascript
Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      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
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    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`** — 타이머로는 절대 열리지 않습니다. 벨 클릭으로 열 수 있도록 `launcher.enabled: true`와 함께 설정하세요. 수동 API는 이 설정이나 벨의 켜짐 여부와 관계없이 항상 프롬프트를 열 수 있습니다.
- **`manual`** — 아래에 설명된 `Pushwoosh.moduleRegistry.subscriptionWidget`을 통해서만 열립니다.

`display.delay`, `display.cappingCount`, `display.cappingInterval`은 `auto` 트리거에만 적용됩니다.

### 런처 벨

`launcher.enabled`는 아직 요청에 응답할 수 있는 방문자(아직 구독하지 않았거나 차단한 방문자)에게 떠 있는 벨을 표시하며, 프롬프트 및 `display.trigger`와 무관합니다. 프롬프트가 열려 있는 동안에도 벨은 화면에 남아 있습니다. `launcher.position`은 네 모서리 중 하나에 벨을 배치합니다. `launcher.offset`은 가장자리로부터의 거리를 픽셀 단위로 설정합니다.

벨 클릭의 효과는 프롬프트에 따라 달라집니다. `prompt.enabled`가 `true`이면 클릭으로 프롬프트를 토글합니다. 닫혀 있으면 열고, 열려 있으면 닫습니다. 프롬프트가 꺼져 있으면 클릭 시 `Pushwoosh.subscribe()`와 동일하게 브라우저에 권한을 직접 요청합니다. 단, 방문자가 이미 알림을 차단한 경우에는 클릭해도 아무 일도 일어나지 않습니다.

`launcher.width`와 `launcher.height`는 벨의 크기를 픽셀 단위로 설정합니다(16–200, 기본값 각각 48). `launcher.imageUrl`은 둥근 벨 버튼 대신 이미지를 그립니다. `launcher.background`와 `launcher.iconColor`는 둥근 버튼의 채우기 색상과 글리프 색상을 설정합니다. 설정하지 않으면 `launcher.background`는 팔레트의 강조 색상이 기본값이고, `launcher.iconColor`는 이에 대한 대비를 위해 계산된 글리프 색상이 기본값입니다.

### 텍스트와 색상

브라우저가 방문자가 알림을 차단했다고 보고하면, 요청 대신 `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 양식은 이 필드들과 `launcher.background`/`launcher.iconColor`를 이런 방식으로 최대 64자까지 검증합니다. init 스니펫은 `colors.*`에 대해 형식이나 길이를 확인하지 않고 비어 있지 않은 모든 문자열을 허용합니다. `launcher.background`/`launcher.iconColor`는 형식을 확인하지 않지만 값을 64자로 조용히 잘라냅니다.

<Aside type="note">
다크 모드 색상 팔레트, `launcher.zIndex`, 사용자 지정 `fontFamily`는 init 매개변수로만 사용할 수 있는 추가 필드로 제공됩니다. 아래에 설명된 Control Panel 양식에는 노출되지 않습니다.
</Aside>

<span id="managing-it-in-the-control-panel" />

## Control Panel에서 관리하기

<Aside type="caution" title="패널 관리 애플리케이션 전용">
Control Panel 카드들은 Web 플랫폼이 **패널 관리** 모드인 애플리케이션에서만 사용할 수 있습니다([Web Push SDK 3.0](/ko/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/) 참조). 스니펫으로 구성된 애플리케이션의 경우 위에 표시된 대로 init 스니펫에서 `subscriptionWidget`을 설정하세요.
</Aside>

패널 관리 애플리케이션에서 **Settings → Configure platforms → Web**으로 이동합니다. 프롬프트와 벨은 두 개의 별도 카드이며, 각각 자체 **On**/**Off** 배지와 **Configure** 버튼이 있습니다:

- **Subscription invitation**은 프롬프트를 편집합니다: **Invitation**(레이아웃, 위치, 아이콘), **When to show**(트리거, 지연, 제한), **Texts**, **Colors**.
- **Subscription bell**은 런처를 편집합니다: 위치, 이미지 URL, 너비/높이, 배경 및 아이콘 색상, 그리고 자체 툴팁 텍스트.

각 카드의 **Configure** 버튼은 양식 옆에 실시간 미리보기를 엽니다. 해당 카드 자체의 스위치가 꺼져 있으면 미리보기에는 아무것도 그려지지 않습니다. 켜져 있으면 미리보기 위의 드롭다운으로 미결정 방문자의 요청과 차단된 방문자의 설명을 전환할 수 있습니다. 카드를 저장하면 패널의 위젯 구성 사본 중 해당 카드의 절반만 대체되며, 다른 카드의 설정과 사이트의 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()`와 `toggle()`은 `prompt.enabled`가 `false`인 동안에는 효과가 없으며, 이미 구독한 방문자에게도 효과가 없습니다. 프롬프트를 열면 `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');
});
```

<span id="migrating-from-the-older-widgets" />

## 이전 위젯에서 마이그레이션

사이트의 `subscriptionWidget.prompt.enabled`와 `subscriptionWidget.launcher.enabled`가 모두 설정되지 않았거나 `false`로 유지되는 한, 푸시 구독 버튼, 사용자 정의 구독 팝업, 구독 프롬프트는 각자의 페이지에 문서화된 대로 계속 작동합니다. 둘 중 하나라도 켜면 스니펫으로 구성된 애플리케이션과 패널 관리 애플리케이션 모두에서 세 가지 모두의 로드가 중지됩니다.

<Aside type="caution">
이전 버전의 위젯은 별도의 `prompt.enabled`/`launcher.enabled` 대신 단일 최상위 `subscriptionWidget.enable` 스위치를 사용했습니다. 이 형태는 더 이상 읽지 않습니다. `enable: true`만 설정한 스니펫은 이제 위젯을 완전히 끈 상태가 됩니다. 프롬프트도 벨도 아무것도 그리지 않고, WebSDK는 대신 설정해야 할 두 필드를 알려 주는 콘솔 힌트를 기록하며, 세 가지 이전 위젯은 `subscriptionWidget`이 설정되지 않은 것처럼 로드됩니다. 패널 관리 애플리케이션을 새 위젯으로 전환해도 대체되는 이전 위젯의 설정은 이어지지 않습니다. 각 카드는 자체 기본값으로 시작합니다.
</Aside>