コンテンツにスキップ

アプリ内メッセージをトリガーする

Braze SDKを通じてアプリ内メッセージをトリガーする方法を説明します。

メッセージのトリガーと配信

アプリ内メッセージは、SDKが次のいずれかのカスタムイベントタイプをログに記録したときにトリガーされます: Session Start、Push Click、Any Purchase、Specific Purchase、Custom Event(最後の2つには強力なプロパティフィルターが含まれます)。

ユーザーのセッション開始時に、Braze は対象となるすべてのアプリ内メッセージをユーザーのデバイスに配信し、同時にアセットをプリフェッチして表示の遅延を最小限に抑えます。トリガーイベントに対象となるアプリ内メッセージが複数ある場合は、優先度が最も高いメッセージのみが配信されます。詳細については、セッションのライフサイクルを参照してください。

アプリ内メッセージの種類

Brazeは、セッション開始時に次の種類のアプリ内メッセージをユーザーデバイスに送信します: inapp と templated_iam。ダッシュボードユーザーにはこれらの種類の違いは表示されませんが、Brazeは設定やコンテンツに応じてそれぞれを異なる方法で処理します。

inapp (標準)

inapp (または「標準」) のアプリ内メッセージは、Brazeがすでに把握しているカスタム属性など、必要な情報がすでにテンプレート化されています。通常、アプリ内メッセージがデバイスにダウンロードされると、デバイスがオフラインや機内モードの場合でも、トリガーイベントによってSDKが inapp のアプリ内メッセージを表示します。

templated_iam (テンプレート化)

templated_iam (または「テンプレート化」) のアプリ内メッセージは、まだ必要な情報でテンプレート化されていません。メッセージを表示する前に、Brazeは情報を取得するために追加のリクエストを行う必要があります。

表示前にキャンペーンの資格を再評価するが選択されている場合、またはメッセージに次のいずれかのLiquidタグが含まれている場合、アプリ内メッセージはテンプレート化されたアプリ内メッセージとして配信されます。

  • canvas_entry_properties
  • connected_content
  • {sms.${*}} などのSMS変数
  • catalog_items
  • catalog_selection_items
  • event_properties

つまり、セッション開始時にデバイスが受け取るのはメッセージ全体ではなく、そのアプリ内メッセージのトリガーです。ユーザーがアプリ内メッセージをトリガーすると、ユーザーのデバイスがネットワークリクエストを行い、実際のメッセージを取得します。

キーと値のペア

Brazeでキャンペーンを作成するときに、キーと値のペアをextrasとして設定できます。アプリ内メッセージングオブジェクトは、これを使用してアプリにデータを送信できます。

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

braze.subscribeToInAppMessage(function(inAppMessage) {
  // control group messages should always be "shown"
  // this will log an impression and not show a visible message
  if (inAppMessage instanceof braze.ControlMessage) {
    return braze.showInAppMessage(inAppMessage);
  }


  if (inAppMessage instanceof braze.InAppMessage) {
    const extras = inAppMessage.extras;
    if (extras) {
      for (const key in extras) {
        console.log("key: " + key + ", value: " + extras[key]);
      }
    }
  }
  braze.showInAppMessage(inAppMessage);
});
Map<String, String> getExtras()
extras: Map<String, String>

次の例では、カスタムロジックを使用して、extras内のキーと値のペアに基づいてアプリ内メッセージの表示方法を設定しています。完全なカスタマイズ例については、サンプルアプリを参照してください。

let customization = message.extras["custom-display"] as? String
if customization == "colorful-slideup" {
  // Perform your custom logic.
}
if ([message.extras[@"custom-display"] isKindOfClass:[NSString class]]) {
  NSString *customization = message.extras[@"custom-display"];
  if ([customization isEqualToString:@"colorful-slideup"]) {
    // Perform your custom logic.
  }
}

自動トリガーの無効化

デフォルトでは、アプリ内メッセージは自動的にトリガーされます。これを無効にするには、次の手順に従います。

読み込みスニペット内の braze.automaticallyShowInAppMessages() の呼び出しを削除し、アプリ内メッセージを表示するかどうかを判断するカスタムロジックを作成します。

braze.subscribeToInAppMessage(function(inAppMessage) {
  // control group messages should always be "shown"
  // this will log an impression and not show a visible message

  if (inAppMessage.isControl) { // v4.5.0+, otherwise use  `inAppMessage instanceof braze.ControlMessage`
     return braze.showInAppMessage(inAppMessage);
  }

  // Display the in-app message. You could defer display here by pushing this message to code within your own application.
  // If you don't want to use the display capabilities in Braze, you could alternatively pass the in-app message to your own display code here.

  if ( should_show_the_message_according_to_your_custom_logic ) {
      braze.showInAppMessage(inAppMessage);
  } else {
      // do nothing
  }
});

トリガーメッセージの延期や復元など、メッセージのタイミングをより高度にコントロールする方法については、チュートリアル:トリガーメッセージの延期と復元を参照してください。

  1. IInAppMessageManagerListener を実装して、カスタムリスナーを設定します。
  2. beforeInAppMessageDisplayed() メソッドを更新して、InAppMessageOperation.DISCARD を返すようにします。

後で表示する方法や再度キューに追加する方法など、メッセージのタイミングをより高度にコントロールする方法については、メッセージのカスタマイズページを参照してください。

  1. アプリに BrazeInAppMessageUIDelegate デリゲートを実装します。詳しい手順については、Tutorial: In-App Message UI を参照してください。
  2. inAppMessage(_:displayChoiceForMessage:) デリゲートメソッドを更新して、.discard を返すようにします。

トリガーメッセージの延期や復元など、メッセージのタイミングをより高度にコントロールする方法については、チュートリアル:トリガーメッセージの延期と復元を参照してください。

  1. 自動統合イニシャライザーを使用していることを確認します。これは、バージョン 2.2.0 以降ではデフォルトで有効になっています。
  2. braze.xml ファイルに次の行を追加して、アプリ内メッセージ操作のデフォルトを DISCARD に設定します。
     <string name="com_braze_flutter_automatic_integration_iam_operation">DISCARD</string>
    

Android の場合は、Braze 設定エディターで Automatically Display In-App Messages の選択を解除します。または、Unity プロジェクトの braze.xml で com_braze_inapp_show_inapp_messages_automatically を false に設定することもできます。

アプリ内メッセージの初期表示操作は、Braze 設定の「In App Message Manager Initial Display Operation」で設定できます。

iOS の場合は、Braze 設定エディターでゲームオブジェクトリスナーを設定し、Braze Displays In-App Messages が選択されていないことを確認します。

アプリ内メッセージの初期表示操作は、Braze 設定の「In App Message Manager Initial Display Operation」で設定できます。

1回のセッションで2つのアプリ内メッセージを連続して表示する

セッション開始時にアプリ内メッセージをトリガーし、最初のメッセージのボタンが押された後に2つ目のアプリ内メッセージをトリガーできます。これを行うには、2つ目のメッセージをトリガーするボタンクリックに対してカスタムイベントを記録します。2つ目のメッセージのトリガーは、すでにデバイス上に存在している必要があり (ユーザーがすでに2つ目のメッセージの対象となっている必要があります)、デバイス側で発生する必要があります (Braze SDKは、Brazeサーバー上で発生したカスタム属性の変更を検出しません)。複数のアプリ内メッセージを短い間隔で続けて表示するには、アプリ内メッセージのトリガー間のデフォルトの30秒のクールダウンを変更する必要があります。プラットフォーム固有の設定については、デフォルトのレート制限の上書きを参照してください。

デフォルトのレート制限のオーバーライド

デフォルトでは、SDKはトリガーされたアプリ内メッセージのレートを30秒に1回に制限しています。これをオーバーライドするには、Brazeインスタンスを初期化する前に、構成ファイルに次のプロパティを追加します。この値は、新しいレート制限 (秒単位) として使用されます。

本番環境のアプリでは、ユーザーが連続したアプリ内メッセージに圧倒されないよう、この値を10秒未満に設定しないでください。テストやサンプルアプリのフローでは、5秒が一般的な設定です。

テストのためにこの間隔を 0 に設定することもできます。ただし、0 秒の間隔を設定しても、複数のアプリ内メッセージが同時に強制的に表示されるわけではありません。すでに1つのアプリ内メッセージが表示されている場合、現在のメッセージが閉じられるまで、別のトリガーメッセージは表示されません。

// Sets the minimum time interval between triggered in-app messages to 5 seconds instead of the default 30
braze.initialize('YOUR-API-KEY', { minimumIntervalBetweenTriggerActionsInSeconds: 5 })
<integer name="com_braze_trigger_action_minimum_time_interval_seconds">5</integer>
let configuration = Braze.Configuration(
  apiKey: "YOUR-APP-IDENTIFIER-API-KEY",
  endpoint: "YOUR-BRAZE-ENDPOINT"
)
// Sets the minimum trigger time interval to 5 seconds
configuration.triggerMinimumTimeInterval = 5
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze
BRZConfiguration *configuration =
    [[BRZConfiguration alloc] initWithApiKey:@"<BRAZE_API_KEY>"
                                    endpoint:@"<BRAZE_ENDPOINT>"];
// Sets the minimum trigger time interval to 5 seconds
configuration.triggerMinimumTimeInterval = 5;
Braze *braze = [BrazePlugin initBraze:configuration];
AppDelegate.braze = braze;

メッセージを手動でトリガーする

デフォルトでは、アプリ内メッセージは SDKがカスタムイベントをログに記録したときに自動的にトリガーされます。これに加えて、以下の方法でメッセージを手動でトリガーすることもできます。

サーバー側イベントを使用する

現時点では、Web Braze SDKはサーバー側イベントによるメッセージの手動トリガーをサポートしていません。

サーバーから送信されるイベントでアプリ内メッセージをトリガーするには、デバイスにサイレントプッシュ通知を送信します。これにより、カスタムプッシュコールバックが SDK ベースのイベントをログに記録できます。このイベントが、ユーザーに表示されるアプリ内メッセージをトリガーします。

ステップ1: サイレントプッシュを受信するプッシュコールバックを作成する

特定のサイレントプッシュ通知をリッスンするカスタムプッシュコールバックを登録します。詳しくは、プッシュ通知の設定を参照してください。

アプリ内メッセージが配信されるまでに、2つのイベントがログに記録されます。1つはサーバーによるもの、もう1つはカスタムプッシュコールバック内からのものです。同じイベントが重複しないように、プッシュコールバック内から記録するイベントには、サーバーから送信されるイベントと同じ名前ではなく、「in-app message trigger event」のような汎用的な命名規則を使用してください。これを行わないと、1回のユーザーアクションに対して重複したイベントが記録され、セグメンテーションやユーザーデータに影響が出る可能性があります。

Braze.getInstance(context).subscribeToPushNotificationEvents(event -> {
  final Bundle kvps = event.getNotificationPayload().getBrazeExtras();
  if (kvps.containsKey("IS_SERVER_EVENT")) {
    BrazeProperties eventProperties = new BrazeProperties();

    // The campaign name is a string extra that clients can include in the push
    String campaignName = kvps.getString("CAMPAIGN_NAME");
    eventProperties.addProperty("campaign_name", campaignName);
    Braze.getInstance(context).logCustomEvent("IAM Trigger", eventProperties);
  }
});
Braze.getInstance(applicationContext).subscribeToPushNotificationEvents { event ->
    val kvps = event.notificationPayload.brazeExtras
    if (kvps.containsKey("IS_SERVER_EVENT")) {
        val eventProperties = BrazeProperties()

        // The campaign name is a string extra that clients can include in the push
        val campaignName = kvps.getString("CAMPAIGN_NAME")
        eventProperties.addProperty("campaign_name", campaignName)
        Braze.getInstance(applicationContext).logCustomEvent("IAM Trigger", eventProperties)
    }
}

ステップ2: プッシュキャンペーンを作成する

サーバーから送信されるイベントによってトリガーされるサイレントプッシュキャンペーンを作成します。

server_event カスタムイベントをトリガーとするアクションベースの配信が設定された、サイレントプッシュキャンペーンの配信ステップ。

プッシュキャンペーンには、このプッシュキャンペーンが SDK カスタムイベントをログに記録するために送信されることを示す、キーと値のペアのエクストラを含める必要があります。このイベントがアプリ内メッセージのトリガーに使用されます。

2組のキーと値のペア: IS_SERVER_EVENT が "true" に、CAMPAIGN_NAME が "example campaign name" に設定されている。

前述のプッシュコールバックのサンプルコードは、これらのキーと値のペアを認識し、適切な SDK カスタムイベントをログに記録します。

「in-app message trigger」イベントにイベントプロパティを付加したい場合は、プッシュペイロードのキーと値のペアでそれらを渡すことで実現できます。この例では、後続のアプリ内メッセージのキャンペーン名が含まれています。カスタムプッシュコールバックは、カスタムイベントをログに記録する際に、その値をイベントプロパティのパラメーターとして渡すことができます。

ステップ3: アプリ内メッセージキャンペーンを作成する

Braze ダッシュボードで、ユーザーに表示されるアプリ内メッセージキャンペーンを作成します。このキャンペーンはアクションベースの配信とし、カスタムプッシュコールバック内からログに記録されたカスタムイベントによってトリガーされるようにします。

次の例では、最初のサイレントプッシュの一部としてイベントプロパティを送信することで、トリガーする特定のアプリ内メッセージを設定しています。

"campaign_name" が "IAM campaign name example." と等しい場合にアプリ内メッセージがトリガーされる、アクションベース配信のキャンペーン。

アプリがフォアグラウンドにないときにサーバー送信イベントが記録された場合、イベントはログに記録されますが、アプリ内メッセージは表示されません。アプリケーションがフォアグラウンドになるまでイベントを遅延させたい場合は、アプリがフォアグラウンドに入るまでイベントを破棄または遅延させるチェックをカスタムプッシュレシーバーに含める必要があります。

ステップ1: サイレントプッシュとキーと値のペアを処理する

次の関数を実装し、application(_:didReceiveRemoteNotification:fetchCompletionHandler:): メソッド内で呼び出します。

func handleExtras(userInfo: [AnyHashable : Any]) {
  print("A push was received")
  if userInfo != nil && (userInfo["IS_SERVER_EVENT"] as? String) != nil && (userInfo["CAMPAIGN_NAME"] as? String) != nil {
    AppDelegate.braze?.logCustomEvent("IAM Trigger", properties: ["campaign_name": userInfo["CAMPAIGN_NAME"]])
  }
}
- (void)handleExtrasFromPush:(NSDictionary *)userInfo {
  NSLog(@"A push was received.");
  if (userInfo !=nil && userInfo[@"IS_SERVER_EVENT"] !=nil && userInfo[@"CAMPAIGN_NAME"]!=nil) {
    [AppDelegate.braze logCustomEvent:@"IAM Trigger" properties:@{@"campaign_name": userInfo[@"CAMPAIGN_NAME"]}];
  }
};

サイレントプッシュを受信すると、SDK で記録されたイベント「in-app message trigger」がユーザープロファイルに対してログに記録されます。

ステップ2: サイレントプッシュキャンペーンを作成する

サーバーから送信されるイベントによってトリガーされるサイレントプッシュキャンペーンを作成します。

ユーザープロファイルにカスタムイベント "server_event" があるユーザーに配信される、アクションベース配信のアプリ内メッセージキャンペーン。

プッシュキャンペーンには、このプッシュキャンペーンが SDK カスタムイベントをログに記録するために送信されることを示す、キーと値のペアのエクストラを含める必要があります。このイベントがアプリ内メッセージのトリガーに使用されます。

2組のキーと値のペアを持つアクションベース配信のアプリ内メッセージキャンペーン。"CAMPAIGN_NAME" が "In-app message name example" に、"IS_SERVER_EVENT" が "true" に設定されている。

application(_:didReceiveRemoteNotification:fetchCompletionHandler:) メソッド内のコードはキー IS_SERVER_EVENT をチェックし、これが存在する場合に SDK カスタムイベントをログに記録します。

プッシュペイロードのキーと値のペアのエクストラ内で目的の値を送信することで、イベント名またはイベントプロパティのいずれかを変更できます。カスタムイベントをログに記録する際、これらのエクストラをイベント名のパラメーター、またはイベントプロパティとして使用できます。

ステップ3: アプリ内メッセージキャンペーンを作成する

Braze ダッシュボードで、ユーザーに表示されるアプリ内メッセージキャンペーンを作成します。このキャンペーンはアクションベースの配信とし、application(_:didReceiveRemoteNotification:fetchCompletionHandler:) メソッド内からログに記録されたカスタムイベントによってトリガーされるようにします。

次の例では、最初のサイレントプッシュの一部としてイベントプロパティを送信することで、トリガーする特定のアプリ内メッセージを設定しています。

カスタムイベント "In-app message trigger" を実行し、"campaign_name" が "IAM キャンペーン Name Example" と等しいユーザーに配信される、アクションベース配信のアプリ内メッセージキャンペーン。

事前定義されたメッセージを表示する

事前定義されたアプリ内メッセージを手動で表示するには、次のメソッドを使用します。

Web SDK では、braze.showInAppMessage(inAppMessage) を使用して任意のアプリ内メッセージを表示します。詳細と例については、リアルタイムでメッセージを表示するを参照してください。

BrazeInAppMessageManager.getInstance().addInAppMessage(inAppMessage);
BrazeInAppMessageManager.getInstance().addInAppMessage(inAppMessage)
AppDelegate.braze?.inAppMessagePresenter?.present(message: inAppMessage)

リアルタイムでメッセージを表示する

ダッシュボードで利用できるものと同じカスタマイズオプションを使用して、ローカルのアプリ内メッセージをリアルタイムで作成して表示することもできます。手順は以下のとおりです。

  // Displays a slideup type in-app message.
  var message = new braze.SlideUpMessage("Welcome to Braze! This is an in-app message.");
  message.slideFrom = braze.InAppMessage.SlideFrom.TOP;
  braze.showInAppMessage(message);
// Initializes a new slideup type in-app message and specifies its message.
InAppMessageSlideup inAppMessage = new InAppMessageSlideup();
inAppMessage.setMessage("Welcome to Braze! This is a slideup in-app message.");
// Initializes a new slideup type in-app message and specifies its message.
val inAppMessage = InAppMessageSlideup()
inAppMessage.message = "Welcome to Braze! This is a slideup in-app message."

inAppMessagePresenter で present(message:) メソッドを手動で呼び出します。例:

let customInAppMessage = Braze.InAppMessage.slideup(
  .init(message: "YOUR_CUSTOM_SLIDEUP_MESSAGE", slideFrom: .bottom, themes: .defaults)
)
AppDelegate.braze?.inAppMessagePresenter?.present(message: customInAppMessage)
BRZInAppMessageRaw *customInAppMessage = [[BRZInAppMessageRaw alloc] init];
customInAppMessage.type = BRZInAppMessageRawTypeSlideup;
customInAppMessage.message = @"YOUR_CUSTOM_SLIDEUP_MESSAGE";
customInAppMessage.slideFrom = BRZInAppMessageRawSlideFromBottom;
customInAppMessage.themes = @{
  @"light": BRZInAppMessageRawTheme.defaultLight,
  @"dark": BRZInAppMessageRawTheme.defaultDark
};
[AppDelegate.braze.inAppMessagePresenter presentMessage:customInAppMessage];

スタック内の次のメッセージを表示するには、DisplayNextInAppMessage() メソッドを使用します。アプリ内メッセージの表示アクションとして DISPLAY_LATER または BrazeUnityInAppMessageDisplayActionType.IAM_DISPLAY_LATER が選択されている場合、メッセージはこのスタックに保存されます。

Appboy.AppboyBinding.DisplayNextInAppMessage();

アプリ内メッセージの遅延の原因

セッション開始の数秒後にアプリ内メッセージキャンペーンを受信した場合、遅延の原因として次のことが考えられます。

  • キャンペーンのトリガーの遅延
  • カスタマイズ
  • トリガーイベントの記録が想定より遅れた (templated_iam の場合など)

Web向け離脱インテントメッセージ

離脱インテントメッセージは、訪問者がWeb サイトを離れる前に重要な情報を伝えるための、ユーザー体験を妨げないアプリ内メッセージです。

Web SDKでこれらのメッセージタイプのトリガーを設定するには、Web サイトに離脱インテントライブラリ(ouibounceのオープンソースライブラリなど)を実装します。次に、以下のコードを使用して、'exit intent' をBrazeのカスタムイベントとして記録します。これで、今後のアプリ内メッセージキャンペーンで、このメッセージタイプをカスタムイベントトリガーとして使用できるようになります。

  var _ouibounce = ouibounce(false, {
    callback: function() { braze.logCustomEvent('exit intent'); }
  });
New Stuff!