Déclencher des messages in-app

Découvrez comment déclencher des messages in-app via le SDK Braze.

Déclencheurs et livraison des messages

Les messages in-app se déclenchent lorsque le SDK enregistre l’un des types d’événements personnalisés suivants : Session Start, Push Click, Any Purchase, Specific Purchase et Custom Event (ces deux derniers proposant des filtres de propriétés avancés).

Au début de la session d’un utilisateur, Braze distribue tous les messages in-app éligibles sur son appareil, tout en préchargeant les ressources afin de réduire au maximum la latence d’affichage. Si l’événement déclencheur compte plusieurs messages in-app éligibles, seul le message ayant la priorité la plus élevée est distribué. Pour en savoir plus, consultez la section Cycle de vie des sessions.

Remarque

Les messages in-app ne peuvent pas être déclenchés via l’API ou par des événements API, uniquement par des événements personnalisés enregistrés par le SDK. Pour en savoir plus sur la journalisation, consultez la section Enregistrer des événements personnalisés.

Types de messages in-app

Braze envoie deux types de messages in-app aux appareils des utilisateurs au démarrage de la session : inapp et templated_iam. En tant qu’utilisateur du tableau de bord, vous ne voyez pas ces différents types, mais Braze les traite différemment selon la configuration et le contenu.

inapp (standard)

Un message in-app inapp (ou « standard ») est déjà modélisé avec les informations nécessaires, comme les attributs personnalisés que Braze connaît déjà. En général, une fois le message in-app téléchargé sur l’appareil, l’événement déclencheur amène le SDK à afficher le message in-app inapp, même lorsque l’appareil est hors ligne ou en mode avion.

templated_iam (modélisé)

Un message in-app templated_iam (ou « modélisé ») n’est pas encore modélisé avec les informations nécessaires. Braze doit effectuer une requête supplémentaire pour récupérer ces informations avant que le message puisse s’afficher.

Les messages in-app sont distribués en tant que messages in-app modélisés lorsque l’option Réévaluer l’éligibilité à la campagne avant l’affichage est sélectionnée ou si l’une des étiquettes Liquid suivantes figure dans le message :

• canvas_entry_properties
• connected_content
• Variables SMS telles que {sms.${*}}
• catalog_items
• catalog_selection_items
• event_properties

Ainsi, au démarrage de la session, l’appareil reçoit le déclencheur de ce message in-app au lieu du message complet. Lorsque l’utilisateur déclenche le message in-app, son appareil envoie une requête réseau pour récupérer le message réel.

Remarque

Le message ne sera pas distribué si l’appareil n’a pas accès à Internet. Il peut également ne pas être distribué si la logique Liquid met trop de temps à se résoudre.

Paires clé-valeur

Lorsque vous créez une campagne dans Braze, vous pouvez définir des paires clé-valeur en tant qu’extras. L’objet de message in-app peut ensuite les utiliser pour envoyer des données à votre application.

• web
• android
• swift

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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);
});

• java
• kotlin

1

Map<String, String> getExtras()

1

extras: Map<String, String>

Conseil

Pour plus d’informations, consultez la KDoc.

L’exemple suivant utilise une logique personnalisée pour définir la présentation d’un message in-app en fonction de ses paires clé-valeur dans extras. Pour un exemple complet de personnalisation, consultez notre application d’exemple.

• swift
• objective-c

1
2
3
4

let customization = message.extras["custom-display"] as? String
if customization == "colorful-slideup" {
  // Perform your custom logic.
}

1
2
3
4
5
6

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

Désactiver les déclencheurs automatiques

Par défaut, les messages in-app sont déclenchés automatiquement. Pour désactiver ce comportement :

• web
• android
• swift
• flutter
• unity

Supprimez l’appel à braze.automaticallyShowInAppMessages() dans votre extrait de code de chargement, puis créez une logique personnalisée pour gérer l’affichage ou non d’un message in-app.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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
  }
});

Important

Si vous appelez braze.showInAppMessage sans supprimer braze.automaticallyShowInAppMessages(), les messages risquent de s’afficher deux fois.

Pour un contrôle plus avancé du moment d’affichage des messages, notamment pour différer et restaurer les messages déclenchés, consultez notre tutoriel : Différer et restaurer les messages déclenchés.

1. Implémentez le IInAppMessageManagerListener pour définir un écouteur personnalisé.
2. Modifiez votre méthode beforeInAppMessageDisplayed() pour qu’elle renvoie InAppMessageOperation.DISCARD.

Pour un contrôle plus avancé du moment d’affichage des messages, notamment pour les afficher plus tard ou les remettre en file d’attente, consultez notre page Personnaliser les messages.

1. Implémentez le délégué BrazeInAppMessageUIDelegate dans votre application. Pour une présentation complète, consultez le tutoriel : Interface utilisateur des messages in-app.
2. Modifiez votre méthode de délégué inAppMessage(_:displayChoiceForMessage:) pour qu’elle renvoie .discard.

Pour un contrôle plus avancé du moment d’affichage des messages, notamment pour différer et restaurer les messages déclenchés, consultez notre tutoriel : Différer et restaurer les messages déclenchés.

1. Vérifiez que vous utilisez l’initialisateur d’intégration automatique, activé par défaut à partir de la version 2.2.0.
2. Définissez l’opération par défaut des messages in-app sur DISCARD en ajoutant la ligne suivante à votre fichier braze.xml.

   
   1
   
    <string name="com_braze_flutter_automatic_integration_iam_operation">DISCARD</string>
   
   

• android
• ios

Pour Android, désélectionnez Afficher automatiquement les messages in-app dans l’éditeur de configuration de Braze. Vous pouvez également définir com_braze_inapp_show_inapp_messages_automatically sur false dans le fichier braze.xml de votre projet Unity.

L’opération d’affichage initiale des messages in-app peut être définie dans la configuration de Braze à l’aide de l’option « In App Message Manager Initial Display Operation ».

Pour iOS, définissez des écouteurs d’objets de jeu dans l’éditeur de configuration de Braze et assurez-vous que l’option Braze affiche les messages in-app n’est pas sélectionnée.

L’opération d’affichage initiale des messages in-app peut être définie dans la configuration de Braze à l’aide de l’option « In App Message Manager Initial Display Operation ».

Enchaîner deux messages in-app au cours d’une même session

Vous pouvez déclencher un message in-app au début de la session, puis déclencher un second message in-app lorsqu’un bouton est actionné dans le premier. Pour ce faire, enregistrez un événement personnalisé pour le clic sur le bouton qui déclenchera le second message. Le déclencheur du second message doit déjà se trouver sur l’appareil (l’utilisateur doit déjà être éligible au second message) et se produire côté appareil (le SDK de Braze ne détecte pas les modifications d’attributs personnalisés effectuées sur les serveurs de Braze). Le délai de 30 secondes appliqué par défaut entre les déclencheurs de messages in-app doit être modifié pour afficher plusieurs messages in-app en succession rapide. Pour la configuration propre à chaque plateforme, consultez Remplacer la limite de débit par défaut.

Remplacer la limite de débit par défaut

Par défaut, le SDK limite l’affichage des messages in-app déclenchés à un toutes les 30 secondes. Pour modifier ce comportement, ajoutez la propriété suivante à votre fichier de configuration avant l’initialisation de l’instance Braze. Cette valeur, exprimée en secondes, devient la nouvelle limite de débit.

Pour les applications en production, ne définissez pas une valeur inférieure à 10 secondes afin d’éviter de submerger les utilisateurs de messages in-app successifs. Pour les tests et les parcours d’applications d’exemple, une valeur de 5 secondes est couramment utilisée.

Vous pouvez définir cet intervalle sur 0 pour vos tests. Toutefois, un intervalle de 0 seconde ne force pas l’affichage simultané de plusieurs messages in-app. Si un message in-app est déjà visible, aucun autre message déclenché ne s’affiche tant que le message en cours n’a pas été fermé.

• web
• android
• swift

1
2

// 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 })

1

<integer name="com_braze_trigger_action_minimum_time_interval_seconds">5</integer>

1
2
3
4
5
6
7
8

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

1
2
3
4
5
6
7

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;

Déclencher manuellement des messages

Par défaut, les messages in-app se déclenchent automatiquement lorsque le SDK enregistre un événement personnalisé. Vous pouvez également déclencher des messages manuellement à l’aide des méthodes suivantes.

Utiliser un événement côté serveur

• web
• android
• swift

Pour le moment, le SDK Braze pour le Web ne permet pas de déclencher manuellement des messages à l’aide d’événements côté serveur.

Pour déclencher un message in-app à partir d’un événement envoyé par le serveur, envoyez une notification push silencieuse à l’appareil. Un rappel push personnalisé peut alors enregistrer un événement via le SDK, qui déclenchera à son tour le message in-app visible par l’utilisateur.

Étape 1 : Créer un rappel push pour recevoir la notification push silencieuse

Enregistrez votre rappel push personnalisé pour qu’il écoute une notification push silencieuse spécifique. Pour en savoir plus, consultez la section Configuration des notifications push.

Deux événements sont enregistrés pour que le message in-app soit distribué : l’un par le serveur, l’autre depuis votre rappel push personnalisé. Pour éviter de dupliquer le même événement, l’événement enregistré dans votre rappel push doit suivre une convention de nommage générique, par exemple « événement déclencheur de message in-app », et ne pas porter le même nom que l’événement envoyé par le serveur. Sinon, la segmentation et les données utilisateur risquent d’être faussées par des événements en double enregistrés pour une seule action de l’utilisateur.

• java
• kotlin

1
2
3
4
5
6
7
8
9
10
11

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);
  }
});

1
2
3
4
5
6
7
8
9
10
11

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)
    }
}

Étape 2 : Créer une Campaign push

Créez une Campaign push silencieuse déclenchée par l’événement envoyé par le serveur.

La Campaign push doit inclure des paires clé-valeur supplémentaires indiquant qu’elle est envoyée pour enregistrer un événement personnalisé via le SDK. Cet événement servira à déclencher le message in-app.

L’exemple de code de rappel push présenté plus haut reconnaît ces paires clé-valeur et enregistre l’événement personnalisé approprié via le SDK.

Si vous souhaitez associer des propriétés d’événement à votre événement « déclencheur de message in-app », transmettez-les dans les paires clé-valeur du payload push. Dans cet exemple, le nom de la Campaign du message in-app qui suit a été inclus. Votre rappel push personnalisé peut ensuite transmettre cette valeur comme paramètre de la propriété d’événement lors de l’enregistrement de l’événement personnalisé.

Étape 3 : Créer une Campaign de message in-app

Créez votre Campaign de message in-app visible par l’utilisateur dans le tableau de bord de Braze. Cette Campaign doit utiliser une livraison par événement et être déclenchée par l’événement personnalisé enregistré dans votre rappel push personnalisé.

Dans l’exemple suivant, le message in-app à déclencher a été configuré en envoyant la propriété d’événement dans la notification push silencieuse initiale.

Si un événement envoyé par le serveur est enregistré alors que l’application n’est pas au premier plan, l’événement est bien enregistré, mais le message in-app ne s’affiche pas. Si vous souhaitez retarder l’événement jusqu’à ce que l’application passe au premier plan, ajoutez une vérification dans votre récepteur push personnalisé pour ignorer ou retarder l’événement jusqu’à ce que l’application soit au premier plan.

Étape 1 : Gérer la notification push silencieuse et les paires clé-valeur

Implémentez la fonction suivante et appelez-la dans la méthode application(_:didReceiveRemoteNotification:fetchCompletionHandler:): :

• swift
• objective-c

1
2
3
4
5
6

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"]])
  }
}

1
2
3
4
5
6

- (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"]}];
  }
};

À la réception de la notification push silencieuse, un événement « déclencheur de message in-app » est enregistré via le SDK dans le profil utilisateur.

Important

Comme une notification push sert à enregistrer un événement personnalisé via le SDK, Braze doit stocker un jeton push pour chaque utilisateur afin que cette solution fonctionne. Pour les utilisateurs iOS, Braze ne stocke un jeton qu’à partir du moment où l’invite de notification push du système d’exploitation a été présentée à l’utilisateur. Avant cela, l’utilisateur ne peut pas être contacté par notification push et la solution décrite ci-dessus n’est pas possible.

Étape 2 : Créer une Campaign push silencieuse

Créez une Campaign push silencieuse déclenchée par l’événement envoyé par le serveur.

La Campaign push doit inclure des paires clé-valeur supplémentaires indiquant qu’elle est envoyée pour enregistrer un événement personnalisé via le SDK. Cet événement servira à déclencher le message in-app.

Le code de la méthode application(_:didReceiveRemoteNotification:fetchCompletionHandler:) vérifie la présence de la clé IS_SERVER_EVENT et, si elle est présente, enregistre un événement personnalisé via le SDK.

Vous pouvez modifier le nom ou les propriétés de l’événement en envoyant la valeur souhaitée dans les paires clé-valeur supplémentaires du payload push. Lors de l’enregistrement de l’événement personnalisé, ces valeurs supplémentaires peuvent servir de paramètre pour le nom de l’événement ou pour une propriété d’événement.

Étape 3 : Créer une Campaign de message in-app

Créez votre Campaign de message in-app visible par l’utilisateur dans le tableau de bord de Braze. Cette Campaign doit utiliser une livraison par événement et être déclenchée par l’événement personnalisé enregistré dans la méthode application(_:didReceiveRemoteNotification:fetchCompletionHandler:).

Dans l’exemple suivant, le message in-app à déclencher a été configuré en envoyant la propriété d’événement dans la notification push silencieuse initiale.

Remarque

Notez que ces messages in-app ne se déclenchent que si la notification push silencieuse est reçue pendant que l’application est au premier plan.

Afficher un message prédéfini

Pour afficher manuellement un message in-app prédéfini, utilisez la méthode suivante :

• web
• android
• swift

1

BrazeInAppMessageManager.getInstance().addInAppMessage(inAppMessage);

1

BrazeInAppMessageManager.getInstance().addInAppMessage(inAppMessage)

1

AppDelegate.braze?.inAppMessagePresenter?.present(message: inAppMessage)

Afficher un message en temps réel

Vous pouvez également créer et afficher des messages in-app locaux en temps réel, avec les mêmes options de personnalisation que celles disponibles dans le tableau de bord. Pour ce faire :

• web
• android
• swift
• unity

1
2
3
4

  // 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);

• java
• kotlin

1
2
3

// 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.");

1
2
3

// 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."

Important

N’affichez pas de messages in-app lorsque le clavier virtuel est affiché à l’écran, car le rendu n’est pas défini dans ce cas.

Appelez manuellement la méthode present(message:) sur votre inAppMessagePresenter. Par exemple :

• swift
• objective-c

1
2
3
4

let customInAppMessage = Braze.InAppMessage.slideup(
  .init(message: "YOUR_CUSTOM_SLIDEUP_MESSAGE", slideFrom: .bottom, themes: .defaults)
)
AppDelegate.braze?.inAppMessagePresenter?.present(message: customInAppMessage)

1
2
3
4
5
6
7
8
9

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];

Remarque

Lorsque vous créez votre propre message in-app, vous renoncez au suivi analytique automatique et devez gérer manuellement l’enregistrement des clics et des impressions à l’aide de votre message.context.

Pour afficher le message suivant dans la pile, utilisez la méthode DisplayNextInAppMessage(). Les messages sont enregistrés dans cette pile si DISPLAY_LATER ou BrazeUnityInAppMessageDisplayActionType.IAM_DISPLAY_LATER est choisi comme action d’affichage du message in-app.

1

Appboy.AppboyBinding.DisplayNextInAppMessage();

Causes des retards d’affichage des messages in-app

Si vous recevez une campagne de messages in-app quelques secondes après le début de la session, ce délai peut s’expliquer par :

• Un retard du déclencheur de la campagne
• Des personnalisations
• Un enregistrement de l’événement déclencheur plus tardif que prévu (par exemple avec un templated_iam)

Messages d’intention de sortie pour le Web

Les messages d’intention de sortie sont des messages in-app non intrusifs qui permettent de communiquer des informations importantes aux visiteurs avant qu’ils ne quittent votre site web.

Pour configurer des déclencheurs pour ces types de messages dans le SDK Web, implémentez une bibliothèque d’intention de sortie sur votre site web (comme la bibliothèque open source de ouibounce), puis utilisez le code suivant pour enregistrer 'exit intent' en tant qu’événement personnalisé dans Braze. Vos futures Campaigns de messages in-app pourront ainsi utiliser ce type de message comme déclencheur d’événement personnalisé.

1
2
3

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