セットアップとデバッグ
OneSignalの呼び出しはOneSignalDeferred.push(async function (OneSignal) { ... })でラップする必要がある場合があります(awaitが不要な場合はfunction (OneSignal) { ... }を使用します)。**OneSignal**引数は、このリファレンス全体で使用されるSDKインスタンスです(例:await OneSignal.init({ ... }))。
複数のコールバックをプッシュすることも、1つのコールバック内に複数のステートメントを入れることもできます。
OneSignal SDKは、ページでdefer属性を使用して読み込まれます。例:
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
この方法により、SDKはドキュメントの解析後に実行され、レンダリングをブロックしません。それより早く実行されるスクリプトには、SDKの準備が整うまで処理をキューに入れる場所が必要です。次のコードから始めます:
window.OneSignalDeferred = window.OneSignalDeferred || [];
この行は、OneSignalDeferredが存在しない場合に定義します。ページ上の以前のスニペットがすでに設定している場合は、同じ参照が保持されます。それ以外の場合は、コールバックをプッシュする空の配列[]として始まります。
配列には.push()メソッドがあるため、OneSignalDeferred.push(...)で関数をエンキューします。SDKが読み込まれると、キューを処理し、.push()を再定義して、以降のプッシュが即座に実行されるようにします(Web SDKソースを参照)。
以下のほとんどのスニペットは
OneSignal単体を使用しています。セクションで別途記載がない限り(例:init前のsetConsentRequired())、これはawait OneSignal.init({ ... })後の遅延コールバックから取得したインスタンスとして扱ってください。init()
OneSignal SDKを初期化します。これは、サイトの各ページの<head>タグで一度呼び出す必要があります。ONESIGNAL_APP_IDは、Keys & IDsで確認できます。
OneSignal SDKの初期化を遅延させたい場合は、プライバシーメソッドの使用をお勧めします。
promptOptionsパラメーター
promptOptionsを使用して、ユーザー権限プロンプトをローカライズまたはカスタマイズします。すべてのフィールドはオプションです。
構造:promptOptions.slidedown.promptsは配列で、各要素が1つのプロンプト構成です。type、autoPrompt、delay、text、categoriesフィールドは、initのappIdの隣のトップレベルキーとしてではなく、prompts内の各オブジェクトに属します。
notifyButtonパラメーター
ページに表示されるサブスクリプションベル(通知ボタン)を構成します。
welcomeNotificationパラメーター
初回サブスクリプション後に送信されるウェルカム通知をカスタマイズします。
例:
setLogLevel()
コンソールに追加のログを出力するようにロギングを設定します。詳細については、トラブルシューティング手順を参照してください。init後の遅延コールバックから実行します(他の場所と同じ**OneSignal**インスタンス)。
JavaScript
'trace''debug''info''warn''error'
ユーザーIDとプロパティ
ユーザーがWebサイトでプッシュ通知にサブスクライブすると、OneSignalは自動的にOneSignal ID(ユーザーレベルID)とサブスクリプションID(デバイスレベルID)を作成します。一意のユーザー識別子を使用してlogin()を呼び出すことで、複数のサブスクリプション(例:デバイス、Email、電話番号)を単一のユーザーに関連付けることができます。
login(external_id)
現在のユーザーコンテキストを、提供されたexternal_idに設定します。これにより、現在のデバイス(Webプッシュサブスクリプション)が既知のユーザーにリンクされ、以降のすべてのデータが単一のonesignal_idの下で統合されます。このメソッドは識別済みユーザーにのみ使用してください(例:ログイン後やアカウント復元後)。匿名ユーザーの場合はloginを呼び出さないでください。代わりに、自動的に割り当てられたonesignal_idを使用して追跡します(OneSignal.User.onesignalIdを参照)。
login(external_id)を呼び出すと何が起こるか
SDKは、external_idがOneSignalアプリ内にすでに存在するかどうかによって動作が異なります。
external_idがすでに存在する場合:
- SDKはその既存のユーザーに切り替えます。
- ブラウザーのネットワークログまたはコンソールに
409 Conflictが表示される場合があります。これはExternal IDがアプリ内にすでに存在することを意味します。このパスでは想定内であり、通常は処理する必要のあるPromiseの拒否ではありません。
- ブラウザーのネットワークログまたはコンソールに
- 現在の
onesignal_idは破棄され、そのユーザーの既存のonesignal_idが読み込まれます。 - 現在のデバイス(Webプッシュサブスクリプション)は既存のユーザーにリンクされます。
- ログイン前に収集された匿名データはマージされず、破棄されます。これには、タグ、セッションデータ、Email/SMSサブスクリプション、およびその他のローカルユーザープロパティが含まれます。
external_idが存在しない場合:
- 現在の
onesignal_idを使用して新しいユーザーが作成されます。 - ユーザーが匿名だった間に収集されたすべてのデータは保持されます。
- デバイス(Webプッシュサブスクリプション)はこの新しいユーザーにリンクされます。
- SDKは、ネットワーク障害またはサーバーエラー時にログインリクエストを自動的に再試行します。
- 独自の再試行ロジックを実装する必要はありません。
- ユーザーのIDが判明したら(例:サインイン後やセッション復元後)、ページ読み込みごとに
login(external_id)を呼び出します。 - サインインしているユーザーが変わるたびに(アカウント切り替え)再度呼び出します。
- 安定した既知のユーザー識別子を取得する前に
loginを呼び出さないでください。
JavaScript
logout()
現在のユーザーをWebプッシュサブスクリプションからリンク解除します。
- 現在のWebプッシュサブスクリプションから
external_idを削除します。他のサブスクリプションからはexternal_idを削除しません。 onesignal_idを新しい匿名ユーザーにリセットします。- 新しいデータ(例:タグ、サブスクリプション、セッションデータなど)は、
loginメソッドで識別されるまで、新しい匿名ユーザーに設定されます。
ユーザーがサイトからサインアウトし、そのブラウザーにターゲットを絞ったトランザクションメッセージをこれ以上送信したくない場合に使用します。
JavaScript
OneSignal.User.onesignalId
ブラウザーにローカルに保存されている現在のユーザーのonesignal_idを取得します。この値はアクティブなユーザーコンテキスト(OneSignalのユーザーID)を表し、時間の経過とともに変化する可能性があります。たとえば、login(external_id)を呼び出したときや、SDKが初期化されたときなどです。早すぎるタイミングで呼び出された場合、このメソッドはnullを返す可能性があります。
この値は、ブラウザー(つまりWebプッシュサブスクリプション)を識別するために使用されるサブスクリプションIDではありません(User.PushSubscription.idを参照)。
onesignal_idが利用可能になるタイミング:
- OneSignal SDKの初期化が完了した後
login(external_id)でユーザーが識別された後- ユーザーの切り替えまたはセッションの復元後
addEventListener('change', …)を使用してください。
一般的なユースケース:
ほとんどの場合、loginメソッドで設定した独自のExternal IDを使用することになります。ただし、onesignal_idを直接使用したい場合もあります。
- External IDが設定される前の匿名ユーザーの追跡
- サポートやデバッグのためにOneSignal IDをバックエンドに保存
- OneSignalユーザーと内部ログの関連付け
- トラブルシューティングやQAのためのID表示
JavaScript
OneSignal.User.externalId
ブラウザーにローカルに保存されている現在のユーザーのExternal IDを取得します。loginメソッドで設定されていない場合、またはユーザー状態が初期化される前に呼び出された場合、nullになる可能性があります。代わりに、User State addEventListener('change', …)を使用してユーザー状態の変更をリッスンします。
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+が必要です。カスタムイベントを追跡するには、ユーザーがログインしている必要があります。カスタムイベントAPIは、window.OneSignalではなく、OneSignalDeferred.pushに渡される**OneSignalインスタンス上で呼び出してください(このページ上部のセットアップとデバッグ**を参照)。ページSDKは遅延キューを通じて初期化され、そのコールバックがOneSignal.Userにアクセスするためのサポートされた方法です。name- 必須。 文字列としてのイベント名。properties- オプション。 イベントに追加するキーと値のペア。プロパティディクショナリーまたはマップは、有効なJSONオブジェクトにシリアル化できる必要があります。ネストされた値をサポートします。
os_sdkの下にアプリ固有のデータをプロパティペイロードに自動的に含め、消費できるようにします。たとえば、サブスクリプションタイプ別にイベントをターゲティングするには、os_sdk.typeにアクセスします。
json
trackEvent()
init()の完了後に呼び出します。この例では、initが常にtrackEventより先に実行されるように、1つの遅延コールバックを使用しています:
JavaScript
本番環境では、すでに
await OneSignal.init(...)を実行している遅延コールバックにtrackEventを追加してください。意図しない限り、2つ目のinitを登録しないでください。タグ
タグは、イベントまたはユーザープロパティに基づいてユーザーに設定する文字列データのカスタムkey : valueペアです。詳細については、タグを参照してください。
addTag(), addTags()
現在のユーザーに単一または複数のタグを設定します。
- キーがすでに存在する場合、値は置き換えられます。
- プランのタグ制限を超えると、操作は警告なしで失敗します。
JavaScript
removeTag(), removeTags()
現在のユーザーから単一または複数のタグを削除します。
JavaScript
getTags()
ユーザーのタグのローカルコピーを返します。タグは、login()または新しいアプリセッション中にサーバーから更新されます。
JavaScript
プライバシー
setConsentRequired()
データ収集が開始される前にユーザーの同意を強制します。init()が実行される前に呼び出す必要があります(たとえば、最初のOneSignalDeferredコールバックの先頭、await OneSignal.init(...)の前)。
このメソッドは、initオプションにrequiresUserPrivacyConsent: trueを追加するのと同じです。
JavaScript
setConsentGiven()
データ収集に対するユーザーの同意を付与または取り消します。同意がない場合、OneSignalにデータは送信されず、サブスクリプションも作成されません。
setConsentRequired()またはrequiresUserPrivacyConsentがtrueに設定されている場合、setConsentGivenがtrueで呼び出されるまで、SDKは完全には有効になりません。setConsentGivenがtrueに設定され、サブスクリプションが作成された後、後でfalseに設定された場合、そのサブスクリプションは更新を受信しなくなります。そのサブスクリプションの現在のデータは、setConsentGivenが再びtrueに設定されるまで変更されません。- ユーザーやサブスクリプションデータを削除したい場合は、Delete userまたはDelete subscription APIを使用してください。
JavaScript
サブスクリプション
サブスクリプションは単一のメッセージングチャネルインスタンス(たとえばブラウザー)を表し、一意のサブスクリプションID(OneSignalのデバイスレベルID)を持ちます。1人のユーザーは、デバイスやプラットフォームをまたいで複数のサブスクリプションを持つことができます。 詳細については、サブスクリプションを参照してください。User.PushSubscription.id
SDKによってローカルに保存されている、現在のブラウザーのWebプッシュサブスクリプションIDを取得します。
このIDは、ユーザーではなく、この特定のブラウザーのプッシュチャネルを一意に識別します。デバイスやブラウザーをバックエンドと関連付ける場合や、配信の問題をデバッグする場合によく使用されます。
サブスクリプションが作成または復元される前に呼び出された場合、この値はnullになる可能性があります。
WebプッシュサブスクリプションIDが利用可能になるタイミングや変更を確実に検出するには、プッシュサブスクリプションリスナーを使用してください。
JavaScript
User.PushSubscription.token
現在のプッシュサブスクリプショントークンを返します。早すぎるタイミングで呼び出された場合、nullを返す可能性があります。変更に対応するために、サブスクリプションオブザーバー内でこのデータを取得することをお勧めします。
JavaScript
addEventListener() プッシュサブスクリプションの変更
このメソッドを使用して、次のようなプッシュサブスクリプションの変更に対応します:
- デバイスがGoogle(FCM)またはApple(APNs)から新しいプッシュトークンを受信する
- OneSignalがサブスクリプションIDを割り当てる
optedIn値が変更される(例:optIn()またはoptOut()を呼び出した)- ユーザーがブラウザーまたはOSの設定でプッシュ権限を切り替え、その後サイトに戻る
previousとcurrentを含む状態オブジェクトを引数に**change**リスナーを実行するため、何が変更されたかを検出できます。
autoResubscribeがtrueの場合、再訪問者ではpreviousとcurrentの両方でoptedIn: trueのchangeイベントが発生することがあります。これはブラウザーの権限が変更されず、プッシュトークンのみが再登録されたためです(たとえば、サイトデータのクリア後や移行後)。新規または再サブスクリプションを反映すべき分析やサーバーサイドの追跡では、optedInのみを比較するよりも、event.current.token && !event.previous.tokenの方が通常は信頼性が高くなります。addEventListener()に渡したものと同じハンドラー参照でremoveEventListener()を呼び出します。
JavaScript
dataLayer経由のGoogle Analytics): 以前にトークンがなく、プッシュトークンが現れたときにカスタムイベントを発火させることで、optedInが変わらない再登録も正しくカウントされます。サブスクリプションIDはタイミングによって、同じコールバックまたは後のchangeイベントで到着する場合があります:
JavaScript
optOut(), optIn(), optedIn
現在のプッシュサブスクリプションのサブスクリプションステータス(subscribedまたはunsubscribed)を制御します。これらのメソッドを使用して、サイトのプッシュサブスクリプションステータスを制御します。一般的なユースケース:1)ログアウトしたユーザーへのプッシュ送信を防止する。2)サイト内に通知設定センターを実装する。
optOut():現在のプッシュサブスクリプションステータスをunsubscribedに設定します(ユーザーが有効なプッシュトークンを持っている場合でも)。optIn():次のいずれかを実行します:- サブスクリプションに有効なプッシュトークンがある場合、現在のプッシュサブスクリプションステータスを
subscribedに設定します。 - サブスクリプションに有効なプッシュトークンがない場合、プッシュ権限プロンプトの表示を試みます。
- サブスクリプションに有効なプッシュトークンがある場合、現在のプッシュサブスクリプションステータスを
optedIn:現在のプッシュサブスクリプションステータスがsubscribedの場合はtrueを返し、それ以外の場合はfalseを返します。プッシュトークンが有効だがoptOut()が呼び出された場合、これはfalseを返します。
JavaScript
addEmail(), removeEmail()
現在のユーザーにEmailサブスクリプション(Emailアドレス)を追加または削除します。
これらのメソッドはIdentity Verificationと互換性があります。
addEmail(email)を呼び出すと:
- Emailアドレスが現在のユーザーのEmailサブスクリプションになります。
- Emailは作成または再割り当てされる場合があります。
- 同じEmailアドレスは、同じOneSignalアプリ内に複数存在することはできません。重複したEmailアドレスが見られる場合は、REST APIリクエストを確認し、必要に応じてサポートにお問い合わせください。
removeEmail(email)を呼び出すと:
- Emailサブスクリプションが現在のユーザーから削除されます。
- 現在のExternal IDがEmailサブスクリプションから削除されます。
- 新しいOneSignal IDがEmailサブスクリプションに割り当てられます。
- 他のサブスクリプション(プッシュ、SMS、他のEmail)は影響を受けません。
- 最初に
login()を呼び出してから、addEmail()を呼び出します。そうしないと、Emailが匿名ユーザーに関連付けられる可能性があります。 - 安定した検証済みのEmailアドレスを使用します。
- Emailレピュテーションのベストプラクティスに従ってください。
JavaScript
addSms(), removeSms()
現在のユーザーにSMSサブスクリプション(電話番号)を追加または削除します。電話番号はE.164形式で提供する必要があります(例:+15551234567)。
これらのメソッドはIdentity Verificationと互換性があります。
addSms(phoneNumber)を呼び出すと:
- 電話番号が現在のユーザーのSMSサブスクリプションになります。
- 番号は作成または再割り当てされる場合があります。
- 同じ電話番号は、同じOneSignalアプリ内に複数存在することはできません。重複した電話番号が見られる場合は、REST APIリクエストを確認し、必要に応じてサポートにお問い合わせください。
removeSms(phoneNumber)を呼び出すと:
- SMSサブスクリプションが現在のユーザーから削除されます。
- 現在のExternal IDがSMSサブスクリプションから削除されます。
- 新しいOneSignal IDがSMSサブスクリプションに割り当てられます。
- 他のサブスクリプション(プッシュ、Email、他のSMS)は影響を受けません。
- 最初に
login()を呼び出してから、addSms()を呼び出します。そうしないと、SMSサブスクリプションが匿名ユーザーに関連付けられる可能性があります。 - 送信前に、必ず電話番号を検証してE.164形式に正規化してください。
- SMS登録要件に従ってください。
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、プッシュトークンは反映されません。それらについては、User.PushSubscription(および以下の関連メソッド)を使用してください。
権限の変更をリッスンするには、permissionChangeイベントを使用します。
JavaScript
addEventListener() Notifications
addEventListenerで通知のライフサイクルにフックできます。最初の引数をpermissionChange、click、dismissなどのイベント名に置き換えてください(以下のサブセクションを参照)。イベントごとに複数のハンドラーを登録できます。
リッスンを停止するには、同じイベント名とハンドラー参照で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
setDefaultUrl()を同じ方法では使用しません。起動とアイコンの動作は、Safari / Appleの構成(たとえば、OneSignal Web設定のSite URL)に従います。サイトセットアップを参照してください。
setDefaultTitle()
通知に表示するデフォルトのタイトルを設定します。
JavaScript
アウトカム
アウトカムメソッドは**OneSignal.Sessionにあります。init後、他の場所と同じ遅延OneSignal**インスタンスを使用してください。
sendOutcome()
OneSignalダッシュボードで表示できるアウトカムをトリガーします。アウトカム名(string、必須)と値(number、オプション)を受け入れます。同じアウトカム名でsendOutcomeメソッドが呼び出されるたびに、アウトカムカウントが増加し、アウトカム値は渡された金額だけ増加します(含まれている場合)。詳細については、カスタムアウトカムを参照してください。
JavaScript
sendUniqueOutcome()
OneSignalダッシュボードで表示できるアウトカムをトリガーします。アウトカム名(string、必須)のみを受け入れます。sendUniqueOutcomeは、そのアウトカムのカウントをユーザーごとに1回だけ増加させます。詳細については、カスタムアウトカムを参照してください。
JavaScript