コンテンツにスキップ

イベント購読

バナー、Content Cards、フィーチャーフラグにおけるBraze SDKイベント購読の仕組みについて説明します。この記事では、各イベントがいつ発火し、インテグレーションで何をすべきかを解説します。

前提条件

イベント購読を使用するには、以下の最小SDKバージョンが必要です。

イベント購読について

各チャネルにはイベント購読メソッドがあります。コールバックを1つ登録すると、キャッシュの再生、リフレッシュの完了、分析イベント、エラーなど、そのチャネルで何かが起こるたびにSDKがコールバックを呼び出します。各イベントは、受信したイベントの種類を通知します。

イベント購読メソッドは、以前の更新購読メソッドに代わるものです。以前のメソッドは現在のデータのみを配信していました。イベントメソッドでは、データが変更された理由、分析イベントがログに記録されて送信されたタイミング、リクエストが失敗したタイミングも通知されます。

チャネル イベント購読メソッド 置き換え対象 ガイド
バナー subscribeToBannersEvents subscribeToBannersUpdates バナープレースメントの管理
Content Cards subscribeToContentCardsEvents subscribeToContentCardsUpdates Content Cardsの作成
フィーチャーフラグ subscribeToFeatureFlagsEvents subscribeToFeatureFlagsUpdates フィーチャーフラグの作成
チャネル イベント購読メソッド 置き換え対象 ガイド
バナー braze.banners.subscribeToEvents(_:) subscribeToUpdates(_:) バナープレースメントの管理
Content Cards braze.contentCards.subscribeToEvents(_:) subscribeToUpdates(_:) Content Cardsの作成
フィーチャーフラグ braze.featureFlags.subscribeToEvents(_:) subscribeToUpdates(_:) フィーチャーフラグの作成

完全なAPIリファレンスについては、BrazeKitドキュメントを参照してください。

各チャネルにはeventsStreamプロパティもあり、同じイベントをAsyncStreamとして配信します。Objective-Cアプリでは、同じチャネルオブジェクトのsubscribeToEvents:メソッドを使用します。

チャネル イベント購読メソッド イベントクラス 置き換え対象 ガイド
バナー subscribeToBannersEvents BannersEvent subscribeToBannersUpdates バナープレースメントの管理
Content Cards subscribeToContentCardsEvents ContentCardsEvent subscribeToContentCardsUpdates Content Cardsの作成
フィーチャーフラグ subscribeToFeatureFlagsEvents FeatureFlagsEvent subscribeToFeatureFlagsUpdates フィーチャーフラグの作成

完全なAPIリファレンスについては、Braze Android SDK KDocを参照してください。

プラットフォームごとの名前

この記事では、イベントタイプ、更新理由、リトライ状態、分析アクション、エラー理由についてWebの名前を使用しています。SwiftとAndroidも同じ概念を使用しますが、各プラットフォームの規約に従った名前になっています。

Web Swift Android
CACHE_REPLAY cacheReplay CacheReplay
CACHE_LOAD cacheLoad CacheLoad
DATA_UPDATED dataUpdated DataUpdated
IMPRESSION impressionEvent ImpressionEvent
CLICK clickEvent ClickEvent
DISMISS dismissEvent DismissEvent
ERROR error ErrorEvent
AUTO_SERVER_REFRESH autoServerRefresh AUTO_SERVER_REFRESH
SDK_WILL_RETRY sdkWillRetry SDK_WILL_RETRY
ENQUEUED enqueued ENQUEUED
SERVER_ERROR .common(.serverError) Common(ErrorReason.ServerError)
FEATURE_DISABLED .featureDisabled FeatureDisabled

残りの更新理由、リトライ状態、分析アクション、エラー理由も同じパターンに従います。Swiftでは、更新理由の型はBraze.ChannelUpdateReasonです。Androidでは、BannersUpdateReasonのように各チャネルに独自の更新理由型があります。

イベントの配信方法

SDKは次の順序でイベントを配信します。

  1. 購読時： SDKは、キャッシュされたデータを含むCACHE_REPLAYイベントですぐにコールバックを呼び出します。チャネルが無効になっている場合は、代わりにFEATURE_DISABLED理由付きのERRORイベントを送信します。いずれの場合も、購読はアクティブなままです。
  2. キャッシュが変更されたとき： サーバーリフレッシュなしでキャッシュが変更された場合はCACHE_LOADイベントを、リフレッシュが完了した場合やデータをローカルで変更した場合はDATA_UPDATEDイベントを送信します。
  3. あなたまたはSDKが分析をログに記録したとき： SDKはENQUEUEDアクション付きのIMPRESSION、CLICK、またはDISMISSイベントを送信し、Brazeがそれを受け入れた後にFLUSHEDアクションで再度送信します。
  4. 何かが失敗したとき： SDKはERRORイベントを送信します。

コールバックは唯一の引数としてイベントを受け取ります。イベントタイプでswitchを使って各種イベントを処理してください。Webでは、コールバックがスローしたエラーをSDKがログに記録しつつ、他の購読者にはイベントを配信し続けます。




import * as braze from "@braze/web-sdk";

// Register the subscription
const subscriptionId = braze.subscribeToBannersEvents((event) => {
  switch (event.type) {
    case braze.ChannelEventType.CACHE_REPLAY:
      // Sent once, right away, with the cached data
      break;
    case braze.ChannelEventType.DATA_UPDATED:
      // A refresh finished or the data changed locally
      break;
    case braze.ChannelEventType.ERROR:
      // A request or analytics operation failed
      break;
  }
});

// Remove the subscription when you no longer need it
braze.removeSubscription(subscriptionId);






// Register the subscription and keep a strong reference to it
let cancellable = AppDelegate.braze?.banners.subscribeToEvents { event in
  switch event {
  case .cacheReplay(let cacheSnapshot):
    // Sent once, right away, with the cached data
    break
  case .dataUpdated(let cacheSnapshot, let reason):
    // A refresh finished or the data changed locally
    break
  case .error(let reason, let retryState):
    // A request or analytics operation failed
    break
  default:
    break
  }
}

// Remove the subscription when you no longer need it
cancellable?.cancel()






// Register the subscription
val subscriber = IEventSubscriber<BannersEvent> { event ->
  when (event) {
    is BannersEvent.CacheReplay -> {
      // Sent once, right away, with the cached data
    }
    is BannersEvent.DataUpdated -> {
      // A refresh finished or the data changed locally
    }
    is BannersEvent.ErrorEvent -> {
      // A request or analytics operation failed
    }
    else -> Unit
  }
}
Braze.getInstance(context).subscribeToBannersEvents(subscriber)

// Remove the subscription when you no longer need it
Braze.getInstance(context).removeSingleSubscription(subscriber, BannersEvent::class.java)

キャッシュスナップショット

CACHE_REPLAY、CACHE_LOAD、DATA_UPDATEDイベントには、現在のユーザーに対してSDKがキャッシュしたデータを含むcacheSnapshotプロパティがあります。

チャネル cacheSnapshot内のデータ
バナー banners：各プレースメントIDとそのキャッシュされたバナーのマップ。バナーのないプレースメントはマップに含まれません。
Content Cards Web：contentCards（ContentCardsオブジェクト）。contentCards.cardsでカードのリストを取得します。SwiftおよびAndroid：cards（カードのリスト）。
フィーチャーフラグ featureFlags：フィーチャーフラグのリスト。

すべてのスナップショットにはlastSyncAtも含まれており、現在のユーザーの最後の同期成功時刻をUnixタイムスタンプ（秒単位）で示します。同期が成功していない場合は0、チャネルが無効な場合はnull（Swiftではnil）になります。

更新購読からの移行

更新購読メソッドはまだ動作しますが、非推奨です。各購読を移行するには、前提条件を満たした上で以下を行ってください。

  1. 非推奨メソッドをそのチャネルのイベント購読メソッドに置き換えます。イベント購読についてのテーブルに各ペアが記載されています。
  2. コールバックを更新します。以前のコールバックは現在のデータのみを受け取っていました。新しいコールバックはイベントを受け取るため、イベントタイプを確認してください。CACHE_REPLAY、CACHE_LOAD、DATA_UPDATEDイベントの場合は、cacheSnapshotからデータを読み取り、再レンダリングします。
  3. （オプション）ERRORイベントを処理して、リフレッシュや分析操作が失敗したタイミングを確認します。Androidでは、これらがsubscribeToBannersErrorsを置き換えます。詳細については、エラー理由を参照してください。
  4. 購読を解除します。Androidでは、レガシーの…UpdatedEventクラスではなく、新しいイベントクラス（BannersEvent、ContentCardsEvent、FeatureFlagsEvent）をremoveSingleSubscriptionに渡します。

移行前後のコードについては、イベント購読についてのテーブルにある各チャネルのガイドを参照してください。

イベントタイプ

すべてのイベントは、このテーブルのイベントタイプのいずれかです。Webでは、イベントにChannelEventType値のいずれかを持つtypeプロパティがあります。SwiftとAndroidでは、各イベントタイプが独自のcaseまたはクラスになっています。すべてのチャネルがすべてのイベントタイプを送信するわけではありません。

イベントタイプ 送信元 発火タイミング 対処方法
CACHE_REPLAY バナー、Content Cards、フィーチャーフラグ 購読するたびに1回、すぐに送信されます。現在のキャッシュを含むcacheSnapshotがあります。 ネットワークを待たずにUIにコンテンツを表示するために、キャッシュされたデータをレンダリングします。
CACHE_LOAD バナー、Content Cards、フィーチャーフラグ サーバーリフレッシュなしでキャッシュが変更された場合に送信されます。ユーザーが変更されたとき、SDKデータを消去したとき、チャネルがオフになったときに発生します。Webでは、Content Cardsはサービスワーカーからカードが到着したときにも送信します。SwiftとAndroidでは、ネットワーク同期前にSDKがローカルストレージからキャッシュを読み込んだときにも発火します。新しいキャッシュを含むcacheSnapshotがあります。 スナップショットから再レンダリングします。ユーザー変更後やチャネルがオフになった場合、スナップショットは空になる可能性があるため、前のユーザーのコンテンツをクリアしてください。
DATA_UPDATED バナー、Content Cards、フィーチャーフラグ キャッシュが変更された場合に送信されます。SDKは、何も変更がなくても完了したリフレッシュごとに、またカードの非表示などのローカル変更に対しても送信します。cacheSnapshotとreasonがあります。 スナップショットから再レンダリングします。reasonを確認して、変更がリフレッシュによるものか独自のアクションによるものかを判断してください。
IMPRESSION バナー、Content Cards、フィーチャーフラグ インプレッションがログに記録されたときに送信されます。actionとログに記録されたアイテム（banner、card、またはflag）があります。 オプション。独自の分析でインプレッションをミラーリングするために使用します。
CLICK バナー、Content Cards クリックがログに記録されたときに送信されます。actionとクリックされたアイテム（bannerまたはcard）があります。バナーのクリックには、IDを持つボタンからのクリックの場合、ボタンIDも含まれます。 オプション。独自の分析でクリックをミラーリングするために使用します。
DISMISS バナー、Content Cards 非表示がログに記録されたときに送信されます。actionと非表示にされたアイテム（bannerまたはcard）があります。 オプション。DISMISSは分析イベントなので、非表示に続くDATA_UPDATEDイベントからUIを更新してください。
ERROR バナー、Content Cards、フィーチャーフラグ リクエストまたは操作が失敗したときに送信されます。reasonとretryStateがあります。Webでは、rateLimitedUntilが含まれる場合があります。SwiftとAndroidでは、レートリミット時刻はRATE_LIMITED理由の一部です。 リトライするかどうかを判断するためにretryStateを確認し、原因を特定するためにreasonを確認してください。

更新理由

DATA_UPDATEDイベントには、ChannelUpdateReason値のいずれかを持つreasonが含まれます。

値 意味 対処方法
AUTO_SERVER_REFRESH SDKが開始したリフレッシュ（新しいセッションでのリフレッシュやそのリトライなど）が完了しました。 スナップショットから再レンダリングします。
MANUAL_SERVER_REFRESH リクエストしたリフレッシュ（リトライを含む）が完了しました。例としては、WebおよびAndroidのrequestBannersRefresh()、requestContentCardsRefresh()、refreshFeatureFlags()、またはSwiftのrequestRefresh()があります。 スナップショットから再レンダリングします。リフレッシュをリクエストしたときに表示したローディングインジケーターを非表示にするために使用します。
CLIENT_ACTION サーバーレスポンスではなく、バナーやContent Cardsの非表示などのローカルアクションによってキャッシュが変更されました。 ローディングやエラー状態を表示せずにスナップショットから再レンダリングします。フィーチャーフラグは現在この理由を送信しませんが、将来送信される場合に備えて処理してください。

リトライ状態

ERRORイベントには、RetryState値のいずれかを持つretryStateが含まれます。SDKが失敗した操作をリトライするかどうか、およびあなたが何をすべきかを示します。

値 意味 対処方法
SDK_WILL_RETRY SDKが自動的にリトライしているか、レートリミットが解除されるのを待ってからリトライします。 キャッシュされたコンテンツを引き続き表示してください。別のリフレッシュをリクエストしないでください。リトライが完了すると、SDKがDATA_UPDATEDまたは別のERRORイベントを送信します。
INTEGRATOR_MAY_RETRY SDKはリトライを停止しました。 キャッシュされたコンテンツを引き続き表示してください。遅延後にリフレッシュメソッドを再度呼び出すことができます。イベントにrateLimitedUntilが含まれている場合は、その時刻まで待ってください。
DO_NOT_RETRY この操作に対して失敗は最終的なものです。リトライしても改善されません。 リトライしないでください。代わりに、APIキーやワークスペースの設定などの原因を修正してください。理由がFEATURE_DISABLEDの場合は、そのチャネルのコンテンツの表示を停止してください。

分析アクション

IMPRESSION、CLICK、DISMISSイベントには、AnalyticsAction値のいずれかを持つactionが含まれます。各分析イベントは2回送信されます。最初にENQUEUED、次にFLUSHEDです。

値 意味 対処方法
ENQUEUED SDKが分析イベントをローカルに保存しました。Brazeはまだ受信していません。 UIまたは独自のロギングをすぐに更新するために使用します。
FLUSHED SDKが分析イベントをBrazeにフラッシュし、ネットワークレスポンスが成功しました。 イベントがフラッシュされたことの確認として使用します。

エラー理由

ERRORイベントには、ChannelErrorReason値のいずれかを持つreasonが含まれます。すべての理由がすべてのチャネルに適用されます。

値 意味 対処方法
SERVER_ERROR Brazeがサーバー側のエラーを返しました（HTTP 5xxレスポンスや、使用可能なRetry-AfterヘッダーのないHTTP 429レスポンスなど）、またはリクエストがBrazeに到達しませんでした。 retryStateに従ってください。SDKが最初にリトライし、その後INTEGRATOR_MAY_RETRYを報告します。キャッシュされたコンテンツを引き続き表示してください。
CLIENT_ERROR Brazeがリクエストを拒否しました（429以外のHTTP 4xxレスポンスやSDK認証エラーなど）。Webでは、フィーチャーフラグの場合、SDKがインプレッションをローカルに保存できなかったことを意味する場合もあります。 retryStateに従ってください。HTTP 4xxレスポンスはすぐにDO_NOT_RETRYになります。SDK認証エラーの場合、SDKが最初にリトライしてからDO_NOT_RETRYを報告します。APIキー、SDKエンドポイント、およびSDK認証の設定を確認してください。
RATE_LIMITED リクエストがレートリミットされました。イベントには、別の試行が成功し得る最も早い時刻を示すrateLimitedUntil（日付）が含まれます。 retryStateがSDK_WILL_RETRYの場合は待ってください。INTEGRATOR_MAY_RETRYの場合は、再度リフレッシュする前にrateLimitedUntilまで待ってください。それより前にリクエストすると再び失敗します。詳細については、レートリミットを参照してください。
SDK_DISABLED SDKがローカルで無効になっているため、ネットワークリクエストを行いません。 最終的なものとして扱い、リトライしないでください。
INVALID_SERVER_DATA Brazeが返したデータをSDKが解釈できませんでした。 リトライしないでください。retryStateはDO_NOT_RETRYです。キャッシュされたコンテンツを引き続き表示し、問題が続く場合はBrazeサポートに連絡してください。
FEATURE_DISABLED このワークスペースでチャネルが無効になっています。SDKはBrazeから最初の設定を受信するまで、チャネルを無効として報告します。 チャネルのUIを非表示にしてください。これはコンテンツの空リストとは異なります。購読を維持してください。Brazeがチャネルを有効にすると、SDKがリフレッシュしてDATA_UPDATEDイベントを送信します。

Brazeカスタマーエンゲージメントプラットフォームのドキュメント。

リソース
法的情報
会社情報
© 2026 Braze, Inc. All rights reserved.
Braze ステータスの確認
New Stuff!