セットアップとデバッグ
OneSignalの呼び出しをOneSignalDeferred.push(async function() { ... })でラップする必要があることに気付くかもしれません。
function()内に必要な数のメソッドを追加できます。
OneSignal SDKは、ページでdefer属性を使用して読み込まれます。例:
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
これは、OneSignalコードがHTML文書が完全に解析された後に実行されることを意味し、OneSignal SDKによるサイトのブロッキングを防ぎます。ただし、これはOneSignalDeferred変数の存在に依存するページスクリプトに問題をもたらします。これを解決するには、OneSignalをサイトに追加する際に、次のように開始する必要があります:
window.OneSignalDeferred = window.OneSignalDeferred || [];
これによりOneSignalDeferred変数が作成され、OneSignalがすでに読み込まれている場合は、読み込まれたインスタンスに割り当てられます。それ以外の場合、OneSignal変数は空の配列 - []と等しくなります。
すべての配列には.push()関数があるため、この時点でOneSignalDeferred変数は、プッシュする関数の配列にすぎません。SDKが最終的に読み込まれると、SDK はこれまでにプッシュされたすべての関数を処理し、.push()を再定義します。
init()
OneSignal SDKを初期化します。これは、サイトの各ページの<head>タグで一度呼び出す必要があります。ONESIGNAL_APP_IDは、Keys & IDsで確認できます。
OneSignal SDKの初期化を遅延させたい場合は、プライバシーメソッドの使用をお勧めします。
Initオプションはカスタムコードセットアップでのみ機能します。それ以外の場合は、OneSignalダッシュボードで構成されます。
| パラメーター | タイプ | 説明 |
|---|---|---|
appId | String | 必須: Keys & IDsにあるOneSignal App ID。 |
requiresUserPrivacyConsent | Boolean | ユーザーがプライバシー同意を提供するまでSDKの初期化を遅延させます。セットアップを完了するにはsetConsentGiven()を呼び出す必要があります。 |
safari_web_id | String | アップロードしたSafari .p12証明書のSafari Web ID。Webクイックスタート。 |
promptOptions | Object | 権限プロンプトをカスタマイズします。詳細は以下。 |
notifyButton | Object | サブスクリプションベルを有効にして構成します。詳細は以下。 |
welcomeNotification | Object | ウェルカム通知をカスタマイズまたは無効にします。詳細は以下。 |
persistNotification | Boolean | Chrome(デスクトップのみ) - true:クリックされるまで通知が持続、false:短時間後に消えます。Firefox/Safariはこの設定を無視します。 |
webhooks | Object | イベントコールバックを構成します。Webhooksを参照。 |
autoResubscribe | Boolean | 推奨: ブラウザーキャッシュをクリアしたユーザーまたはOneSignalに移行したユーザーを自動的に再サブスクライブします。コードで使用すると、ダッシュボード設定を上書きします。 |
notificationClickHandlerMatch | String | "exact"(デフォルト):正確なURL一致でタブにフォーカス。"origin":同じドメインの任意のタブにフォーカス。 |
notificationClickHandlerAction | String | "navigate"(デフォルト):launchURLに移動。"focus":既存のタブにフォーカス("origin"一致でのみ使用)。 |
serviceWorkerParam | Object | サービスワーカーのscopeを設定します。該当する場合、他のサービスワーカーのスコープとは異なる必要があります。例:{ scope: "/myPath/myCustomScope/" } |
serviceWorkerPath | String | OneSignalサービスワーカーファイルの場所を設定します。例:"myPath/OneSignalSDKWorker.js" |
promptOptionsパラメーター
promptOptionsを使用して、ユーザー権限プロンプトをローカライズまたはカスタマイズします。すべてのフィールドはオプションです。
| パラメーター | タイプ | 説明 |
|---|---|---|
slidedown | Object | 構成オプションを含むpromptsの配列が含まれます。 |
prompts | Array of Objects | プロンプト構成の配列。例:"slidedown": { "prompts": [{...}, {...}] } |
type | String | プロンプトタイプ:
|
autoPrompt | Boolean |
|
delay | Object | 自動プロンプトが表示されるタイミングを制御:{ pageViews: 3, timeDelay: 20 } = 3回目のページビュー後と20秒待機後に表示。 |
text | Object | カスタムテキストオプション:
|
categories | Array of Objects | type: categoryの場合のみ。各オブジェクトには以下が含まれます:tag:内部キーlabel:ユーザーに表示される名前例: [ {tag: "local_news", label: "Local News"} ]。データタグを参照。 |
notifyButtonパラメーター
ページに表示されるサブスクリプションベル(通知ボタン)を構成します。
| パラメーター | タイプ | 説明 |
|---|---|---|
enable | Boolean | サブスクリプションベルを有効にします。デフォルトでは無効です。 |
displayPredicate | Function | ベルを表示/非表示するためにtrueまたはfalseを返すカスタム関数(またはPromise)。表示時に一度評価されます。 |
size | String | 'small'、'medium'、または'large'。サブスクリプション後に'small'に縮小されます。 |
position | String | 'bottom-left'または'bottom-right'。 |
offset | Object | CSSピクセルオフセット:{ bottom: '50px', left: '10px' } |
prenotify | Boolean | trueの場合、「1 unread」アイコンとカスタムホバーテキストを表示します。 |
showCredit | Boolean | ポップアップで「Powered by OneSignal」を非表示にするにはfalseに設定します。 |
text | Object | ベルUIのカスタムテキスト。 |
welcomeNotificationパラメーター
初回サブスクリプション後に送信されるウェルカム通知をカスタマイズします。
| パラメーター | タイプ | 説明 |
|---|---|---|
disable | Boolean | ウェルカム通知を無効にします。 |
message | String | 必須: 通知メッセージ。空白の場合、デフォルトは'Thanks for subscribing!'です。 |
title | String | 通知のタイトル。デフォルトはサイトのタイトルです。削除するには' '(スペース)を使用します(推奨されません)。 |
url | URL | ユーザーが通知をクリックしたときに開くオプションのURL。通常は不要です。 |
例:
setLogLevel()
コンソールに追加のログを出力するようにロギングを設定します。詳細については、ブラウザーDevToolsでのデバッグを参照してください。
JavaScript
'trace''debug''info''warn''error'
ユーザーIDとプロパティ
ユーザーがWebサイトでプッシュ通知にサブスクライブすると、OneSignalは自動的にOneSignal ID(ユーザーレベル)とサブスクリプションID(デバイスレベル)を作成します。一意のユーザー識別子を使用してlogin()を呼び出すことで、複数のサブスクリプション(例:デバイス、Email、電話番号)を単一のユーザーに関連付けることができます。
login(external_id)
提供されたexternal_idにユーザーコンテキストを設定します。このexternal_idに関連付けられたすべてのサブスクリプションとプロパティが単一のonesignal_idの下で統合されることを保証します。詳細については、ユーザーを参照してください。
主な動作:
external_idがすでに存在する場合、SDKはそのユーザーに切り替えます。ログイン前に収集された匿名データはマージされず、破棄されます。external_idが存在しない場合、ローカル状態は現在のonesignal_idの下に保存されます。ユーザーが匿名だった間に収集されたデータは保持されます。- ネットワーク障害またはサーバーエラー時にSDKが自動的に再試行します。
External IDが設定され、サブスクリプションがユーザーにリンクされていることを確認するために、ユーザーがサイトを開くたびに、またはサブスクリプション変更リスナー内でこのメソッドを呼び出します。
logout()
現在のユーザーをサブスクリプションからリンク解除します。
- 現在のプッシュサブスクリプションから
external_idを削除します。 - OneSignal IDを新しい匿名ユーザーにリセットします。
- 新しいデータ(例:タグ、サブスクリプション、セッションデータなど)は、
loginメソッドで識別されるまで、新しい匿名ユーザーに設定されます。
サブスクリプションを新しい匿名ユーザーに設定したい場合、ユーザーがアプリからサインアウトするときにこれを使用します。
JavaScript
OneSignal.User.onesignalId
ブラウザーにローカルに保存されている現在のユーザーのOneSignal IDを取得します。ユーザー状態が初期化される前に呼び出された場合、nullになる可能性があります。代わりに、User State addObserver()を使用してユーザー状態の変更をリッスンします。
JavaScript
OneSignal.User.externalId
ブラウザーにローカルに保存されている現在のユーザーのExternal IDを取得します。loginメソッドで設定されていない場合、またはユーザー状態が初期化される前に呼び出された場合、nullになる可能性があります。代わりに、User State addObserver()を使用してユーザー状態の変更をリッスンします。
JavaScript
addEventListener() User State
ユーザーコンテキストの変更(例:ログイン、ログアウト、ID割り当て)をリッスンします。
JavaScript
addAlias(), addAliases(), removeAlias(), removeAliases()
エイリアスは代替識別子(ユーザー名やCRM IDなど)です。
- エイリアスを追加する前に、
login()でexternal_idを設定します。external_idのないサブスクリプションに追加されたエイリアスは、複数のサブスクリプション間で同期されません。 - 詳細については、エイリアスを参照してください。
JavaScript
getLanguage(), setLanguage()
ユーザーの自動検出された言語を取得または上書きします。使用可能な言語コードのリストについては、多言語メッセージングを参照してください。
JavaScript
カスタムイベント
カスタムイベントを介してジャーニーをトリガーし、Wait Untilステップのアクティベーションを行います。カスタムイベントにはWeb SDK
160500+が必要ですカスタムイベントを追跡するには、ユーザーがログインしている必要があります。name- 必須。 文字列としてのイベント名。properties- オプション。 イベントに追加するキーと値のペア。プロパティディクショナリーまたはマップは、有効なJSONオブジェクトにシリアル化できる必要があります。ネストされた値をサポートします。
os_sdkの下にアプリ固有のデータをプロパティペイロードに自動的に含め、消費できるようにします。たとえば、サブスクリプションタイプ別にイベントをターゲティングするには、os_sdk.typeにアクセスします。
json
trackEvent()
JavaScript
データタグ
タグは、イベントまたはユーザープロパティに基づいてユーザーに設定する文字列データのカスタムkey : valueペアです。詳細については、データタグを参照してください。
addTag(), addTags()
現在のユーザーに単一または複数のタグを設定します。
- キーがすでに存在する場合、値は置き換えられます。
- プランのタグ制限を超えると、操作は警告なしで失敗します。
JavaScript
removeTag(), removeTags()
現在のユーザーから単一または複数のタグを削除します。
JavaScript
getTags()
ユーザーのタグのローカルコピーを返します。タグは、login()または新しいアプリセッション中にサーバーから更新されます。
JavaScript
プライバシー
setConsentRequired()
データ収集が開始される前にユーザーの同意を強制します。SDKを初期化する前に呼び出す必要があります。
このメソッドは、initメソッドにrequiresUserPrivacyConsent: trueを追加するのと同じです。
JavaScript
setConsentGiven()
データ収集に対するユーザーの同意を付与または取り消します。同意がない場合、OneSignalにデータは送信されず、サブスクリプションも作成されません。
setConsentRequired()またはrequiresUserPrivacyConsentがtrueに設定されている場合、setConsentGivenがtrueで呼び出されるまで、SDKは完全には有効になりません。setConsentGivenがtrueに設定され、サブスクリプションが作成された後、後でfalseに設定された場合、そのサブスクリプションは更新を受信しなくなります。そのサブスクリプションの現在のデータは、setConsentGivenが再びtrueに設定されるまで変更されません。- ユーザーやサブスクリプションデータを削除したい場合は、Delete userまたはDelete subscription APIを使用してください。
JavaScript
サブスクリプション
詳細については、サブスクリプションを参照してください。User.PushSubscription.id
ブラウザーにローカルに保存されている現在のユーザーのプッシュサブスクリプションIDを取得します。早すぎるタイミングで呼び出された場合、nullを返す可能性があります。変更に対応するために、サブスクリプションオブザーバー内でこのデータを取得することをお勧めします。
JavaScript
User.PushSubscription.token
現在のプッシュサブスクリプショントークンを返します。早すぎるタイミングで呼び出された場合、nullを返す可能性があります。変更に対応するために、サブスクリプションオブザーバー内でこのデータを取得することをお勧めします。
JavaScript
addEventListener() プッシュサブスクリプションの変更
このメソッドを使用して、次のようなプッシュサブスクリプションの変更に対応します:
- デバイスがGoogle(FCM)またはApple(APNs)から新しいプッシュトークンを受信する
- OneSignalがサブスクリプションIDを割り当てる
optedIn値が変更される(例:optIn()またはoptOut()を呼び出した)- ユーザーがシステム設定でプッシュ権限を切り替え、その後アプリを開く
onPushSubscriptionChangeイベントをトリガーします。リスナーはpreviousとcurrentの値を持つ状態オブジェクトを受け取るため、何が変更されたかを正確に検出できます。
更新のリッスンを停止するには、関連付けられたremoveObserver()またはremoveEventListener()メソッドを呼び出します。
JavaScript
optOut(), optIn(), optedIn
現在のプッシュサブスクリプションのサブスクリプションステータス(subscribedまたはunsubscribed)を制御します。これらのメソッドを使用して、サイトのプッシュサブスクリプションステータスを制御します。一般的なユースケース:1)ログアウトしたユーザーへのプッシュ送信を防止する。2)サイト内に通知設定センターを実装する。
optOut():現在のプッシュサブスクリプションステータスをunsubscribedに設定します(ユーザーが有効なプッシュトークンを持っている場合でも)。optIn():次の3つのアクションのいずれかを実行します:- サブスクリプションに有効なプッシュトークンがある場合、現在のプッシュサブスクリプションステータスを
subscribedに設定します。 - サブスクリプションに有効なプッシュトークンがない場合、プッシュ権限プロンプトの表示を試みます。
- サブスクリプションに有効なプッシュトークンがある場合、現在のプッシュサブスクリプションステータスを
optedIn:現在のプッシュサブスクリプションステータスがsubscribedの場合はtrueを返し、それ以外の場合はfalseを返します。プッシュトークンが有効だがoptOut()が呼び出された場合、これはfalseを返します。
JavaScript
addEmail(), removeEmail()
現在のユーザーにEmailサブスクリプション(Emailアドレス)を追加または削除します。正しいユーザーコンテキストを設定するために、login()の後にaddEmailを呼び出します。Identity Verificationと互換性があります。
JavaScript
addSms(), removeSms()
現在のユーザーにSMSサブスクリプション(電話番号)を追加または削除します。E.164形式が必要です。正しいユーザーコンテキストを設定するために、login()の後にaddSmsを呼び出します。Identity Verificationと互換性があります。
JavaScript
スライドダウンプロンプト
サイトにさまざまなスライドダウンプロンプトを表示します。詳細については、Web権限プロンプトを参照してください。- 却下された場合、今後の呼び出しは少なくとも3日間無視されます。さらに拒否すると、ユーザーに再度プロンプトを表示するまでに必要な時間が長くなります。
- バックオフ動作を上書きするには、メソッドに
{force: true}を渡します。ただし、良好なユーザーエクスペリエンスを提供するために、アクションをボタンクリックなどのUI起動イベントにバインドします。
これは、サブスクリプションに必要なネイティブブラウザープロンプトを置き換えるものではありません。ネイティブブラウザープロンプトを使用して権限を取得する必要があります。
promptPush()
プッシュ通知の通常のスライドダウンプロンプトを表示します。
- カテゴリを使用している場合は、代わりに
promptPushCategories()を呼び出します。 - OneSignalによって設定されたバックオフロジックの対象となります。詳細については、Web権限プロンプトを参照してください。
JavaScript
promptPushCategories()
カテゴリスライドダウンプロンプトを表示し、ユーザーがタグを更新できるようにします。ユーザーがまだ権限を付与していない場合は、ネイティブ通知権限プロンプトもトリガーします。
- カテゴリを使用していない場合は、代わりに
promptPush()を呼び出します。 - OneSignalによって設定されたバックオフロジックの対象となります。詳細については、Web権限プロンプトを参照してください。
JavaScript
promptSms()
SMSサブスクリプションプロンプトを表示します。
- OneSignalによって設定されたバックオフロジックの対象となります。詳細については、Web権限プロンプトを参照してください。
JavaScript
promptEmail()
Emailサブスクリプションプロンプトを表示します。
- OneSignalによって設定されたバックオフロジックの対象となります。詳細については、Web権限プロンプトを参照してください。
JavaScript
promptSmsAndEmail()
SMSとEmailサブスクリプションプロンプトを同時に表示します。
- OneSignalによって設定されたバックオフロジックの対象となります。詳細については、Web権限プロンプトを参照してください。
JavaScript
addEventListener() Slidedown
スライドダウンプロンプト表示イベントを検出するためのコールバックを追加します。
JavaScript
プッシュ通知
requestPermission()
ネイティブブラウザープロンプトを介してプッシュ通知の権限を要求します。ブラウザーによって設定されたバックオフロジックの対象となります。詳細については、Web権限プロンプトを参照してください。
JavaScript
isPushSupported()
現在のブラウザーがWebプッシュをサポートしている場合はtrueを返します。
JavaScript
OneSignal.Notifications.permission
サイトの現在の通知表示権限を示すブール値を返します。
true:ユーザーが通知を表示する権限を付与しました。false:ユーザーが権限を拒否したか、まだ付与していません。
optOutステータスまたはサブスクリプションIDとプッシュトークンの存在は考慮されません。これらについては、OneSignal.User.PushSubscriptionを参照してください。
権限の変更をリッスンするには、permissionChangeイベントを使用します。
JavaScript
addEventListener() notifications
通知イベントにイベントハンドラーをアタッチすることで、通知のライフサイクルにフックできます。addEventListenerを呼び出すと、通知イベントに任意の数のイベントハンドラーを追加できます。
イベントのリッスンを停止するには、関連付けられたremoveEventListener()メソッドを呼び出します。
JavaScript
permissionChange
このイベントは、ユーザーがAllowまたはBlockをクリックするか、ブラウザーのネイティブ権限リクエストを却下したときに発生します。
JavaScript
permissionPromptDisplay
このイベントは、ブラウザーのネイティブ権限リクエストが表示されたときに発生します。
JavaScript
click
このイベントは、通知の本文/タイトルまたはアクションボタンがクリックされたときに発生します。
JavaScript
foregroundWillDisplay
このイベントは、通知が表示される前に発生します。このイベントはページで発生します。サイトで複数のブラウザータブが開いている場合、このイベントはOneSignalがアクティブなすべてのページで発生します。
JavaScript
dismiss
このイベントは、次の場合に発生します:
- ユーザーが通知本文またはアクションボタンをクリックせずに意図的に通知を却下した
- Android上のChromeで、ユーザーがすべてのWebプッシュ通知を却下した(このイベントは、表示する各Webプッシュ通知に対して発生します)
- 通知が自動的に期限切れになり消える
このイベントは、ユーザーが通知本文またはアクションボタンの1つをクリックした場合は発生しません。それは通知
clickイベントと見なされます。JavaScript
setDefaultUrl()
通知のデフォルトURLを設定します。
デフォルトURLを設定していない場合、通知はデフォルトでサイトのルートに開きます。
JavaScript
setDefaultTitle()
通知に表示するデフォルトのタイトルを設定します。
JavaScript
アウトカム
sendOutcome()
OneSignalダッシュボードで表示できるアウトカムをトリガーします。アウトカム名(string、必須)と値(number、オプション)を受け入れます。同じアウトカム名でsendOutcomeメソッドが呼び出されるたびに、アウトカムカウントが増加し、アウトカム値は渡された金額だけ増加します(含まれている場合)。詳細については、カスタムアウトカムを参照してください。
JavaScript
sendUniqueOutcome()
OneSignalダッシュボードで表示できるアウトカムをトリガーします。アウトカム名(string、必須)のみを受け入れます。sendUniqueOutcomeは、そのアウトカムのカウントをユーザーごとに1回だけ増加させます。詳細については、カスタムアウトカムを参照してください。
JavaScript