> ## 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.

# WordPress 문제 해결

> 브라우저 호환성(Chrome, Firefox, Safari), 플러그인 통합 및 CDN 또는 캐싱 충돌 해결을 포함하여 WordPress의 OneSignal 웹 푸시 알림과 관련된 일반적인 설정 문제 해결을 위한 포괄적인 가이드입니다.

## 일반적인 설정 문제

### OneSignal 대시보드 설정 확인

[WordPress 설정 가이드](./wordpress)의 각 단계를 완료했는지 확인하세요:

* OneSignal 앱을 만들 때 **WordPress 플러그인** 옵션을 선택합니다
* 사이트 URL은 브라우저 URL과 정확히 일치해야 합니다
  * 예를 들어 `https://example.com`은 `https://www.example.com`과 **동일하지 않습니다**. 하나의 버전을 일관되게 사용하세요.
  * 푸시에는 하나의 사이트 원본만 지원됩니다. [동일 출처 정책](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)을 참조하세요.
* 최소한 하나의 권한 프롬프트를 추가했는지 확인하세요.

### OneSignal 코드를 수동으로 추가하지 마세요

OneSignal WordPress 플러그인은 초기화 스크립트 및 서비스 워커를 **자동으로** 포함합니다.

* 사이트에 OneSignal JavaScript `init` 코드를 추가하지 **마세요**.
* WordPress 플러그인과 함께 [사용자 지정 코드 설정](./web-push-custom-code-setup)을 사용하지 **마세요**. `init` 메서드를 사용자 지정해야 하는 경우 **플러그인을 제거**하고 코드와 서비스 워커를 수동으로 추가하세요.

### 게시물 게시 시 알림 보내기

게시물, 페이지 또는 사용자 지정 게시물 유형을 게시하면 OneSignal이 구독자에게 자동으로 알림을 보낼 수 있습니다.

<Frame caption="OneSignal Push Notifications 메타박스——필요한 경우 드래그하여 위치를 변경할 수 있습니다">
  <img src="https://mintcdn.com/onesignal/kAXbp86YqdTAbPtE/images/web-push/onesignal-push-notifications-metabox-wordpress.png?fit=max&auto=format&n=kAXbp86YqdTAbPtE&q=85&s=428a477e16f85fa50f9ff69678304340" alt="OneSignal Push Notifications 메타박스——필요한 경우 드래그하여 위치를 변경할 수 있습니다" width="3252" height="1674" data-path="images/web-push/onesignal-push-notifications-metabox-wordpress.png" />
</Frame>

**게시물이 게시되거나 업데이트될 때 알림 보내기** 체크박스가 보이지 않으면 다음 항목을 확인하세요:

1. 편집기 오른쪽과 아래쪽의 메타박스를 확인하세요. 필요에 따라 드래그 앤 드롭할 수 있습니다.
2. 편집기 상단의 **화면 옵션**을 확인하여 **OneSignal Push Notifications** 메타박스가 체크되어 있는지 확인하세요.

<Frame caption="OneSignal Push Notifications 메타박스가 체크된 화면 옵션">
  <img src="https://mintcdn.com/onesignal/kAXbp86YqdTAbPtE/images/web-push/wordpress-screen-options-onesignal-push-notifications-metabox-checked.png?fit=max&auto=format&n=kAXbp86YqdTAbPtE&q=85&s=fd11371fd17a5d66fec241bcc2ff5084" alt="OneSignal Push Notifications 메타박스가 체크된 화면 옵션" width="1896" height="330" data-path="images/web-push/wordpress-screen-options-onesignal-push-notifications-metabox-checked.png" />
</Frame>

3. 사용자 지정 게시물 유형을 사용하고 있는지 확인하세요. 일반적으로 URL에서 `post_type=your_custom_type` 형태로 확인할 수 있습니다. 그렇다면 [OneSignal WordPress 플러그인 설정](./wordpress#add-a-custom-post-type-to-onesignal-wordpress-plugin)의 **사용자 지정 게시물 유형** 필드에 해당 유형을 추가하세요.

<Frame caption="사용자 지정 게시물 유형 이름을 찾는 위치 예시">
  <img src="https://mintcdn.com/onesignal/kAXbp86YqdTAbPtE/images/web-push/wordpress-find-custom-post-types-field.png?fit=max&auto=format&n=kAXbp86YqdTAbPtE&q=85&s=3239d37ca790551c1fd3685f8424f319" alt="사용자 지정 게시물 유형 필드를 보여주는 OneSignal WordPress 플러그인 설정" width="1154" height="894" data-path="images/web-push/wordpress-find-custom-post-types-field.png" />
</Frame>

***

## 사이트 문제를 해결하는 방법

<Steps>
  <Step title="플러그인이 활성화되어 있는지 확인하고 개발자 도구 열기">
    플러그인이 활성화된 상태로 일반(비시크릿) 브라우저 창에서 사이트를 로드합니다.

    <Frame caption="사이트를 마우스 오른쪽 버튼으로 클릭하고 검사를 클릭한 다음 Console 탭을 엽니다.">
      <img src="https://mintcdn.com/onesignal/3zq1PvSaqvUE2bIx/images/docs/28c27ab14a40621fbcc2c4168d49a2bf72088536a669be59c160b7a30a7fcd95-Screenshot_2025-02-27_at_10.39.27_AM.png?fit=max&auto=format&n=3zq1PvSaqvUE2bIx&q=85&s=38d793be0784bcfd8acee745e3757dcf" alt="WordPress 사이트에서 Console 탭이 선택된 브라우저 개발자 도구" width="1814" height="1024" data-path="images/docs/28c27ab14a40621fbcc2c4168d49a2bf72088536a669be59c160b7a30a7fcd95-Screenshot_2025-02-27_at_10.39.27_AM.png" />
    </Frame>
  </Step>

  <Step title="콘솔에서 OneSignal 오류 확인">
    **Console** 탭을 열고 페이지를 새로 고치고 빨간색 또는 노란색 OneSignal 관련 오류를 찾습니다.
    도움이 필요하면 [일반적인 OneSignal 콘솔 오류](#common-onesignal-console-errors)를 참조하세요.
  </Step>

  <Step title="브라우저에서 구독 상태 확인">
    페이지 로딩이 완료되고 콘솔에 OneSignal 오류가 없는 것을 확인한 후 다음을 붙여넣습니다:

    ```javascript JavaScript theme={null}
    OneSignal.User.PushSubscription.id
    ```

    방문자가 구독한 경우 문자열(구독 ID)을 반환합니다. 구독하지 않았거나 구독이 아직 준비되지 않은 경우 **`null`** 또는 빈 값이 표시될 수 있습니다. \*\*`OneSignal is not defined`\*\*가 표시되면 몇 초 기다린 후 다시 시도하거나, 먼저 [일반적인 OneSignal 콘솔 오류](#common-onesignal-console-errors)의 콘솔 오류를 수정하세요——SDK가 지연 로더를 통해 아직 로드 중일 수 있습니다.

    <Frame caption="콘솔에서 OneSignal 구독 ID를 찾습니다.">
      <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/96cdeebdc8888b5c49b6466bf6975a75fb9497f7e54d34f7da3d6c25b35250ae-Screenshot_2025-02-27_at_11.15.16_AM.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=f396b737c9cd56257c59d6515086aec6" alt="브라우저 콘솔에 OneSignal 사용자 PushSubscription id 문자열 결과가 표시됨" width="1258" height="448" data-path="images/docs/96cdeebdc8888b5c49b6466bf6975a75fb9497f7e54d34f7da3d6c25b35250ae-Screenshot_2025-02-27_at_11.15.16_AM.png" />
    </Frame>
  </Step>

  <Step title="OneSignal 대시보드에서 구독 ID 확인">
    **OneSignal 대시보드**에서 **Audience > Subscriptions**으로 이동하여 위에서 반환된 ID를 검색합니다.

    <Frame caption="구독 ID에 대해 OneSignal 대시보드를 검색합니다.">
      <img src="https://mintcdn.com/onesignal/Z6xkXGfmy814If53/images/docs/e3907be9912e3ed3a934c6968f2e6f9354af519b8c670d1f7de07f32e71a8a80-Screenshot_2025-02-27_at_11.18.06_AM.png?fit=max&auto=format&n=Z6xkXGfmy814If53&q=85&s=76657b84cf0f8f29fa03a776f26cf66c" alt="구독 ID 조회가 있는 OneSignal 대시보드 구독 검색 필드" width="2726" height="780" data-path="images/docs/e3907be9912e3ed3a934c6968f2e6f9354af519b8c670d1f7de07f32e71a8a80-Screenshot_2025-02-27_at_11.18.06_AM.png" />
    </Frame>
  </Step>

  <Step title="테스트 푸시 알림 보내기">
    구독이 존재하고 상태가 **구독됨**인 경우 [푸시 가이드](./push)를 따라 알림을 보냅니다.
    아무것도 나타나지 않으면 브라우저별 수정 사항에 대해 [표시되지 않는 알림](./notifications-not-shown-web-push)을 참조하세요.
  </Step>
</Steps>

***

## 일반적인 OneSignal 콘솔 오류

### <Danger>SdkInitError: OneSignal: This web push config can only be used on ... Your current origin is ...</Danger>

<Frame caption="사이트 URL 불일치 오류.">
  <img src="https://mintcdn.com/onesignal/_KaXe4GQkxsEfa17/images/docs/334686c64af6155f95d674d0cfd28a5b92739f3cae57382073365ec9206b7e7c-Screenshot_2025-02-27_at_11.35.59_AM.png?fit=max&auto=format&n=_KaXe4GQkxsEfa17&q=85&s=2d8d0656875180f0b77dd88795a4bced" alt="웹 푸시 구성 출처 불일치를 보여주는 콘솔 SdkInitError" width="2090" height="192" data-path="images/docs/334686c64af6155f95d674d0cfd28a5b92739f3cae57382073365ec9206b7e7c-Screenshot_2025-02-27_at_11.35.59_AM.png" />
</Frame>

OneSignal 대시보드의 사이트 URL이 실제 도메인과 일치하지 않습니다.
브라우저에서 보는 도메인과 정확히 일치하는지 확인하세요.

### <Danger>PushPermissionNotGrantedError: The user dismissed the permission prompt.</Danger>

방문자가 브라우저 프롬프트를 거부했습니다. 대기 기간이 만료될 때까지 다시 나타나지 않습니다.
브라우저 규칙에 대해서는 [웹 권한 프롬프트](./permission-requests)를 참조하거나 사이트 데이터를 지워 즉시 다시 시도하세요.

### <Danger>The OneSignal web SDK can only be initialized once.</Danger>

<Frame caption="중복 OneSignal 초기화 오류.">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/e88d53c6c92a546f188c06e14e1776da8ad63c658c64044b6a674802ce2a2277-Screenshot_2025-02-27_at_2.40.32_PM.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=cc2d3a0773b894f423f0d6db598a37a1" alt="콘솔 오류: OneSignal 웹 SDK는 한 번만 초기화할 수 있음" width="2164" height="182" data-path="images/docs/e88d53c6c92a546f188c06e14e1776da8ad63c658c64044b6a674802ce2a2277-Screenshot_2025-02-27_at_2.40.32_PM.png" />
</Frame>

OneSignal을 두 번 로드하고 있습니다. 플러그인을 사용하는 경우 수동으로 추가된 OneSignal 코드를 제거하세요.

### <Danger>Installing service worker failed.. 403 or 404 error</Danger>

<Frame caption="서비스 워커 파일 누락(403/404).">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/990e505-Screen_Shot_2020-02-01_at_9.31.44_PM.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=0d719e6b826477612901d07e1d505f15" alt="콘솔 오류: 서비스 워커 설치가 403 또는 404 오류로 실패함" width="3364" height="200" data-path="images/docs/990e505-Screen_Shot_2020-02-01_at_9.31.44_PM.png" />
</Frame>

이 파일에 액세스할 수 있는지 확인하세요(`your-site.com`을 교체하고 기본값과 다른 경우 **실제 플러그인 폴더 이름**과 일치시키세요):
`https://your-site.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js`

그렇지 않은 경우 CDN 또는 캐싱 문제를 해결하려면 [일반적인 플러그인 지원](#common-plugin-support)을 참조하세요.

***

## 일반적인 플러그인 지원

CDN 및 캐싱 플러그인은 OneSignal의 필수 파일을 차단할 수 있습니다. 아래 경로는 플러그인 디렉터리가 \*\*`onesignal-free-web-push-notifications`\*\*라고 가정합니다. 설치에서 다른 폴더 이름을 사용하는 경우 조정하세요.

### Autoptimize

**Excluded scripts**에 다음을 추가합니다:

```
wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/(.*)
```

### WP Rocket

**CDN > Exclude Files From CDN** 아래에 다음을 추가합니다:

```
(.*)/onesignal-free-web-push-notifications/sdk_files/(.*)
```

### LiteSpeed Cache

**CDN > Exclude Path** 아래에 다음을 추가합니다:

```
(.*)/onesignal-free-web-push-notifications/sdk_files/(.*)
```

그런 다음 저장을 누릅니다.

### WP Super Cache

1. **Settings > WP Super Cache > CDN**으로 이동합니다
2. **Exclude if substring**에 `onesignal-free-web-push-notifications`를 포함합니다
3. **Contents** > **Delete Cache**를 클릭합니다

### WP Engine

WP Engine은 CDN을 통해 플러그인 URL을 재작성할 수 있습니다. **HTML 후처리** 규칙은 환경마다 다릅니다. 아래 스니펫은 **예시일 뿐**입니다——적용 전에 [WP Engine 지원](https://wpengine.com/support/) 또는 사용자 포털에서 경로를 확인하세요.

WP Engine **plugin > General Settings > HTML Post-Processing**에서 다음과 유사한 규칙이 필요할 수 있습니다. 각 자리 표시자를 **귀하의** 사이트와 WP Engine CDN 호스트명의 실제 값으로 교체하세요:

| 자리 표시자                 | 교체할 값                                            |
| ---------------------- | ------------------------------------------------ |
| `YOURSITEHERE`         | 베어 도메인(정규식 세그먼트), 예: `example.com`의 경우 `example` |
| `mywpenginehandleHere` | WP Engine 설치 이름(`.wpengine.com` 앞의 서브도메인)        |
| `wpengineCDNpathHere`  | WP Engine의 NetDNA / CDN 경로 세그먼트(CDN URL에 자주 표시됨) |
| `mywebsiteHere`        | 경로 없는 라이브 사이트 오리진, 예: `https://example.com`      |

```text text theme={null}
#https?://(www\.)?(YOURSITEHERE\.com|mywpenginehandleHere.wpengine.com|wpengineCDNpathHere.wpengine.netdna-(ssl|cdn).com)/wp-(content|includes)#
=> https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-$4
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
#https://wpengineCDNpathHere-wpengine.netdna-ssl.com/wp-content/plugins/onesignal-free-web-push-notifications/#
=> https://mywebsiteHere.com/wp-content/plugins/onesignal-free-web-push-notifications/
```

### W3 Total Cache

1. **Performance > CDN**으로 이동합니다
2. **Rejected files** 아래에 다음을 추가합니다:

```
{plugins_dir}/onesignal-free-web-push-notifications/sdk_files/*
```

<Frame caption="W3 Total Cache 제외 설정.">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/64ad121-Screen_Shot_2020-03-02_at_7.36.18_PM.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=1b7d1eb06d32c8beef4026a70111dcdb" alt="OneSignal sdk_files 경로를 포함하는 W3 Total Cache CDN 거부된 파일 목록" width="1071" height="494" data-path="images/docs/64ad121-Screen_Shot_2020-03-02_at_7.36.18_PM.png" />
</Frame>

### BunnyCDN

플러그인의 CDN Excluded Paths에서 *onesignal*을 제외합니다.

<Frame caption="BunnyCDN 제외 예시.">
  <img src="https://mintcdn.com/onesignal/ciRrThfP6xMpI7GY/images/docs/025f46c1159398106997c97a61ad26ffe4ecd6f7a068dcd6e3f743762e6e697b-Screenshot_2024-11-19_at_9.34.35_AM.png?fit=max&auto=format&n=ciRrThfP6xMpI7GY&q=85&s=d893359f9da931a9db313391a58cf1ca" alt="onesignal을 포함하는 BunnyCDN WordPress 플러그인 제외 경로" width="1830" height="518" data-path="images/docs/025f46c1159398106997c97a61ad26ffe4ecd6f7a068dcd6e3f743762e6e697b-Screenshot_2024-11-19_at_9.34.35_AM.png" />
</Frame>

### CDN Enabler

Settings > CDN Enabler에서 "Exclusions"에 다음을 추가합니다:

```
onesignal-free-web-push-notifications
```

### PressCDN

Exclude Directories에 다음을 추가합니다:

```
/wp-content/plugins/onesignal-free-web-push-notifications/
```

### Breeze

**Settings > CDN > Exclude Content**에 다음을 추가합니다:

```
/onesignal-free-web-push-notifications/sdk_files/
```

<Frame caption="Breeze 제외 예시.">
  <img src="https://mintcdn.com/onesignal/Z6xkXGfmy814If53/images/docs/e0ea4ad-Screen_Shot_2020-06-30_at_7.59.26_PM.png?fit=max&auto=format&n=Z6xkXGfmy814If53&q=85&s=c12fed5c62e460beec878171e940928d" alt="OneSignal sdk_files 경로가 있는 Breeze CDN 제외 콘텐츠 필드" width="1219" height="552" data-path="images/docs/e0ea4ad-Screen_Shot_2020-06-30_at_7.59.26_PM.png" />
</Frame>

### Hummingbird Pro

**Hummingbird > Asset Optimization**으로 이동합니다. **JavaScript**(OneSignal 자산이 있는 경우 **CSS**도) 아래에서 URL에 **`onesignal-free-web-push-notifications`** 또는 \*\*`OneSignalSDK`\*\*가 포함된 파일을 찾습니다. 축소/결합/지연에서 **제외**하거나 해당 자산을 **로드하지 않음** 최적화로 전환하여 플러그인이 이를 재작성하거나 지연시키지 않도록 하세요.

<Frame caption="Hummingbird Pro 자산 최적화.">
  <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/a888a91-PastedGraphic-4_3.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=e376446d64ec7fa8a8067ac7e8e551ba" alt="스크립트 제외를 보여주는 Hummingbird Pro 자산 최적화 목록" width="476" height="90" data-path="images/docs/a888a91-PastedGraphic-4_3.png" />
</Frame>

### Sucuri

OneSignal 파일을 허용하려면 [Sucuri의 화이트리스트 가이드](https://kb.sucuri.net/firewall/Whitelist+and+Blacklist/whitelist-file-folder)를 따르세요.

### Solid Security (구 iThemes Security)

`OneSignalSDKWorker.js.php`가 실행될 수 있도록 **System Tweaks**에서 **Disable PHP in Plugins**(또는 동등한 옵션)을 비활성화합니다.

<Frame caption="iThemes PHP 플러그인 설정.">
  <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/f78a21b-php-in-plugins.jpg?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=ee27f7a8662e6f8e2b001056b22aa904" alt="플러그인의 PHP 허용이 체크 해제 또는 비활성화된 보안 플러그인 설정" width="818" height="188" data-path="images/docs/f78a21b-php-in-plugins.jpg" />
</Frame>

### Defender Security plugin

"Prevent PHP execution"을 활성화하지 마세요.
Defender Plugin > Security Tweaks로 이동하여 설정이 비활성화되어 있는지 확인합니다.

### 서비스 워커 액세스를 위한 .htaccess 예시

```apache theme={null}
<Files *.php>
Order allow,deny
Deny from all
</Files>
<Files OneSignalSDKWorker.js.php>
Allow from all
ForceType 'application/javascript; charset=UTF-8'
</Files>
<Files OneSignalSDKWorker.js>
Allow from all
ForceType 'application/javascript; charset=UTF-8'
</Files>
```

<Note>
  Apache 2.4+는 종종 `Order allow,deny` 대신 `Require all denied` / `Require all granted`를 사용합니다. 호스트에 문의하거나 서버의 Apache 버전에 맞게 규칙을 조정하세요.
</Note>

***

## 알림을 보낸 후 서버 속도 저하 또는 사이트에 액세스할 수 없음

알림을 보낸 후 서버 속도가 저하되거나 액세스할 수 없게 되면 알림 자산의 부하 증가 또는 제한된 서버 리소스로 인한 경우가 많습니다.

### 자체 알림 아이콘을 호스팅하지 마세요

알림에 사용되는 이미지를 자체 호스팅하지 마세요. 자체 알림 아이콘 또는 이미지를 호스팅하면 알림이 전송될 때 모든 수신자의 브라우저가 동시에 이미지를 가져오려고 시도하므로 서버에 과부하가 걸릴 수 있습니다.
서버 부하를 줄이려면 동시 액세스 수가 많은 환경에 최적화된 이미지 호스팅 솔루션 또는 CDN 서비스를 사용하세요.

### 호스팅 리소스 업그레이드 고려

서버 문제가 지속되면 다음이 필요할 수 있습니다:

* **호스팅 플랜 업그레이드:** 대규모 알림 전송을 처리하려면 더 높은 대역폭 또는 더 강력한 호스팅이 필요할 수 있습니다.
* **호스팅 제공업체에 문의:** 제공업체는 호스팅 환경에 특정한 인사이트 또는 최적화를 제공할 수 있습니다.

***