メインコンテンツへスキップ
Notifly JavaScript SDKは、WebアプリにNotiflyを組み込むためのSDKです。
次の機能を利用できます。
  • デバイス情報をNotiflyに登録し、Webプッシュ通知の受信とWebポップアップの表示を行います。
  • イベントとユーザー情報をNotiflyに連携し、キャンペーンのターゲティングや分析に利用します。
  • ユーザーの行動をイベントとして記録し、効果を測定します。

始める前に

  1. VAPIDキーを生成します。 Webプッシュ通知を送受信するには、コンソールの設定 → SDK設定 → ウェブサイト設定でVAPIDキーを生成します。Webプッシュ通知を使用する場合のみ必要です。
  2. ブラウザーの権限ポリシーに対応するため、HTTPS環境を推奨します。 最新のChrome、Edge、SafariとES2017以降の環境を推奨します。Webpack、Vite、Rollupなどのビルドツールを使用する場合は、Service Workerファイルがビルド出力から除外されないように設定してください。

1. 基本設定

1. Service Workerを登録する

ブラウザーのバックグラウンドでプッシュ通知を受信できるように、ルートディレクトリにService Workerファイルを作成します。
notifly-service-worker.jsに次のコードを追加します。
Service Workerのファイル名とパスは任意に指定できます。ただし、初期化設定のserviceWorkerPathと一致させる必要があります。
Webpack、Rollup、Parcelなどのバンドラーを使用する場合は、notifly-service-worker.jsがバンドルに取り込まれたり削除されたりしないよう、アセットのコピーを設定してください。
Web環境に合わせて、npm、yarn、pnpmによるパッケージのインストール、またはCDNスクリプトのいずれかを選択してください。

2. SDKを初期化する

string
必須
NotiflyのプロジェクトIDです。
string
必須
プロジェクトのユーザー名です。
string
必須
後方互換性のため、初期化オプションに含める必要があるプレースホルダーフィールドです。実際のパスワードやAPI Secret Keyは入力せず、usernameと同じ空でない値を渡してください。
number
非推奨
セッションの有効期間を秒単位で指定します。最小値は300、デフォルトは1800です。2.5.0以降ではコンソールの設定が適用されます。
NotiflyPushSubscriptionOptions
非推奨
Webプッシュのオプションです。2.5.0以降ではコンソールの設定を使用します。
SDK 2.5.0以降では、projectIdとusername以外の初期化設定はコンソールの設定に置き換わります。セッション、権限リクエストのポップアップ、Service Workerのパス、遅延時間、VAPIDキーが対象です。passwordは後方互換性のためのプレースホルダーです。実際のパスワードやAPI Secret Keyを入力しないでください。 NotiflyコンソールのJavaScript SDK設定画面

3. プッシュ通知の権限をリクエストする

コンソールで権限リクエストのポップアップ(askPermission)を有効にすると、サイト訪問時にページ上部の案内が表示され、その後ブラウザーの権限ダイアログが表示されます。 権限リクエストは次のルールに従います。
  • ユーザーが通知権限をまだ設定していない場合は、案内ポップアップの後にブラウザーの権限をリクエストします。
  • ユーザーがすでに通知を許可している場合は、ポップアップの表示も権限の再リクエストも行いません。
  • ユーザーが通知をブロック(拒否)している場合は、権限の再リクエストもポップアップの表示も行いません。
Webプッシュの標準権限リクエスト 会員登録の完了直後など、特定のタイミングでのみ権限をリクエストする場合は、手動で呼び出すを参照してください。
  • ポップアップのテキストや色をブランドに合わせて変更する場合は、ポップアップをカスタマイズするを参照してください。
  • 独自の権限リクエストUIを使用する場合は、次のように設定します。
    • SDK 2.5.0以降では、Notiflyコンソールで自動表示を無効にします。
    • SDK 2.5.0未満では、SDKの初期化時にaskPermission: falseを設定します。
    • その後、独自のUIで権限リクエストを実装します。
    • MDN Web Docs - Notification: requestPermissionを参照してください。

対応言語

SDKの権限リクエストのポップアップは、次の言語に対応しています。
  • SDK 2.8.0以降
    • ko(韓国語)
    • en(英語)
    • ja(日本語)
    • zh(中国語)
  • SDK 2.8.0未満
    • 韓国語と英語のみに対応しています。

手動で呼び出す

  • SDK 2.7.0以降が必要です。
  • コンソールで設定 → SDK設定 → ウェブサイト設定を開き、権限要求ポップアップ設定の自動表示を使用をオフにします。
ポップアップの表示言語は、次のルールで選択されます。
  1. languageパラメーターを渡した場合は、その言語コードでポップアップの表示を試みます。
  2. パラメーターを省略した場合、または未対応の言語コードを渡した場合は、ブラウザーの言語が対応言語であればその言語を使用します。ブラウザーの言語も未対応の場合は、以下のデフォルト表示言語を使用します。

デフォルト表示言語

この設定はNotifly JavaScript SDK 2.8.0以降で利用できます。2.8.0未満では、デフォルトの言語は常に韓国語(ko)です。
デフォルト表示言語は、次の場合に使用されます。
  • ブラウザーに優先言語が設定されていない場合。
  • ブラウザーの言語がSDKで対応していない場合。
Notiflyコンソールの設定 → SDK設定 → ウェブサイト設定を開き、権限要求ポップアップ設定のデフォルト表示言語を変更します。

ポップアップをカスタマイズする

  • このカスタマイズ機能はNotifly JavaScript SDK 2.7.0以降で利用できます。それより前のバージョンではSDKのデフォルトのポップアップが表示されます。 Webプッシュの標準権限リクエスト
  • コンソールで変更したデザインがユーザーの環境に反映されるまで、数分かかる場合があります。
Notiflyコンソールで設定 → SDK設定 → ウェブサイト設定 → 権限要求ポップアップ設定に移動します。 デザイン設定をクリックし、ポップアップのテキストとスタイルを編集します。 Webプッシュの権限リクエスト設定 変更を適用すると、更新したスタイルがユーザーに表示されます。 Webプッシュの権限リクエストのプレビュー

Webポップアップのボタンで同意を取得する

Webポップアップエディターでボタンブロック(Button)を選び、クリックアクションでWebプッシュの同意処理を選択します。このアクションでは、SDKが受信同意の保存、ブラウザーの通知権限リクエスト、プッシュ購読の登録を行います。未ログインのユーザーにも対応しており、同意を取得するために別途setUserId()を呼び出す必要はありません。コンソールの設定方法は、Webポップアップのユーザーガイドを参照してください。 連携の準備
  1. このアクションに対応したJavaScript SDKをサイトにインストールし、初期化します。未対応のSDKでは、ポップアップの同意ボタンが無効になります。
  2. コンソールの設定 → SDK設定 → ウェブサイト設定でWebプッシュを有効にし、VAPIDキーとService Workerのパスを設定します。指定したパスでService Workerが正常に登録されている必要があります。
  3. 通知の許可をこのポップアップでのみ求める場合は、自動表示を使用をオフにします。コンソール設定のweb_push_options.ask_permissionがfalseでも、このボタンアクションは動作します。
  4. 本番サイトはHTTPSで配信し、ブラウザーと実行環境が通知およびWebプッシュに対応していることを確認します。
新しい初期化オプションは不要です。allowUserSuppliedLogEventの設定にかかわらず動作し、ボタンのHTMLにtrackEvent()やrequestPermission()を直接呼び出すコードを追加する必要もありません。既存のnotifly.requestPermission()は、Notiflyの権限案内ポップアップを表示する別のAPIです。このアクションの同意属性は記録しません。 SDKの処理の流れ
  1. 対応するSDKがポップアップに準備完了の応答を返すと、同意ボタンが有効になります。
  2. ユーザーがボタンを直接クリックすると、SDKは内部のset_user_propertiesイベントで次の予約属性を更新します。
  3. 保存や分析イベントの完了を待たずに、ブラウザーの権限リクエストを開始します。ユーザーのクリックによる権限リクエストとして扱われるよう、Notiflyの事前案内モーダルやポップアップを閉じるアニメーションは先に実行しません。
  4. 権限リクエストを開始した直後にWebポップアップを閉じます。ブラウザーの応答やサーバーへの送信完了は待ちません。
  5. 権限が許可された場合は、ポップアップを閉じる処理とは別に、既存または新規のPushSubscriptionを内部のset_device_propertiesイベントのdevice_tokenとして登録します。ユーザーが許可を拒否したり権限ダイアログを閉じたりした場合や、実行環境が未対応の場合、処理に失敗した場合も、Webポップアップの再表示や結果の案内は行いません。すでに許可またはブロックされている権限は再リクエストしません。
ボタンのクリックは、既存のnotifly__main_button_clickイベントとしても記録されます。web_push_consentというカスタムイベントは別途送信しません。イベントパラメーターのbutton_nameには、ポップアップで設定したボタン名が入ります。 同意ボタンを押すとポップアップが閉じるため、同じポップアップでの重複クリックは処理しません。新しいポップアップで同意すると、同意時刻が更新されます。SDKは、同意を示すユーザー属性とプッシュ購読情報をNotiflyに送信します。ブラウザーの通知権限はサイト単位で適用されます。ユーザーが通知を許可すると、ページ読み込み時と同様に、その時点でログインしているユーザーにプッシュ購読が関連付けられます。 同意ボタンのクリック後に独自の処理を行う 同意ボタンが押されたときにサイト側で追加の処理を行うには、notifly.setPopupActionHandler()を使用します。このAPIを含むJavaScript SDKが必要です。 ボタンブロックの「버튼 이름 (이벤트 파라미터)」に consent_cta を設定します。画像では「ボタン名 (イベントパラメータ)」と表示しています。SDKをインストールした自社サイトのコードに次のコードを追加します。SDKの読み込み後、サイトの初期化コードで一度だけ登録してください。notifly.initialize()を呼び出す前でも登録できます。
ボタンブロックでイベントパラメーターに使うボタン名をconsent_ctaに設定
この例は、すべてのキャンペーンにあるconsent_ctaという名前の同意ボタンを処理します。特定のキャンペーンだけを対象にするには、event.campaignIdも確認してください。 コールバックは同意ボタンのアクションが発生したことを通知します。ブラウザーの権限許可やサーバーへの保存成功を意味するものではありません。 同意の記録と権限リクエストはSDKが処理するため、コールバック内でsetUserProperties()やrequestPermission()を再度呼び出す必要はありません。SDKはコールバックの完了を待たずに通常の処理を続けます。 登録できるハンドラーは1つだけです。再登録すると、前のハンドラーが置き換わります。不要になったらnotifly.setPopupActionHandler(null)で解除してください。 同意の記録と撤回の処理 予約属性は、ブラウザーのNotification.permissionをコピーした値ではありません。ボタンで同意した後にブラウザーで拒否したり権限ダイアログを閉じたりしても、保存済みの同意記録は維持されます。逆に、ブラウザーの権限がすでにgrantedであるだけでは、このアクションの同意属性は作成されません。 サービスで別途同意撤回用のUIを提供する場合は、ユーザーが撤回したときに次のように同意状態を更新できます。
この呼び出しは、ブラウザーの通知権限を解除したり、プッシュ購読を削除したりしません。撤回したユーザーを配信対象から除外するには、キャンペーンやユーザージャーニーの対象条件でも、$web_push_consentがtrueのユーザーのみを含めるように設定してください。$web_push_consented_atは最後の同意時刻を示すため、この呼び出しでは変更しません。
コンソールのプレビューではクリックアクションのログのみを記録し、実際の属性更新、権限リクエスト、購読登録は行いません。実際のサイトで、権限の未設定、許可、ブロックの各状態と、未ログインおよびログインへの切り替えを確認してください。ブラウザーの自動ブロックや未対応の環境では、権限ダイアログが表示されない場合があります。

2. SDKをインストールして初期化する

最新バージョンは次のとおりです。 npm ダウンロード数

1. パッケージマネージャー(npm、yarn、pnpm)

初期化の例(v2.5.0以降)

projectIdには連携先のプロジェクトIDを、usernameにはSDK認証情報のユーザー名を指定します。passwordは後方互換性のために必要な項目です。実際のパスワードやAPI Secret Keyを使わず、usernameと同じ空でない値を渡してください。

2. CDN

<body>内にスクリプトを追加します。読み込み後は、window.notiflyからSDKにアクセスできます。
  • AMDローダーを使用すると、<script>が競合する場合があります。v2.7.4以降のIIFEビルド(index.global.min.js)を推奨します。
  • SDKはwindowが存在するブラウザー環境でのみ動作します。レンダリング前に必ずtypeof window !== 'undefined'を確認してください。

3. ユーザー情報を登録する

NotiflyはユーザーID(userId)とユーザー属性(userProperties)に基づいて、マーケティングキャンペーンをパーソナライズします。
登録されたユーザー情報は、セグメント分けや、プッシュ通知、メール、カカオアリムトークなどの配信対象の指定に使用されます。

1. ユーザーIDを設定する

パラメーター

String
ログインしているユーザーのIDです。ログアウト時はnullを設定して解除します。

2. ユーザー属性を設定する

機密性の高いユーザー属性を送信する前に氏名や住所など、保護が必要なカスタムユーザー属性は、データの送信前にコンソールのユーザー管理 > ユーザー一覧の属性管理で送信するキーと同じ名前で登録し、暗号化を有効にしてください。設定方法と利用時の制限は、属性管理ガイドを参照してください。

パラメーター

Record<string, any>
必須
更新するユーザー属性の値です。
setUserProperties
予約属性キー。 チャネル配信やパーソナライズに使用する$email、$phone_number、$line_user_idなどのキーは、必ず指定された名前で設定してください。
ログアウト時にsetUserId(null)を呼び出すと、現在のデバイスとユーザーの関連付けが解除されます。

4. イベントを記録する

ユーザーの行動を記録し、キャンペーンのトリガー、セグメント条件、効果分析などに利用できます。
たとえば、ボタンのクリック、ページへのアクセス、購入完了などの行動をイベントとして収集します。

パラメーター

string
必須
イベント名です。例として”click_button”や”purchase_completed”などがあります。
Record<string, any>
イベントに付加するパラメーターです。例として”plan”: “premium”や”duration”: 120などがあります。
string[]
セグメント分けの基準に使用するキーのリストです。指定できるキーは最大1つです。
segmentationEventParamKeysを使うと、イベントパラメーター(eventParams)を配信対象の条件などに利用できます。指定できるキーは最大1つです。
trackEvent
呼び出し順序に注意してください。 ログイン時など、userIdを変更した直後は、setUserId → setUserProperties → trackEventの順序で呼び出すことを推奨します。

5. Webポップアップからカスタムイベントを記録する(任意)

WebポップアップのHTMLからカスタムイベントを記録するには、SDK 2.17.2以降と次のオプションが必要です。
ポップアップテンプレートへのログ記録コードの追加方法は、Notiflyチームにお問い合わせください。

6. 連携をテストする

SDKのインストール後、以下のページで実際のイベント収集とプッシュ通知の受信をテストしてください。
連携をテストする