웹 SDK 설정 - OneSignal

개요

웹 푸시 알림을 사용하면 사용자에게 실시간 업데이트, 알림 및 개인화된 메시지를 보내 참여와 유지를 개선할 수 있습니다. OneSignal은 모든 주요 브라우저 및 플랫폼을 지원하므로 한 번 작성하여 Chrome, Firefox, Edge, Safari 및 기타 지원되는 브라우저에 전달할 수 있습니다.

요구 사항

HTTPS 웹사이트: 웹 푸시는 HTTP 또는 시크릿/프라이빗 모드에서 작동하지 않습니다.
서버 액세스: Service Worker 파일을 사이트에 업로드해야 합니다.
단일 원본: 웹 푸시는 동일 원본 정책을 따릅니다. 여러 원본(도메인/하위 도메인)이 있는 경우 원본당 하나씩 여러 OneSignal 앱이 필요합니다. 이 브라우저 제한을 준수하려면 다음 중 하나를 수행할 수 있습니다:
- 구독을 위해 트래픽을 단일 원본으로 리디렉션합니다.
- 원본당 하나씩 여러 OneSignal 앱을 생성합니다.

팀이 이미 OneSignal로 계정을 만든 경우 앱을 설정할 수 있도록 관리자 역할로 초대받도록 요청하세요. 그렇지 않으면 onesignal.com에서 무료 계정에 가입하여 시작하세요!

OneSignal 앱 및 플랫폼 구성

OneSignal 대시보드에서:

설정 > 푸시 및 인앱 > 웹으로 이동합니다.

OneSignal 설정에서 웹 플랫폼 활성화

통합 유형을 선택하세요:

일반 사이트(권장)

추가 코딩 없이 OneSignal 대시보드를 통해 직접 프롬프트 및 설정을 관리하세요.

WordPress

공식 플러그인으로 WordPress를 사용하는 경우 필요합니다.

사용자 지정 코드

프롬프트 및 SDK 구성에 대한 완전한 제어가 필요한 개발자를 위한 것입니다.

사이트 설정

사이트 세부 정보를 추가하세요:

사이트 이름: 사이트 이름 및 기본 알림 제목입니다.
사이트 URL: 사이트의 URL입니다. 자세한 내용은 사이트 URL을 참조하세요.
자동 재구독: 사용자가 사이트로 돌아올 때 브라우저 데이터를 지운 사용자를 자동으로 재구독하려면 이것을 활성화하세요(새 권한 프롬프트 필요 없음)
기본 아이콘 URL: 알림 및 프롬프트에 표시되는 정사각형 256x256px PNG 또는 JPG 이미지를 업로드하세요. 설정하지 않으면 기본 아이콘으로 벨을 사용합니다.

OneSignal 대시보드의 웹 설정

사이트 URL

사이트의 정확한 원본을 입력하세요(예: https://yourdomain.com). 사이트가 그렇게 구성되지 않은 경우 www. 사용을 피하세요. 여러 원본이 있는 경우:

단일 원본으로 리디렉션합니다.
또는 원본당 하나의 OneSignal 앱을 설정합니다.

로컬 테스트

웹 SDK는 localhost 환경에서 테스트할 수 있습니다. localhost에서 테스트하는 경우 프로덕션 앱이 아닌 다른 OneSignal 앱을 설정하는 것이 좋습니다.

Localhost 구성

사이트 URL을 localhost 환경 URL과 정확히 일치하도록 설정하세요. 일반적인 localhost URL이어야 합니다. 예:

http://localhost
https://localhost:3000
http://127.0.0.1
https://127.0.0.1:5000

localhost가 HTTP를 사용하는 경우 테스트를 위해 HTTP localhost를 HTTPS로 처리를 선택하세요.Google Chrome은 http://localhost 및 http://127.0.0.1을 보안 원본으로 처리하여 HTTP에서도 HTTPS 통합을 허용합니다. 이것이 HTTPS localhost에서 다른 비표준 원본을 테스트할 수 없는 이유입니다.

OneSignal 대시보드의 로컬 테스트

OneSignal `init` 옵션에 `allowLocalhostAsSecureOrigin` 추가

localhost 사이트에서 OneSignal을 초기화할 때 OneSignal init 옵션에 allowLocalhostAsSecureOrigin: true,를 추가하세요.또한 자체 서명된 인증서로 HTTPS에서 localhost를 테스트하는 경우 Chrome이 테스트용 유효하지 않은 인증서를 무시하도록 요청해야 할 수 있습니다: --allow-insecure-localhost. Firefox 및 Safari는 보안 인증서에 대한 예외를 추가하는 기본 제공 메커니즘을 제공합니다.

html

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

권한 프롬프트

일반적인 사이트 설정을 사용하면 사용자 또는 팀 구성원이 언제든지 OneSignal 대시보드를 통해 권한 프롬프트를 추가, 제거 및 업데이트할 수 있습니다.

권한 프롬프트에 대한 자세한 내용은 웹 권한 프롬프트를 참조하세요.

환영 알림 (선택 사항)

사용자가 푸시 알림을 구독할 때 전송할 환영 알림을 설정할 수도 있습니다.

고급 설정

OneSignal 대시보드에서 구성할 수 있는 추가 기능입니다.

Webhooks

웹 SDK는 특정 웹 푸시 이벤트를 선택한 URL로 POST할 수 있는 기능을 제공합니다. 웹 푸시 Webhook은 이벤트 Webhook과 별도의 구현이며 상호 교환하여 사용할 수 없습니다.

자세한 내용은 웹 푸시 Webhook을 참조하세요.

Service workers

웹 푸시 구성의 다음 페이지에서 OneSignalSDKWorker.js service worker 파일이 제공됩니다. 웹 SDK는 기본적으로 사이트의 루트에서 이 파일을 찾습니다. service worker 파일 위치, 이름 및/또는 범위를 변경하려는 경우 여기에서 이러한 설정을 업데이트할 수 있습니다.

Path to service worker files는 이러한 파일을 배치할 디렉토리의 경로입니다.
Main and Updater service worker filenames는 OneSignalSDKWorker.js이거나 이 파일의 이름을 변경하려는 경우 사용할 수 있습니다. .js 파일 확장자를 사용해야 합니다.
Service worker registration scope는 이 파일이 작동할 수 있는 페이지입니다. 푸시 알림의 경우 이것은 중요하지 않으며 원래 service worker 파일에 더 많은 기능을 추가하려는 경우를 위해 설계되었습니다. 이것을 위치와 동일한 경로로 설정해야 합니다.

Service worker 구성

이 예제에서는 https://yourdomain.com/push/onesignal/OneSignalSDKWorker.js에서 파일의 코드를 공개적으로 액세스할 수 있어야 합니다.

자세한 내용은 OneSignal Service Worker를 참조하세요.

클릭 동작

알림을 클릭할 때 설정한 URL로 사용자가 탐색하는 방법을 제어합니다.

사용자가 브라우저 탭에서 사이트를 열지 않은 경우 사이트로 이동하는 알림을 클릭하면 브라우저가 새 탭을 열고 알림의 URL로 이동합니다.
사용자가 하나 이상의 브라우저 탭에서 사이트를 연 경우 사이트로 이동하는 알림을 클릭하면 구성할 수 있는 여러 가지 방법으로 브라우저가 동작할 수 있습니다:
- Exact Navigate (기본값) - 알림의 정확한 URL(예: example.com/product)이 브라우저가 이미 열어둔 탭과 일치하면 브라우저가 해당 탭에서 알림의 URL로 이동합니다.
- Origin Navigate - 알림의 원본(예: example.com)이 브라우저가 이미 열어둔 탭과 일치하면 브라우저가 해당 탭에서 알림의 URL로 이동합니다.
- Exact Focus - 알림의 정확한 URL(예: example.com/product)이 브라우저가 이미 열어둔 탭과 일치하면 브라우저가 해당 탭에 포커스를 두지만 페이지를 새로 고치지 않습니다.
- Origin Focus - 알림의 원본(예: example.com)이 브라우저가 이미 열어둔 탭과 일치하면 브라우저가 해당 탭에 포커스를 두지만 페이지를 새로 고치지 않습니다.

지속성

기본 웹 푸시 동작은 장치에 약 5초 동안 팝업된 후 알림 센터로 이동되어 운영 체제에서 제거되기 전까지 약 1주일 동안 유지됩니다. 일부 장치 및 Chrome 및 Edge 버전에서는 화면에서 알림을 더 오래 유지할 수 있습니다. 이는 사용자가 상호 작용할 때까지 알림이 화면에 남아 있음을 의미합니다. 이것은 사용자를 짜증나게 할 수 있으며 권장되지 않습니다. 또한 지속성을 활성화하면 문자 수가 줄어들어 알림이 구독자에게 표시되는 방식에 영향을 미치고 이미지 및 버튼이 표시되는 방식에 영향을 줄 수 있습니다. 변경하면 업데이트된 설정으로 사이트를 방문하는 구독자에게만 적용됩니다. 이러한 옵션 변경이 표시되지 않으면 기다려야 합니다.

Safari 인증서 (선택 사항)

OneSignal은 추가 비용 없이 Safari 브라우저에서 작동하는 데 필요한 인증서를 자동으로 제공합니다. 이미 자체 Safari 웹 푸시 인증서가 있는 경우 이 옵션을 켜서 Safari Web .p12 Push Certificate 및 비밀번호를 업로드하세요.

Safari 인증서 구성

Service worker 파일 업로드

위의 고급 설정 > Service workers에서 간략하게 설명한 대로 OneSignalSDKWorker.js Service Worker 파일을 사이트에 추가합니다.

Service worker 파일 업로드 단계

고급 설정 > Service workers 섹션에서 Path to service worker files를 설정하지 않은 경우 사이트의 최상위 루트에 OneSignalSDKWorker.js 파일을 배치해야 합니다. 그렇지 않으면 설정한 디렉토리에 배치해야 합니다.

옵션 1. 서버에서 파일 생성 및 코드 복사
옵션 2. zip 폴더 다운로드 및 업로드

OneSignalSDKWorker.js라는 새 파일을 만들고 공개로 설정합니다.
다음 import 문을 파일에 복사하여 붙여넣습니다:

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

파일이 서버에 있으면 다음을 확인하여 작동하는지 확인합니다:

위치 확인

파일이 고급 설정 > Service workers에서 설정한 것과 동일한 Path to service worker files에 있는지 확인합니다. 이러한 설정을 업데이트하지 않은 경우 파일을 루트에 넣어야 합니다. 예를 들어:

https://yourdomain.com/OneSignalSDKWorker.js
https://yourdomain.com/some-subdirectory/OneSignalSDKWorker.js

원본에서 공개적으로 액세스할 수 있어야 함

OneSignalSDKWorker.js 파일은 원본에서 공개적으로 액세스할 수 있고 사용 가능해야 합니다. CDN을 통해 호스팅되거나 리디렉션으로 다른 원본에 배치될 수 없습니다.파일의 URL을 방문하면 코드가 표시되어야 합니다.

content-type: application/javascript로 제공되어야 함

이것은 javascript 파일이며 그렇게 제공되어야 합니다. text/html의 content-type을 가질 수 없습니다.

추가 질문이 있거나 다른 웹 푸시 제공업체에서 OneSignal로 마이그레이션하는 경우 OneSignal Service Worker 문서를 검토하는 것이 좋습니다.

사이트에 코드 추가

이제 사이트에 SDK를 추가할 준비가 모두 완료되었습니다. 제공된 JavaScript SDK 코드는 모든 사이트에서 작동해야 하지만 사이트가 Angular, React JS 또는 Vue JS를 사용하여 설정된 경우 이러한 링크를 따르세요. JavaScript SDK로 사이트에서 OneSignal을 초기화하려면 제공된 코드를 웹사이트의 <head> 태그에 복사/붙여넣기합니다. 대시보드는 다음 코드를 제공하지만 OneSignal 앱 ID를 포함합니다.

JavaScript

  <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",
      });
    });
  </script>

iOS 웹 푸시 지원

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

iOS 웹 푸시 설정

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

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

Check the OneSignal dashboard:

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

Dashboard showing subscription with 'Subscribed' status

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 subscriptions

Test subscriptions are helpful for testing a push notification before sending a message.

Add to Test Subscriptions.

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

Adding a device to Test Subscriptions

Name your subscription.

Name the subscription so you can easily identify your device later in the Test Subscriptions tab.

Dashboard showing the 'Name your subscription' field

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.

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

If all setup steps were completed successfully, the test subscriptions 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.

Expanded push notification with image on Chrome macOS

Check for confirmed delivery.

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

Delivery stats showing confirmed delivery

If you’re on a Professional plan or higher, scroll to Audience Activity to see subscription-level confirmation:

Confirmed delivery at the device level in Audience Activity

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

Need help? Contact support@onesignal.com with the following information:

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

We’ll be happy to help!

User identification

Previously, we demonstrated how to create web push Subscriptions. Now we’ll expand to identifying Users across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We’ll cover 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 our SDK’s login method each time they are 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 our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.

Add data 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 our SDK 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

Earlier we saw how our SDK creates web push subscriptions to send push. You can also reach users through emails 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.

See our Privacy & security docs for more on:

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:

Web SDK setup & reference

Make sure you’ve enabled all key features by reviewing the Web push setup guide. For full details on available methods and configuration options, visit the Web SDK reference.

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

도움이 필요하신가요?지원 팀과 채팅하거나 support@onesignal.com으로 이메일을 보내주세요.다음을 포함해 주세요:

발생한 문제의 세부 정보 및 재현 단계(가능한 경우)
OneSignal 앱 ID
External ID 또는 Subscription ID(해당하는 경우)
OneSignal 대시보드에서 테스트한 메시지의 URL(해당하는 경우)
관련 로그 또는 오류 메시지

기꺼이 도와드리겠습니다!

개발자 문서

모바일 SDKs

웹 SDKs

실시간 활동

데스크탑 & 워치 설정

레거시 SDK 참조

​개요

​요구 사항

​OneSignal 앱 및 플랫폼 구성

일반 사이트(권장)

WordPress

사용자 지정 코드

​사이트 설정

​사이트 URL

​로컬 테스트

​OneSignal init 옵션에 allowLocalhostAsSecureOrigin 추가

​권한 프롬프트

​환영 알림 (선택 사항)

​고급 설정

​Webhooks

​Service workers

​클릭 동작

​지속성

​Safari 인증서 (선택 사항)

​Service worker 파일 업로드

​사이트에 코드 추가

​iOS 웹 푸시 지원

iOS 웹 푸시 설정

​Testing the OneSignal SDK integration

​Check web push subscriptions

​Set up test subscriptions

​Send test push via API

​User identification

​Assign External ID

​Add data 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

개요

요구 사항

OneSignal 앱 및 플랫폼 구성

사이트 설정

사이트 URL

로컬 테스트

OneSignal `init` 옵션에 `allowLocalhostAsSecureOrigin` 추가

권한 프롬프트

환영 알림 (선택 사항)

고급 설정

Webhooks

Service workers

클릭 동작

지속성

Safari 인증서 (선택 사항)

Service worker 파일 업로드

사이트에 코드 추가

iOS 웹 푸시 지원

Testing the OneSignal SDK integration

Check web push subscriptions

Set up test subscriptions

Send test push via API

User identification

Assign External ID

Add data 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