Disparar mensagens no app

Aprenda a disparar mensagens no app pelo SDK da Braze.

Disparos e entrega de mensagens

As mensagens no app são disparadas quando o SDK registra um dos seguintes tipos de evento personalizado: Session Start, Push Click, Any Purchase, Specific Purchase e Custom Event (os dois últimos contam com filtros de propriedade robustos).

No início da sessão de um usuário, a Braze entrega todas as mensagens no app elegíveis para o dispositivo dele e, ao mesmo tempo, faz a pré-busca dos ativos para minimizar a latência de exibição. Se o evento-gatilho tiver mais de uma mensagem no app elegível, somente a mensagem com a maior prioridade será entregue. Para saber mais, consulte Ciclo de vida da sessão.

Nota

As mensagens no app não podem ser disparadas pela API nem por eventos de API—apenas por eventos personalizados registrados pelo SDK. Para saber mais sobre registro, consulte Registro de eventos personalizados.

Tipos de mensagens no app

A Braze envia os seguintes tipos de mensagens no app para os dispositivos dos usuários no início da sessão: inapp e templated_iam. Como usuário do dashboard, você não vê esses tipos diferentes, mas a Braze os trata de formas diferentes, dependendo da configuração e do conteúdo.

inapp (padrão)

Uma mensagem no app inapp (ou “padrão”) já vem modelada com as informações necessárias, como atributos personalizados que a Braze já conhece. Em geral, quando a mensagem no app é baixada para o dispositivo, o evento-gatilho faz com que o SDK exiba a mensagem no app inapp mesmo se o dispositivo estiver off-line ou em modo avião.

templated_iam (modelada)

Uma mensagem no app templated_iam (ou “modelada”) ainda não está modelada com as informações necessárias. A Braze precisa fazer outra solicitação para buscar essas informações antes que a mensagem possa aparecer.

As mensagens no app são entregues como mensagens no app modeladas quando a opção Reavaliar a elegibilidade da campanha antes da exibição está selecionada ou quando qualquer uma das seguintes Liquid tags existe na mensagem:

• canvas_entry_properties
• connected_content
• Variáveis de SMS, como {sms.${*}}
• catalog_items
• catalog_selection_items
• event_properties

Isso significa que, no início da sessão, o dispositivo recebe o gatilho dessa mensagem no app em vez da mensagem inteira. Quando o usuário dispara a mensagem no app, o dispositivo dele faz uma solicitação de rede para buscar a mensagem real.

Nota

A mensagem não será entregue se o dispositivo não tiver acesso à internet. A mensagem pode não ser entregue se a lógica do Liquid demorar muito para ser resolvida.

Pares de chave-valor

Ao criar uma campanha na Braze, você pode definir pares de chave-valor como extras, que o objeto de mensagem no app pode usar para enviar dados para seu app.

• 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>

Dica

Para saber mais, consulte o KDoc.

O exemplo a seguir usa uma lógica personalizada para definir a apresentação de uma mensagem no app com base nos pares de chave-valor em extras. Para ver um exemplo completo de personalização, confira nosso app de exemplo.

• 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.
  }
}

Desativação de disparos automáticos

Por padrão, as mensagens no app são disparadas automaticamente. Para desativar isso:

• web
• android
• swift
• flutter
• unity

Remova a chamada para braze.automaticallyShowInAppMessages() do seu snippet de carregamento. Depois, crie uma lógica personalizada para decidir se uma mensagem no app deve ou não ser exibida.

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

Importante

Se você chamar braze.showInAppMessage sem remover braze.automaticallyShowInAppMessages(), as mensagens poderão ser exibidas duas vezes.

Para ter um controle mais avançado sobre o momento de exibição das mensagens, incluindo adiar e restaurar mensagens disparadas, consulte nosso Tutorial: Adiar e restaurar mensagens disparadas.

1. Implemente o IInAppMessageManagerListener para definir um listener personalizado.
2. Atualize seu método beforeInAppMessageDisplayed() para retornar InAppMessageOperation.DISCARD.

Para ter um controle mais avançado sobre o momento de exibição das mensagens, incluindo exibir mais tarde e recolocar na fila, consulte nossa página Personalização de mensagens.

1. Implemente o delegate BrazeInAppMessageUIDelegate no seu app. Para um passo a passo completo, consulte o Tutorial: UI de mensagens no app.
2. Atualize seu método delegate inAppMessage(_:displayChoiceForMessage:) para retornar .discard.

Para ter um controle mais avançado sobre o momento de exibição das mensagens, incluindo adiar e restaurar mensagens disparadas, consulte nosso Tutorial: Adiar e restaurar mensagens disparadas.

1. Verifique se você está usando o inicializador de integração automática, que fica ativado por padrão nas versões 2.2.0 e posteriores.
2. Defina a operação padrão de mensagens no app como DISCARD adicionando a seguinte linha ao seu arquivo braze.xml.

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

• android
• ios

No Android, desmarque Exibir automaticamente mensagens no app no editor de configuração da Braze. Como alternativa, você pode definir com_braze_inapp_show_inapp_messages_automatically como false no braze.xml do seu projeto Unity.

A operação inicial de exibição de mensagens no app pode ser definida na configuração da Braze usando a opção “In App Message Manager Initial Display Operation”.

No iOS, defina os listeners de objetos de jogo no editor de configuração da Braze e confira se a opção Braze exibe mensagens no app não está selecionada.

A operação inicial de exibição de mensagens no app pode ser definida na configuração da Braze usando a opção “In App Message Manager Initial Display Operation”.

Encadeamento de duas mensagens no app em uma sessão

Você pode disparar uma mensagem no app no início da sessão e, depois, disparar uma segunda mensagem no app quando o usuário pressionar um botão na primeira. Para isso, registre um evento personalizado para o clique no botão que vai disparar a segunda mensagem. O gatilho da segunda mensagem já precisa estar no dispositivo, ou seja, o usuário já deve ser elegível para a segunda mensagem. Além disso, o gatilho precisa ocorrer no lado do dispositivo, porque o SDK da Braze não detecta alterações de atributos personalizados que ocorrem nos servidores da Braze. Para exibir várias mensagens no app em sequência rápida, você precisa alterar o intervalo padrão de 30 segundos entre os gatilhos de mensagens no app. Para ver a configuração específica de cada plataforma, consulte Substituição do limite de frequência padrão.

Substituição do limite de frequência padrão

Por padrão, o SDK limita as mensagens no app disparadas a uma a cada 30 segundos. Para substituir esse comportamento, adicione a seguinte propriedade ao seu arquivo de configuração antes de inicializar a instância da Braze. Esse valor passa a ser o novo limite de frequência, em segundos.

Em apps de produção, não defina um valor menor que 10 segundos. Assim, os usuários não recebem uma mensagem no app atrás da outra. Para testes e fluxos de apps de exemplo, 5 segundos é uma configuração comum.

Você pode definir esse intervalo como 0 para testes. No entanto, um intervalo de 0 segundo não força a exibição de várias mensagens no app ao mesmo tempo. Se uma mensagem no app já estiver visível, outra mensagem disparada só aparece depois que a mensagem atual for descartada.

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

Disparar mensagens manualmente

Por padrão, as mensagens no app são disparadas automaticamente quando o SDK registra um evento personalizado. Além disso, você pode disparar mensagens manualmente usando os métodos a seguir.

Usando um evento do lado do servidor

• web
• android
• swift

No momento, o SDK Web da Braze não oferece suporte ao disparo manual de mensagens usando eventos do lado do servidor.

Para disparar uma mensagem no app usando um evento enviado pelo servidor, envie uma notificação por push silenciosa ao dispositivo. Assim, um retorno de chamada de push personalizado pode registrar um evento baseado no SDK. Esse evento vai disparar a mensagem no app exibida ao usuário.

Etapa 1: Crie um retorno de chamada de push para receber o push silencioso

Registre seu retorno de chamada de push personalizado para escutar uma notificação por push silenciosa específica. Para saber mais, consulte Configuração de notificações por push.

Dois eventos serão registrados para que a mensagem no app seja entregue: um pelo servidor e outro dentro do seu retorno de chamada de push personalizado. Para garantir que o mesmo evento não seja duplicado, o evento registrado dentro do retorno de chamada de push deve seguir uma convenção de nomenclatura genérica, por exemplo, “evento-gatilho de mensagem no app”, e não usar o mesmo nome do evento enviado pelo servidor. Caso contrário, a segmentação e os dados de usuários podem ser afetados por eventos duplicados registrados para uma única ação do usuário.

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

Etapa 2: Crie uma Campaign de push

Crie uma Campaign de push silencioso disparada pelo evento enviado pelo servidor.

A Campaign de push deve incluir extras de pares chave-valor indicando que ela é enviada para registrar um evento personalizado do SDK. Esse evento será usado para disparar a mensagem no app.

O código de exemplo do retorno de chamada de push mostrado anteriormente reconhece os pares chave-valor e registra o evento personalizado do SDK apropriado.

Se quiser anexar propriedades ao seu evento “evento-gatilho de mensagem no app”, basta passá-las nos pares chave-valor da carga útil do push. Neste exemplo, incluímos o nome da Campaign da mensagem no app subsequente. Seu retorno de chamada de push personalizado pode então passar o valor como parâmetro da propriedade do evento ao registrar o evento personalizado.

Etapa 3: Crie uma Campaign de mensagem no app

Crie sua Campaign de mensagem no app visível ao usuário no dashboard da Braze. Essa Campaign deve ter entrega baseada em ação e ser disparada pelo evento personalizado registrado dentro do seu retorno de chamada de push personalizado.

No exemplo a seguir, a mensagem no app específica a ser disparada foi configurada enviando a propriedade do evento como parte do push silencioso inicial.

Se um evento enviado pelo servidor for registrado enquanto o app não estiver em primeiro plano, o evento será registrado, mas a mensagem no app não será exibida. Se quiser que o evento seja postergado até que o aplicativo esteja em primeiro plano, inclua uma verificação no seu receptor de push personalizado para descartar ou postergar o evento até que o app entre em primeiro plano.

Etapa 1: Trate o push silencioso e os pares chave-valor

Implemente a função a seguir e chame-a dentro do método 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"]}];
  }
};

Quando o push silencioso for recebido, um evento “evento-gatilho de mensagem no app” registrado pelo SDK será gravado no perfil do usuário.

Importante

Como uma mensagem push é usada para registrar um evento personalizado do SDK, a Braze precisará armazenar um token por push para cada usuário para viabilizar esta solução. Para usuários iOS, a Braze só armazena um token a partir do momento em que o usuário recebe o prompt de push do sistema operacional. Antes disso, o usuário não poderá ser alcançado por push, e a solução anterior não será possível.

Etapa 2: Crie uma Campaign de push silencioso

Crie uma Campaign de push silencioso disparada pelo evento enviado pelo servidor.

A Campaign de push deve incluir extras de pares chave-valor, indicando que ela é enviada para registrar um evento personalizado do SDK. Esse evento será usado para disparar a mensagem no app.

O código dentro do método application(_:didReceiveRemoteNotification:fetchCompletionHandler:) verifica a chave IS_SERVER_EVENT e registra um evento personalizado do SDK se ela estiver presente.

Você pode alterar o nome ou as propriedades do evento enviando o valor desejado nos extras de pares chave-valor da carga útil do push. Ao registrar o evento personalizado, esses extras podem ser usados como parâmetro do nome do evento ou como uma propriedade do evento.

Etapa 3: Crie uma Campaign de mensagem no app

Crie sua Campaign de mensagem no app visível ao usuário no dashboard da Braze. Essa Campaign deve ter entrega baseada em ação e ser disparada pelo evento personalizado registrado dentro do método application(_:didReceiveRemoteNotification:fetchCompletionHandler:).

No exemplo a seguir, a mensagem no app específica a ser disparada foi configurada enviando a propriedade do evento como parte do push silencioso inicial.

Nota

Essas mensagens no app só serão disparadas se o push silencioso for recebido enquanto o aplicativo estiver em primeiro plano.

Exibir uma mensagem predefinida

Para exibir manualmente uma mensagem no app predefinida, use o seguinte método:

• web
• android
• swift

1

BrazeInAppMessageManager.getInstance().addInAppMessage(inAppMessage);

1

BrazeInAppMessageManager.getInstance().addInAppMessage(inAppMessage)

1

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

Exibir uma mensagem em tempo real

Você também pode criar e exibir mensagens no app locais em tempo real, usando as mesmas opções de personalização disponíveis no dashboard. Para isso:

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

Importante

Não exiba mensagens no app enquanto o teclado virtual estiver aberto na tela, pois a renderização não é definida nessa situação.

Chame manualmente o método present(message:) no seu inAppMessagePresenter. Por exemplo:

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

Nota

Ao criar sua própria mensagem no app, você abre mão de qualquer rastreamento de análise de dados e precisará registrar manualmente cliques e impressões usando o seu message.context.

Para exibir a próxima mensagem da pilha, use o método DisplayNextInAppMessage(). As mensagens serão salvas nessa pilha se DISPLAY_LATER ou BrazeUnityInAppMessageDisplayActionType.IAM_DISPLAY_LATER for escolhido como ação de exibição da mensagem no app.

1

Appboy.AppboyBinding.DisplayNextInAppMessage();

Causas de atrasos em mensagens no app

Se você receber uma Campaign de mensagem no app alguns segundos depois do início da sessão, o atraso pode ter sido causado por:

• Um atraso no disparo da Campaign
• Personalizações
• O registro do evento-gatilho acontecer mais tarde do que o esperado (como com um templated_iam)

Mensagens de intenção de saída para a web

As mensagens de intenção de saída são mensagens no app não disruptivas, usadas para comunicar informações importantes aos visitantes antes que eles saiam do seu site.

Para configurar gatilhos para esses tipos de mensagem no Web SDK, implemente uma biblioteca de intenção de saída no seu site (como a biblioteca de código aberto do ouibounce). Depois, use o código a seguir para registrar 'exit intent' como um evento personalizado na Braze. Assim, suas futuras Campaigns de mensagens no app poderão usar esse tipo de mensagem como gatilho de evento personalizado.

1
2
3

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