Skip to main content
Use the Notifly JavaScript SDK to integrate Notifly into your web app.
The SDK supports the following features:
  • Register device information with Notifly to receive web push notifications and display web popups.
  • Send events and user information to Notifly for campaign targeting and analytics.
  • Log user actions as events and measure campaign performance.

Before you begin

  1. Create a VAPID key. To send and receive web push notifications, create a VAPID key in the console under Settings > SDK Settings > Website Settings. This step is required only if you use web push notifications.
  2. HTTPS is recommended because of browser permission policies. The recommended environment is a current version of Chrome, Edge, or Safari with ES2017 or later. If you use a build tool such as Webpack, Vite, or Rollup, configure it to include the service worker file in the build output.

1. Basic setup

1. Register a service worker

Create a service worker file in the root directory to receive push notifications while the browser runs in the background.
Add the following code to notifly-service-worker.js:
You can choose the service worker filename and path. The path must match the serviceWorkerPath initialization setting.
If you use a bundler such as Webpack, Rollup, or Parcel, configure asset copying so that notifly-service-worker.js remains a separate file in the build output.
Choose a package manager such as npm, yarn, or pnpm, or use a CDN script to suit your web environment.

2. Initialize the SDK

string
required
Your Notifly project ID.
string
required
Your project username.
string
required
A placeholder for backward compatibility. Include it in the initialization options. Do not enter a real password or API Secret Key. Pass the same nonempty value as username.
number
deprecated
Session duration in seconds. Minimum 300, default 1800. Version 2.5.0 and later use the console setting.
NotiflyPushSubscriptionOptions
deprecated
Web push options. Version 2.5.0 and later use the console settings.
In SDK 2.5.0 and later, the console settings replace all initialization settings except projectId and username. This includes the session duration, permission prompt, service worker path, prompt delay, and VAPID key. password is a placeholder for backward compatibility. Do not enter a real password or API Secret Key. JavaScript SDK settings in the Notifly console

3. Request push notification permission

If you enable the permission prompt (askPermission) in the console, visitors first see a prompt at the top of the page, followed by the browser permission dialog. Permission requests follow these rules:
  • If the user has not set a notification permission, the SDK shows the introductory prompt, then requests browser permission.
  • If the user has already allowed notifications, the SDK does not show the prompt or request permission again.
  • If the user has blocked notifications, the SDK does not request permission again or show the prompt.
Default web push permission prompt To request permission at a specific time, such as immediately after sign-up, see the manual request section below.
  • To match the prompt text and colors to your brand, see the prompt customization section below.
  • To use your own permission UI:
    • For SDK 2.5.0 and later, disable automatic display in the Notifly console.
    • For SDK versions earlier than 2.5.0, set askPermission: false when you initialize the SDK.
    • Then implement the permission request in your own UI.
    • See MDN Web Docs - Notification: requestPermission.

Supported languages

The SDK permission prompt supports the following languages:
  • SDK 2.8.0 and later
    • ko (Korean)
    • en (English)
    • ja (Japanese)
    • zh (Chinese)
  • SDK versions earlier than 2.8.0
    • Only Korean and English are supported.

Request permission manually

  • Requires SDK 2.7.0 or later.
  • In the Notifly console, go to Settings > SDK Settings > Website Settings > Permission Prompt Settings and turn off Auto Display.
The prompt language is selected as follows:
  1. If you pass the language parameter, the SDK attempts to display the prompt in that language.
  2. If you omit the parameter or pass an unsupported language code, the SDK uses the browser language if supported. Otherwise, it uses the default display language described below.

Default display language

This setting requires Notifly JavaScript SDK 2.8.0 or later. In earlier versions, the default language is always Korean (ko).
The default display language is used in the following cases:
  • The browser has no preferred language.
  • The SDK does not support the browser language.
In the Notifly console, go to Settings > SDK Settings > Website Settings. Under Permission Prompt Settings, change Default Display Language.

Customize the permission prompt

  • Prompt customization requires Notifly JavaScript SDK 2.7.0 or later. Earlier versions display the SDK’s default prompt. Default web push permission prompt
  • Design changes in the console may take a few minutes to appear for users.
In the Notifly console, go to Settings > SDK Settings > Website Settings > Permission Prompt Settings. Click Design Settings to edit the prompt text and style. Web push permission prompt settings Apply the changes to display the updated style to users. Web push permission prompt preview Use Button > Click action > Web push consent in the web popup editor to let the SDK save consent, request browser notification permission, and register the push subscription. This action also supports anonymous users. You do not need to call setUserId() separately to collect consent. For console setup, see the web popup user guide. Prepare the integration
  1. Install and initialize a JavaScript SDK version that supports this action on your website. The consent button is disabled if the SDK does not support it.
  2. Enable web push in the console under Settings > SDK Settings > Website Settings and configure the VAPID key and service worker path. The service worker must be registered successfully at that path.
  3. To request permission through this popup only, disable Auto Display. The button action works even when the console setting web_push_options.ask_permission is false.
  4. Serve your production website over HTTPS. Confirm that the browser and runtime support notifications and web push.
No new initialization options are required. The action works regardless of allowUserSuppliedLogEvent, and you do not need to add calls to trackEvent() or requestPermission() to the button HTML. Use notifly.requestPermission() to show the Notifly permission prompt separately. This call does not record the consent properties for this action. SDK processing flow
  1. The consent button becomes active when a compatible SDK sends a ready response to the popup.
  2. When the user clicks the button, the SDK updates the following reserved properties through an internal set_user_properties event.
  3. The SDK starts the browser permission request in direct response to the user’s click, without waiting for storage or analytics events to complete. It skips the Notifly introductory modal and starts the request before any popup closing animation.
  4. The SDK closes the web popup immediately after starting the permission request. It does not wait for the browser response or server transmission to finish.
  5. If permission is granted, the SDK registers the existing or new PushSubscription as device_token in an internal set_device_properties event, independently of closing the popup. If permission is denied, the dialog is dismissed, the environment is unsupported, or processing fails, the SDK does not reopen the web popup or show a result message. It does not request permission again if permission is already granted or blocked.
The click is also recorded as the existing notifly__main_button_click event. The SDK does not send a separate custom event named web_push_consent. The popup’s button name setting supplies button_name. Clicking the consent button closes the popup, so duplicate clicks on the same popup are not processed. Consenting in a new popup updates the timestamp. The SDK sends the user properties that record consent and the push subscription to Notifly. Browser notification permission applies to the site. When permission is granted, the push subscription is registered to the currently signed-in user, as it is when the page loads. Run custom actions after a consent button click Use notifly.setPopupActionHandler() to run additional site actions when the consent button is clicked. Your JavaScript SDK version must include this API. In the Button block, set 버튼 이름 (이벤트 파라미터) to consent_cta. The screenshot labels this field Button name (event parameter). Add the following code to your website code, where the SDK is installed. Register the handler once in your site initialization code after the SDK loads. You can register it before calling notifly.initialize().
Set the Button block's button name event parameter to consent_cta
This example handles consent buttons named consent_cta across all campaigns. To handle only a specific campaign, also check event.campaignId. The callback indicates that the consent button action occurred. It does not confirm that browser permission was granted or that the server saved the data. The SDK handles consent recording and the permission request, so you do not need to call setUserProperties() or requestPermission() again in the callback. The SDK continues its normal flow without waiting for the callback to finish. Only one handler can be registered. Registering another handler replaces the previous one. Call notifly.setPopupActionHandler(null) to remove it when no longer needed. Record consent and handle withdrawal The reserved properties do not mirror the browser’s Notification.permission. After the user consents through the button, the stored consent remains even if they deny browser permission or dismiss the dialog. Conversely, an existing browser permission of granted does not create this action’s consent properties. If your service provides a separate withdrawal UI, update consent as follows when the user withdraws it.
This call does not revoke browser notification permission or delete the push subscription. To exclude users who withdraw consent, configure campaign and user journey targeting to include only users whose $web_push_consent is true. The call leaves $web_push_consented_at unchanged because it records the last consent time.
The console preview records only the click action log. It does not update properties, request permission, or register a subscription. On your website, test unset, granted, and blocked permission states, as well as anonymous users and sign-in transitions. Browser blocking or unsupported environments may prevent the permission dialog from appearing.

2. Install and initialize the SDK

The badge below shows the latest version: npm Downloads

1. Package manager (npm, yarn, or pnpm)

Initialization example (v2.5.0 and later)

Set projectId and username to your project’s integration values. password is a placeholder for backward compatibility. Do not enter a real password or API Secret Key. Include the field in the initialization options and pass the same nonempty value as username.

2. CDN

Add the script inside <body>. After it loads, access the SDK through window.notifly.
  • Scripts may conflict with an AMD loader. Use the IIFE build (index.global.min.js) in v2.7.4 or later.
  • The SDK runs only in a browser environment where window exists. Check typeof window !== 'undefined' before rendering.

3. Register user information

Notifly uses the user ID (userId) and user properties (userProperties) to personalize marketing campaigns.
Registered user information is used for segmentation and targeting across channels such as push notifications, email, and Kakao AlimTalk.

1. Set the user ID

Parameters

String
The signed-in user’s ID. Pass null on sign-out to clear the association.

2. Set user properties

Before sending sensitive user propertiesBefore sending custom user properties that need protection, such as names or addresses, register each key under User Management > User List > Property management in the console and enable encryption. Use the same key names as in the data you send.For setup instructions and limitations, see the property management guide.

Parameters

Record<string, any>
required
User property values to update.
setUserProperties
Reserved property keys. Use the exact reserved names for keys used in channel delivery and personalization, such as $email, $phone_number, and $line_user_id.
Call setUserId(null) when the user signs out to disassociate the current device from the user.

4. Log events

Record user actions for campaign triggers, segment conditions, and performance analysis.
For example, collect button clicks, page views, and completed purchases as events.

Parameters

string
required
Event name, such as “click_button” or “purchase_completed”.
Record<string, any>
Additional event parameters, such as “plan”: “premium” and “duration”: 120.
string[]
Keys to use for segmentation. Supports at most one key.
Use segmentationEventParamKeys to make event parameters (eventParams) available for targeting and related settings. You can specify at most one key.
trackEvent
Call order matters. Immediately after changing userId, such as after sign-in, the recommended call order is setUserId → setUserProperties → trackEvent.

5. Log custom events from web popups (optional)

To log custom events from web popup HTML, use SDK 2.17.2 or later and enable the following option.
Contact the Notifly team for instructions on adding logging code to popup templates.

6. Test the integration

After you install the SDK, follow Test your integration to verify event collection and push notification delivery.