> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 웹 푸시 FAQ

> 개발자 및 웹사이트 소유자를 위한 OneSignal 웹 푸시 알림 설정, 요구 사항, 브라우저 호환성, 도메인 변경 및 일반적인 문제 해결에 대한 완벽한 가이드입니다.

## 웹 푸시 요구 사항

웹 푸시가 작동하려면 웹사이트가 다음을 모두 충족해야 합니다:

**필수 브라우저 API**

* [Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)
* [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
* [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)

**보안 및 연결**

* ✅ HTTPS만 가능(유효한 SSL 인증서 필요)
* ✅ OneSignal의 [Service Worker](./onesignal-service-worker) 설치됨
* ✅ 브라우저가 다음에 도달할 수 있어야 함:
  * 브라우저 푸시 서버(예: FCM, Mozilla)
  * `api.onesignal.com`

**사용자 상태**

* ✅ 사용자가 알림 권한 부여
* ❌ 시크릿/프라이빗/게스트 모드가 아님
* ❌ 사이트 데이터가 지워지지 않음(구독 삭제됨)

<Warning>브라우저 데이터(쿠키, 사이트 저장소)를 지우면 푸시 알림에서 사용자가 자동으로 구독 취소됩니다.</Warning>

### iOS/iPadOS 요구 사항

iOS 또는 iPadOS에서 푸시를 받으려면:

* iOS 16.4+ 또는 iPadOS 16.4+
* 사이트를 홈 화면에 추가하고 거기에서 열어야 함
* 필수 필드가 있는 유효한 `manifest.json` 파일
* 웹 앱으로 연 후 사용자가 알림 권한을 수락해야 함

<Card title="iOS 웹 푸시 설정" href="./web-push-for-ios" arrow={true}>
  iOS 16.4+를 실행하는 iPhone 및 iPad에서 웹 푸시를 활성화하려면 Apple 전용 단계를 따르세요.
</Card>

***

## 브라우저 및 플랫폼 지원

### 운영 체제별 브라우저 호환성

|                                      Browser                                     | Windows PC |  macOS  | Android | iOS (iPhone, iPad) |
| :------------------------------------------------------------------------------: | :--------: | :-----: | :-----: | :----------------: |
|             [Chrome 50+](https://en.wikipedia.org/wiki/Google_Chrome)            |   **Yes**  | **Yes** | **Yes** |      **Yes** ¹     |
|               [Firefox 47+](https://en.wikipedia.org/wiki/Firefox)               |   **Yes**  | **Yes** | **Yes** |      **Yes** ¹     |
|        [Safari 10+](https://en.wikipedia.org/wiki/Safari_\(web_browser\))        |     No     | **Yes** |    No   |      **Yes** ¹     |
|       [Microsoft Edge 18+](https://en.wikipedia.org/wiki/Microsoft_Edge) ²       |   **Yes**  | **Yes** | **Yes** |      **Yes** ¹     |
|          [Opera](https://en.wikipedia.org/wiki/Opera_\(web_browser\)) ²          |   **Yes**  | **Yes** | **Yes** |      **Yes** ¹     |
| [Samsung Internet](https://en.wikipedia.org/wiki/Samsung_Internet_for_Android) ² |     No     |    No   | **Yes** |      **Yes** ¹     |
|             [Yandex](https://en.wikipedia.org/wiki/Yandex_Browser) ²             |   **Yes**  | **Yes** | **Yes** |      **Yes** ¹     |
|             [UC Browser](https://en.wikipedia.org/wiki/UC_Browser) ²             |   **Yes**  |    No   | **Yes** |      **Yes** ¹     |
|      [Internet Explorer](https://en.wikipedia.org/wiki/Internet_Explorer) ³      |     No     |    No   |    No   |         No         |
|              [DuckDuckGo](https://en.wikipedia.org/wiki/DuckDuckGo)              |     No     |    No   |    No   |         No         |

* ¹ iOS는 웹 앱 설치 필요(위의 [iOS 웹 푸시 설정](./web-push-for-ios) 요구 사항 참조)
* ² Chromium 기반 브라우저는 OneSignal 분석에서 "Chrome"으로 표시됨
* ³ Internet Explorer는 더 이상 사용되지 않으며 업데이트를 받지 않음

<Warning> 시크릿 모드, 프라이빗 브라우징 모드 및 게스트 브라우저 모드는 모든 플랫폼에서 웹 푸시를 **지원하지 않습니다**.</Warning>

***

## 도메인 변경 및 마이그레이션

### 브라우저 원본 정책 이해

브라우저는 보안상의 이유로 웹 푸시 구독을 특정 [원본(도메인/사이트 URL)](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)에 연결합니다. **서로 다른 원본 간에 구독자를 전송할 수 없습니다** - 이것은 브라우저 제한이지 OneSignal 제한이 아닙니다.

**다른 원본에는 다음이 포함됩니다:**

* HTTP vs HTTPS (예: `http://mysite.com` → `https://mysite.com`)
* www vs non-www (예: `www.mysite.com` vs `mysite.com`)
* 다른 도메인/하위 도메인 (예: `domain1.com` vs `domain2.com` 또는 `sub1.domain.com` vs `sub2.domain.com`)

### 마이그레이션 옵션

사이트의 원본을 변경할 때 다음 접근 방식 중 하나를 선택하세요:

<Tabs>
  <Tab title="새 OneSignal 앱(권장)">
    **가장 적합한 경우**: 대부분의 도메인 변경, 특히 깔끔한 마이그레이션을 원하는 경우

    1. **새 OneSignal 앱 생성** - 새 도메인용
    2. **이중 전송 전략**: 이전 앱에서 계속 전송하되 "시작 URL"을 새 도메인으로 설정
    3. **점진적 전환**:
       * 높은 빈도 발신자(하루 1회 이상 알림): 2주 전환
       * 중간 빈도 발신자(주 2회 이상 알림): 2개월 전환
    4. **마이그레이션 알림**: 전환 시작 및 종료 시 "우리가 이사했습니다! 업데이트를 받으려면 새 사이트를 방문하세요"와 같은 메시지 1-2개 전송

    <Warning> 두 앱에서 동일한 메시지를 보내면 두 앱 모두에 구독한 사용자에게 중복 알림이 생성됩니다.</Warning>
  </Tab>

  <Tab title="앱 업데이트 및 이전 구독자 삭제">
    **가장 적합한 경우**: 동일한 OneSignal 앱 ID를 유지해야 하는 경우

    1. [앱 업데이트](/reference/update-an-app) API를 다음과 함께 사용:
       * `name`: 앱/사이트 이름
       * `chrome_web_origin`: 새 사이트 URL
       * `chrome_web_default_notification_icon`: 아이콘 이미지 URL

    2. **이전 구독자 삭제** - 중복 방지:
       * 세그먼트 생성: "Device Type is Web Push"
       * [세그먼트의 모든 사용자 삭제](./delete-users)
  </Tab>
</Tabs>

### HTTP에서 HTTPS로 업그레이드

HTTP에서 HTTPS로 업그레이드하면 새 원본이 생성됩니다. 브라우저가 HTTPS 사이트를 HTTP 버전과 완전히 별개로 취급하므로 위의 도메인 마이그레이션 단계를 따르세요.

***

## 여러 사이트 및 하위 도메인

### 단일 앱 제한

브라우저 동일 원본 정책으로 인해 다음과 같은 여러 원본에 하나의 OneSignal 앱을 사용할 수 **없습니다**:

* `https://mysite.com` 및 `https://www.mysite.com`
* `https://main.com` 및 `https://shop.main.com`

### 여러 원본을 위한 솔루션

<Tabs>
  <Tab title="단일 원본 전략">
    * 메인 도메인에서만 사용자 구독
    * 다른 원본에서 구독을 위해 메인 도메인으로 사용자 리디렉션
    * 구독 후 원래 페이지로 리디렉션
  </Tab>

  <Tab title="별도 앱">
    * 각 원본에 대해 개별 OneSignal 앱 생성
    * 여러 사이트에 구독한 경우 사용자가 중복 알림을 받을 수 있음을 수락
  </Tab>
</Tabs>

***

### 언어 지원 시나리오

<Tabs>
  <Tab title="동일 원본(권장)">
    * `https://mysite.com/en/` 또는 `https://mysite.com/es/`와 같은 URL
    * 단일 OneSignal 앱 사용
    * [다국어 프롬프트 가이드](./permission-requests#faq) 따르기
    * [언어 및 현지화](./multi-language-messaging) 구현
  </Tab>

  <Tab title="다른 원본">
    * `https://en.mysite.com` 또는 `https://es.mysite.com`과 같은 URL
    * 각 하위 도메인에 대해 별도의 OneSignal 앱 필요
  </Tab>
</Tabs>

***

## 고급 구성

### 동일한 사이트의 여러 OneSignal 앱

* **권장하지 않음** - 구독 충돌을 유발합니다.
* **발생하는 상황**: OneSignal은 가장 최근에 방문한 앱 ID로 사용자를 자동으로 재구독하여 구독자가 앱 간에 이동하고 많은 구독 취소된 기기를 생성합니다.
* **더 나은 접근 방식**: 단일 앱 내에서 사용자를 세분화하려면 [데이터 태그](./add-user-data-tags)를 사용하세요.

### 하위 폴더 사이트

웹 푸시는 원본 수준에서 작동합니다. 하위 폴더의 사이트(예: `https://example.com/blog`)의 경우 설정에 메인 원본(`https://example.com`)을 사용하세요.

### SDK 파일 자체 호스팅

**강력히 권장하지 않음**. 브라우저 푸시 사양이 자주 변경되며 OneSignal은 호환성을 유지하기 위해 파일을 즉시 업데이트합니다. 대신 웹 푸시 설정에서 OneSignal의 CDN URL을 사용하세요.

### 사용자 지정 init 코드

사용자 지정 `init` 코드는 [사용자 지정 코드 설정](./web-push-custom-code-setup)에서만 작동합니다.

**일반 설정 또는 웹사이트 빌더 사용자**: 사용자 지정 init 코드는 OneSignal SDK에서 무시됩니다. 초기화를 지연해야 하는 경우 [개인 정보 보호 메서드](./web-sdk-reference#privacy)를 사용하세요.

***

## 개발 및 테스트

### 로컬 환경 테스트

전체 로컬 테스트 설정은 [웹 SDK 설정 > 로컬 테스트](./web-sdk-setup#local-testing)를 참조하세요.

### Service Worker 통합

OneSignal은 기존 Service Worker 및 PWA와 함께 작동할 수 있습니다. 구현 세부 정보는 [여러 Service Worker 통합](./onesignal-service-worker)을 참조하세요.

***

## 푸시 스팸

푸시 알림은 광고, 사용자 스팸 또는 기만적인 캠페인에 사용되도록 설계되지 않았습니다.

앱이 스팸 알림을 보내는 것으로 감지되면 브라우저가 사용자에게 "스팸 경고" 알림을 보낼 수 있습니다.

다음과 같은 알림을 보내지 마세요:

* 사용자와 관련이 없는 알림
* "광고"와 같은 단어를 사용하거나 앱과 관련이 없는 페이지로 연결되는 알림
* 신뢰할 수 있는 출처가 아닌 알림(예: 연결되지 않은 브랜드)

<Warning>
  자세한 내용은 [Chrome에서 머신러닝으로 원치 않는 알림 차단](https://blog.chromium.org/2025/05/fighting-unwanted-notifications-with.html)을 참조하세요.
</Warning>

앱이 스팸으로 표시되는 경우 다음을 수행할 수 있습니다:

* 알림 콘텐츠를 검토하고 스팸으로 간주될 수 있는 항목을 제거합니다. 여기에는 다음이 포함됩니다:
  * 제목 또는 본문의 "광고" 또는 "Ad"라는 단어
  * 앱과 관련이 없는 페이지로의 링크
  * 신뢰할 수 있는 출처가 아닌 페이지로의 링크(예: 연결되지 않은 브랜드)
* 계속 전송하고 추가 보고를 모니터링합니다.

***

## 문제 해결

### 업데이트 배포 타이밍

* **Service Worker 파일**: 24시간 캐시
* **웹 SDK**: 3일 캐시

중요한 업데이트를 배포할 때 이에 따라 계획하세요.

### macOS Chrome 알림 문제

macOS Chrome 사용자의 경우 **둘 다**에 대해 알림이 활성화되어 있는지 확인하세요:

1. **Google Chrome** 앱(Apple 메뉴 > 설정 > 알림)
2. **Google Chrome Helper** 앱

둘 다 활성화되지 않으면 알림이 알림 센터에 표시되지 않습니다.

### 설정 후 다음 단계

1. **철저히 테스트** - 지원되는 브라우저 및 기기 전반에 걸쳐
2. **적절한 오류 처리 구현** - 권한 요청에 대해
3. **분석 설정** - 구독률 모니터링
4. **알림 전략 계획** - 사용자 피로 방지
5. **A/B 테스트 고려** - 권한 요청 타이밍 및 메시징

### 일반적인 마이그레이션 함정

* **브라우저 데이터 지우기** - 사용자를 자동으로 구독 취소함
* **중복 알림** - 이중 앱 전환 중
* **iOS는 웹 앱 설치 필요** - 푸시가 작동하기 전에
* **프라이빗/시크릿 모드** - 푸시 알림을 지원하지 않음
* **Service Worker는 액세스 가능해야 함** - 사이트의 루트 또는 구성된 하위 디렉토리에서

***

## 다음 단계

* [웹 SDK 설정](./web-sdk-setup)
* [웹 SDK 참조](./web-sdk-reference)

***