웹 SDK 설정

​

개요

​

요구 사항

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

​

OneSignal 앱 및 플랫폼 구성

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

​

사이트 설정

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

​

사이트 URL

• 단일 원본으로 리디렉션합니다.
• 또는 원본당 하나의 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 init 옵션에 allowLocalhostAsSecureOrigin 추가

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

복사

AI에게 묻기

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

​

권한 프롬프트

​

환영 알림 (선택 사항)

​

고급 설정

​

Webhooks

​

Service workers

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

​

클릭 동작

​

지속성

​

Safari 인증서 (선택 사항)

​

Service worker 파일 업로드

​

사이트에 코드 추가

  <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 웹 푸시 지원

​

FAQ

​

웹 푸시가 HTTP 사이트에서 작동하나요?

​

서비스 워커 파일이 왜 필요한가요?

​

iOS(iPhone/iPad)에서 웹 푸시를 사용할 수 있나요?

​

알림이 표시되지 않는 이유는 무엇인가요?

​

Testing the OneSignal SDK integration

​

Check web push subscriptions

1

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.

2

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 subscriptions

1

Add to Test Subscriptions.

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

2

Name your subscription.

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

3

Create a test users segment.

Go to Audience > Segments > New Segment.

4

Name the segment.

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

5

Add the Test Users filter and click Create Segment.

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

1

Get your App API Key and App ID.

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

2

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.

복사

AI에게 묻기

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"
}'

3

Run the code.

Run the code in your terminal.

4

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.

5

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.

푸시 알림 메시지 보고서

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

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

​

User identification

​

Assign External ID

​

Add data tags

​

Add email and/or SMS subscriptions

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

​

Privacy & user consent

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

​

Listen to push, user, and in-app events

​

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

​

Web SDK setup & reference