OneSignal Web SDK를 사용한 사용자 지정 코드 웹 푸시 설정

고급 구성 또는 프로그래밍 방식 제어가 필요한 경우에만 이 사용자 지정 코드 설정을 사용하세요. 대부분의 사용자에게는 다음을 권장합니다:

JavaScript 프레임워크를 사용하는 경우 다음 전문 가이드를 따르세요:

요구 사항

HTTPS 웹사이트: 웹 푸시는 HTTP 또는 시크릿/비공개 모드에서 작동하지 않습니다.
서버 액세스: 서비스 워커 파일을 사이트에 업로드해야 합니다.
단일 출처: 웹 푸시는 동일 출처 정책을 따릅니다. 여러 출처(도메인/하위 도메인)가 있는 경우 여러 OneSignal 앱이 필요합니다(출처당 하나). 이 브라우저 제한을 준수하려면:
- 구독을 위해 트래픽을 단일 출처로 리디렉션합니다.
- 출처당 하나씩 여러 OneSignal 앱을 만듭니다.

OneSignal 앱 및 플랫폼 구성

OneSignal 대시보드에서:

Settings > Push & In-App > Web으로 이동합니다.
Custom Code 통합 유형을 선택합니다.

사이트 설정

사이트 세부 정보를 추가합니다:

Site Name: 사이트 이름 및 기본 알림 제목.
Site URL: 사이트의 정확한 출처(예: https://yourdomain.com). 사이트가 그렇게 구성되지 않은 경우 www. 사용을 피하세요. 여러 출처가 있는 경우 요구 사항을 참조하세요.
Auto Resubscribe: 사용자가 브라우저 데이터를 지운 후 사이트에 돌아올 때 자동으로 재구독하려면 이것을 활성화합니다(새 권한 프롬프트 불필요).
Default Icon URL: 알림 및 프롬프트에 표시되는 정사각형 256×256 PNG, JPG 또는 애니메이션이 아닌 GIF를 업로드합니다. 설정하지 않으면 기본값으로 벨 아이콘이 사용됩니다. 알림 아이콘을 참조하세요.

사용자가 브라우저 데이터를 지우면 사이트로 돌아올 때까지 푸시 수신이 중지됩니다. Auto Resubscribe를 활성화하면 새 권한 프롬프트 없이 다시 구독됩니다. 구독을 참조하세요.

OneSignal web push configuration showing site name, URL, and icon settings — OneSignal 대시보드의 웹 설정

로컬 테스트

localhost에서 테스트하려면 프로덕션 앱과 별도의 OneSignal 앱을 사용하고 init 옵션에 allowLocalhostAsSecureOrigin: true를 추가합니다. 자체 서명된 인증서로 HTTPS에서 localhost를 테스트하는 경우 --allow-insecure-localhost를 사용하여 Chrome에 잘못된 인증서를 무시하도록 지시해야 할 수 있습니다. Firefox와 Safari는 보안 인증서에 예외를 추가하는 기본 제공 메커니즘을 제공합니다.

  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(function(OneSignal) {
      OneSignal.init({
        appId: "YOUR_OS_APP_ID",
        allowLocalhostAsSecureOrigin: true,
      });
    });
  </script>

환영 알림(선택 사항)

사용자 지정 코드는 welcomeNotification 매개변수를 사용하여 OneSignal.init()에서 환영 알림을 설정합니다. Typical Site 및 WordPress는 대시보드에서 설정합니다. Web SDK 설정을 참조하세요.

서비스 워커 파일 업로드

Web SDK는 OneSignal.init()에서 사용자 지정 경로를 전달하지 않는 한 사이트 루트(https://yourdomain.com/OneSignalSDKWorker.js)에서 OneSignalSDKWorker.js를 찾습니다. 사용자 지정 코드는 대시보드의 Customize service worker paths and filenames 필드를 사용하지 않습니다. serviceWorkerPath 및 serviceWorkerParam을 사용하여 코드에서 SDK가 찾을 위치를 지정합니다. OneSignal 대시보드에서 파일을 다운로드하거나 다음 한 줄로 OneSignalSDKWorker.js라는 이름의 파일을 만드세요:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

루트(기본값): https://yourdomain.com/OneSignalSDKWorker.js에서 사용할 수 있도록 파일을 업로드합니다. serviceWorkerPath를 설정할 필요가 없습니다. SDK가 이 URL을 자동으로 요청합니다. 하위 디렉터리: 사이트에 이미 서비스 워커가 있는 경우(예: PWA), /를 소유한 워커와 충돌하지 않도록 OneSignal 파일을 /push/onesignal/과 같은 하위 디렉터리에 넣으세요. 그런 다음 OneSignal.init()에서 serviceWorkerPath 및 serviceWorkerParam을 전달해야 합니다. 사이트에 코드 추가를 참조하세요. 파일은 https://yourdomain.com/push/onesignal/OneSignalSDKWorker.js에서 공개적으로 액세스할 수 있어야 합니다.

파일이 사이트 루트에 없는데 serviceWorkerPath와 serviceWorkerParam을 생략하면 SDK는 여전히 https://yourdomain.com/OneSignalSDKWorker.js를 가져오고 서비스 워커 등록이 실패합니다.

OneSignal 서비스 워커

워커 결합, 사용자 지정 파일 이름 및 다른 제공업체에서의 마이그레이션.

사이트에 코드 추가

이 코드를 웹사이트의 <head> 섹션에 추가합니다. YOUR_ONESIGNAL_APP_ID를 OneSignal 대시보드의 앱 ID로 교체하세요. OneSignalSDKWorker.js가 사이트 루트에 있는 경우 이 스니펫을 사용하세요:

HTML

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
      notifyButton: {
        enable: true,
      },
    });
  });
</script>

파일이 하위 디렉터리에 있는 경우 serviceWorkerPath 및 serviceWorkerParam을 추가하세요. 이 옵션은 사용자 지정 코드에서 SDK에 루트가 아닌 위치를 알려주는 유일한 방법입니다.

HTML

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
      notifyButton: {
        enable: true,
      },
    });
  });
</script>

매개변수	설명	예시
`serviceWorkerPath`	사이트 루트에서 `.js` 파일까지의 상대 경로입니다. 앞에 슬래시를 포함하지 마세요.	`"push/onesignal/OneSignalSDKWorker.js"`
`serviceWorkerParam.scope`	서비스 워커가 제어하는 URL 경로입니다. 파일과 동일한 디렉터리를 사용하세요.	`"/push/onesignal/"`

지속성은 코드에서 persistNotification으로 설정됩니다. 대시보드의 Persistence 토글은 사용자 지정 코드에 적용되지 않습니다. 이 옵션을 생략하면 SDK는 현재 지속성이 켜진 것으로 취급합니다. 끄려면 persistNotification: false를 설정하세요. 데스크톱의 Chrome 및 Edge에서만 작동합니다. 지속성을 참조하세요.

iOS 웹 푸시 지원

Apple은 iOS 16.4+를 실행하는 iPhone 및 iPad에서 웹 푸시 알림 지원을 시작했습니다. 지원되는 브라우저에서 방문하면 웹 푸시가 그냥 “작동하는” Android 기기와 달리, Apple은 manifest.json 파일 및 사용자가 사이트를 홈 화면에 추가하는 작업 등 몇 가지 추가 요구 사항을 추가했습니다.

iOS 웹 푸시 설정

필요한 manifest.json 파일을 추가하고 사용자가 사이트를 홈 화면에 추가하도록 안내합니다.

Safari Web Push .p12 인증서(선택 사항, 레거시)

이미 자체 Safari Web Push .p12 인증서가 있고 레거시 Safari 사용자를 지원하려는 경우가 아니라면 이 설정을 꺼 두세요. 최신 Safari(macOS 13+ 및 iOS 16.4+)는 VAPID(Voluntary Application Server Identification)를 사용하는 표준 기반 Web Push를 사용합니다. OneSignal은 VAPID를 자동으로 처리합니다. 최신 Safari 브라우저를 위해 인증서를 업로드할 필요가 없습니다. 이미 자체 .p12가 있는 경우(Apple은 Safari Web Push에 .p8을 지원하지 않음) 대시보드에서 업로드하세요. Safari Web Push .p12 인증서를 참조하세요.

Testing the OneSignal SDK integration

This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.

Check web push subscriptions

Launch your site on a test device.

Use Chrome, Firefox, Edge, or Safari while testing.
Do not use Incognito or private browsing mode. Users cannot subscribe to push notifications in these modes.
The prompts should appear based on your permission prompts configuration.
Click Allow on the native prompt to subscribe to push notifications.

사용자에게 알림 허용 또는 차단을 묻는 브라우저 기본 권한 프롬프트 — Web push native permission prompt

Check your OneSignal dashboard

Go to Audience > Subscriptions.
You should see a new entry with the status Subscribed.

You have successfully created a web push subscription. Web push subscriptions are created when users first subscribe to push notifications on your site.

Set up test users

test users are helpful for testing a push notification before sending a message.

Add to Test Users.

In the dashboard, next to the subscription, click the Options (three dots) button and select Add to Test Users.

구독의 옵션 메뉴에 테스트 구독에 추가 옵션이 표시됨 — Adding a device to Test Users

Name your subscription.

Name the subscription so you can easily identify your device later in the test users tab.

Create a test users segment.

Go to Audience > Segments > New Segment.

Name the segment.

Name the segment Test Users (the name is important because it will be used later).

Add the Test Users filter and click Create Segment.

Test Users 필터가 선택되고 세그먼트 이름이 Test Users인 세그먼트 편집기 — Creating a 'Test Users' segment with the Test Users filter

You have successfully created a segment of test users. We can now test sending messages to this individual device and groups of test users.

Send test push via API

Get your App API Key and App ID.

In your OneSignal dashboard, go to Settings > Keys & IDs.

Update the provided code.

Replace YOUR_APP_API_KEY and YOUR_APP_ID in the code below with your actual keys. This code uses the Test Users segment we created earlier.

curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

Run the code.

Run the code in your terminal.

Check images and confirmed receipt.

If all setup steps were completed successfully, the test users should receive a notification.

Only Chrome supports images. Images will appear small in the collapsed notification view. Expand the notification to see the full image.

macOS Chrome에서 커스텀 이미지가 표시된 확장된 푸시 알림 — Expanded push notification with image on Chrome macOS

Check for confirmed receipt.

In your dashboard, go to Delivery > Sent Messages, then click the message to view stats. You should see the confirmed stat, meaning the device received the push.

Safari does not support confirmed receipt.

푸시 알림 메시지 보고서

푸시 알림의 전달, 클릭 및 전환 통계를 확인하세요.

You have successfully sent a notification via the API to a segment.

If notifications are not arriving, contact support@onesignal.com with the following:

The API request and response (copy-paste into a .txt file)
Your Subscription ID
Your website URL with the OneSignal code

User identification

The previous section covered creating web push Subscriptions. This section expands to identifying Users across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. It covers External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.

Assign External ID

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend’s user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for Integrations). Set the External ID with the SDK’s login method each time a user is identified by your app.

OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.Setting the External ID via the SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.

Add Tags

Tags are key-value pairs of string data you can use to store user properties (like username, role, or preferences) and events (like purchase_date, game_level, or user interactions). Tags power advanced Message Personalization and Segmentation allowing for more advanced use cases. Set tags with the SDK’s addTag and addTags methods as events occur in your app. In this example, the user reached level 6 identifiable by the tag called current_level set to a value of 6.

A user profile in OneSignal with a tag called "current_level" set to "6"

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

Segment editor showing a segment targeting users with a current_level value of greater than 4 and less than 10

Screenshot showing a push notification targeting the Level 5-10 segment with a personalized message

Add email and/or SMS subscriptions

The OneSignal SDK creates web push subscriptions automatically when users opt in. You can also reach users through email and SMS channels by creating the corresponding subscriptions.

Use the addEmail method to create email subscriptions.
Use the addSms method to create SMS subscriptions.

If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates. You can view unified users via Audience > Users in the dashboard or with the View user API.

A user profile with push, email, and SMS subscriptions unified by External ID

Best practices for multi-channel communication

Obtain explicit consent before adding email or SMS subscriptions.
Explain the benefits of each communication channel to users.
Provide channel preferences so users can select which channels they prefer.

To control when OneSignal collects user data, use the SDK’s consent gating methods:

setConsentRequired(true): Prevents data collection until consent is given.
setConsentGiven(true): Enables data collection once consent is granted.

For more on privacy and security:

SDK가 수집하는 데이터

OneSignal SDK가 사용자로부터 수집하는 데이터를 확인하세요.

개인 데이터 처리

개인정보 보호 규정에 따라 사용자 데이터를 관리하고 보호하세요.

Listen to push, user, and in-app events

Use SDK listeners to react to user actions and state changes. The SDK provides several event listeners for you to hook into. See our SDK reference guide for more details.

Push notification events

Click event listener: Detect when a notification is tapped.
Foreground lifecycle listener: Control how notifications behave in foreground.

User state changes

User state change event listener: Detect when the External ID is set.
Permission observer: Track the user’s specific interaction with the native push permission prompt.
Push subscription change observer: Track when the push subscription status changes.

Advanced setup & capabilities

Explore more capabilities to enhance your integration:

OneSignal로 마이그레이션

다른 푸시 공급자에서 OneSignal로 이전하세요.

통합

OneSignal을 서드파티 도구 및 플랫폼과 연결하세요.

액션 버튼

푸시 알림에 인터랙티브 버튼을 추가하세요.

다국어 메시징

사용자의 선호 언어로 현지화된 메시지를 전송하세요.

Identity Verification

서버 측 Identity Verification으로 SDK 통합을 보호하세요.

커스텀 아웃컴

메시지와 연결된 커스텀 전환 이벤트를 추적하세요.

Web SDK setup & reference

웹 푸시 설정

통합을 위한 모든 핵심 웹 푸시 기능을 활성화하세요.

Web SDK 레퍼런스

사용 가능한 메서드와 구성 옵션에 대한 전체 세부 정보.

Congratulations! You’ve successfully completed the Web SDK setup guide.

FAQ

Web SDK는 서비스 워커를 어디에서 찾나요?

Web SDK는 OneSignal.init()에서 serviceWorkerPath와 serviceWorkerParam을 전달하지 않는 한 사이트 루트(https://yourdomain.com/OneSignalSDKWorker.js)에서 OneSignalSDKWorker.js를 찾습니다. 사용자 지정 코드는 대시보드 경로 필드를 사용하지 않습니다. 서비스 워커 파일 업로드를 참조하세요.

웹 푸시 알림에 HTTPS가 필요한가요?

예. 모든 최신 브라우저는 푸시 알림 지원을 위해 HTTPS가 필요합니다. 사이트가 HTTP를 사용하는 경우 웹 푸시를 설정하기 전에 HTTPS로 마이그레이션해야 합니다.

단일 페이지 애플리케이션(SPA)에서 이 설정을 사용할 수 있나요?

예. 사용자 지정 코드 설정은 React, Angular 또는 Vue와 같은 프레임워크로 빌드된 SPA에 권장되는 접근 방식입니다. Angular 설정, React JS 설정 및 Vue JS 설정을 참조하세요.

사용자가 브라우저 데이터를 지우면 어떻게 되나요?

사용자의 푸시 구독이 제거됩니다. Auto Resubscribe가 활성화된 경우 다음번에 사이트를 방문할 때 자동으로 재구독됩니다.

권한 요청

사용자에게 구독을 요청하는 시기와 방법을 구성합니다.

Web SDK 참조

OneSignal Web SDK의 전체 API 참조.

​요구 사항

​OneSignal 앱 및 플랫폼 구성

​사이트 설정

​로컬 테스트

​환영 알림(선택 사항)

​서비스 워커 파일 업로드

OneSignal 서비스 워커

​사이트에 코드 추가

​iOS 웹 푸시 지원

iOS 웹 푸시 설정

​Safari Web Push .p12 인증서(선택 사항, 레거시)

​Testing the OneSignal SDK integration

​Check web push subscriptions

​Set up test users

​Send test push via API

푸시 알림 메시지 보고서

​User identification

​Assign External ID

​Add Tags

​Add email and/or SMS subscriptions

​Privacy & user consent

SDK가 수집하는 데이터

개인 데이터 처리

​Listen to push, user, and in-app events

​Push notification events

​User state changes

​Advanced setup & capabilities

OneSignal로 마이그레이션

통합

액션 버튼

다국어 메시징

Identity Verification

커스텀 아웃컴

​Web SDK setup & reference

웹 푸시 설정

Web SDK 레퍼런스

​FAQ

​Web SDK는 서비스 워커를 어디에서 찾나요?

​웹 푸시 알림에 HTTPS가 필요한가요?

​단일 페이지 애플리케이션(SPA)에서 이 설정을 사용할 수 있나요?

​사용자가 브라우저 데이터를 지우면 어떻게 되나요?

​관련 페이지

권한 요청

Web SDK 참조

요구 사항

OneSignal 앱 및 플랫폼 구성

사이트 설정

로컬 테스트

환영 알림(선택 사항)

서비스 워커 파일 업로드

사이트에 코드 추가

iOS 웹 푸시 지원

Safari Web Push .p12 인증서(선택 사항, 레거시)

Testing the OneSignal SDK integration

Check web push subscriptions

Set up test users

Send test push via API

User identification

Assign External ID

Add Tags

Add email and/or SMS subscriptions

Privacy & user consent

Listen to push, user, and in-app events

Push notification events

User state changes

Advanced setup & capabilities

Web SDK setup & reference

FAQ

Web SDK는 서비스 워커를 어디에서 찾나요?

웹 푸시 알림에 HTTPS가 필요한가요?

단일 페이지 애플리케이션(SPA)에서 이 설정을 사용할 수 있나요?

사용자가 브라우저 데이터를 지우면 어떻게 되나요?

관련 페이지