Integração do SDK do Braze

Integração do SDK do Android

Etapa 1: Atualize seu build.gradle

Em seu site build.gradle, adicione mavenCentral() à sua lista de repositórios.

1
2
3
repositories {
  mavenCentral()
}

Em seguida, adicione o Braze às suas dependências.

• somente a base
• com componentes de interface do usuário

1
2
3
4
dependencies {
    implementation 'com.braze:android-sdk-base:SDK_VERSION' // (Required) Adds dependencies for the base Braze SDK.
    implementation 'com.braze:android-sdk-location:SDK_VERSION' // (Optional) Adds dependencies for Braze location services.
}

1
2
3
4
dependencies {
    implementation 'com.braze:android-sdk-ui:SDK_VERSION' // (Required) Adds dependencies for the Braze SDK and Braze UI components. 
    implementation 'com.braze:android-sdk-location:SDK_VERSION' // (Optional) Adds dependencies for Braze location services.
}

Etapa 2: Configure seu braze.xml

Crie um arquivo braze.xml na pasta res/values de seu projeto. Se estiver em um cluster de dados específico ou tiver um endpoint personalizado pré-existente, também será necessário especificar o endpoint no arquivo braze.xml.

O conteúdo desse arquivo deve se parecer com o seguinte trecho de código. Certifique-se de substituir YOUR_APP_IDENTIFIER_API_KEY pelo identificador encontrado na página Manage Settings (Gerenciar configurações) do dashboard do Braze. Faça o registro em dashboard.braze.com para encontrar seu endereço de cluster.

1
2
3
4
5
<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string translatable="false" name="com_braze_api_key">YOUR_APP_IDENTIFIER_API_KEY</string>
  <string translatable="false" name="com_braze_custom_endpoint">YOUR_CUSTOM_ENDPOINT_OR_CLUSTER</string>
</resources>

Etapa 3: Adicionar permissões a AndroidManifest.xml

Em seguida, adicione as seguintes permissões ao seu site AndroidManifest.xml:

1
2
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Etapa 4: Ativar a inicialização com postergação (opcional)

Para usar a inicialização por postergação, é necessária a versão mínima do Braze SDK:

Etapa 4.1: Atualize seu braze.xml

A inicialização com postergação está desativada por padrão. Para ativar, use uma das seguintes opções:

• arquivo xml do braze
• em tempo de execução

1
<bool name="com_braze_enable_delayed_initialization">true</bool>

1
Braze.enableDelayedInitialization(context);

1
Braze.enableDelayedInitialization(context)

Etapa 4.2: Configurar a análise de dados push (opcional)

Quando a inicialização com postergação é ativada, as análises de dados push são enfileiradas por padrão. No entanto, você pode optar por enfileirar ou descartar explicitamente a análise de dados push.

Enfileirar explicitamente

Para enfileirar explicitamente a análise de dados push, escolha uma das seguintes opções:

• arquivo xml do braze
• em tempo de execução

1
<string name="com_braze_delayed_initialization_analytics_behavior">QUEUE</string>

1
Braze.enableDelayedInitialization(context, DelayedInitializationAnalyticsBehavior.QUEUE);

1
Braze.enableDelayedInitialization(context, DelayedInitializationAnalyticsBehavior.QUEUE)

Queda

Para descartar a análise de dados por push, escolha uma das seguintes opções:

• arquivo xml do braze
• em tempo de execução

1
<string name="com_braze_delayed_initialization_analytics_behavior">DROP</string>

1
Braze.enableDelayedInitialization(context, DelayedInitializationAnalyticsBehavior.DROP);

1
Braze.enableDelayedInitialization(context, DelayedInitializationAnalyticsBehavior.DROP)

Etapa 4.3: Inicialização manual do SDK

Após o período de postergação escolhido, use o método Braze.disableDelayedInitialization() para inicializar manualmente o SDK.

• java
• kotlin

1
Braze.disableDelayedInitialization(context);

1
Braze.disableDelayedInitialization(context)

Etapa 5: Ativar o rastreamento da sessão do usuário

Ao ativar o rastreamento da sessão do usuário, as chamadas para openSession(), closeSession(),ensureSubscribedToInAppMessageEvents()e InAppMessageManager podem ser tratadas automaticamente.

Para registrar retornos de chamada do ciclo de vida da atividade, adicione o seguinte código ao método onCreate() da sua classe Application.

• java
• kotlin

1
2
3
4
5
6
7
public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    registerActivityLifecycleCallbacks(new BrazeActivityLifecycleCallbackListener());
  }
}

1
2
3
4
5
6
class MyApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    registerActivityLifecycleCallbacks(BrazeActivityLifecycleCallbackListener())
  }
}

Teste de rastreamento de sessão

Se tiver problemas durante o teste, ative a capacitação de registro detalhado e use o logcat para detectar chamadas ausentes de openSession e closeSession em suas atividades.

1. No Braze, acesse Overview (Visão geral), selecione seu app e, no menu suspenso Display Data For (Exibir dados para ), escolha Today (Hoje).
2. Abra seu app e, em seguida, atualize o dashboard do Braze. Verifique se suas métricas aumentaram em 1.
3. Navegue pelo seu app e verifique se apenas uma sessão foi registrada no Braze.
4. Coloque o app em segundo plano por pelo menos 10 segundos e, em seguida, coloque-o em primeiro plano. Verifique se uma nova sessão foi registrada.

Configurações opcionais

Configuração do tempo de execução

Para definir suas opções do Braze no código em vez de no arquivo braze.xml, use a configuração de tempo de execução. Se houver um valor em ambos os lugares, o valor de tempo de execução será usado em seu lugar. Depois que todas as configurações necessárias forem fornecidas em tempo de execução, você poderá excluir o arquivo braze.xml.

No exemplo a seguir, um objeto builder é criado e, em seguida, passado para Braze.configure(). Note que apenas algumas das opções de tempo de execução disponíveis são mostradas - consulte nosso KDoc para obter a lista completa.

• java
• kotlin

1
2
3
4
5
6
7
8
BrazeConfig brazeConfig = new BrazeConfig.Builder()
        .setApiKey("api-key-here")
        .setCustomEndpoint("YOUR_CUSTOM_ENDPOINT_OR_CLUSTER")
        .setSessionTimeout(60)
        .setHandlePushDeepLinksAutomatically(true)
        .setGreatNetworkDataFlushInterval(10)
        .build();
Braze.configure(this, brazeConfig);

1
2
3
4
5
6
7
8
val brazeConfig = BrazeConfig.Builder()
        .setApiKey("api-key-here")
        .setCustomEndpoint("YOUR_CUSTOM_ENDPOINT_OR_CLUSTER")
        .setSessionTimeout(60)
        .setHandlePushDeepLinksAutomatically(true)
        .setGreatNetworkDataFlushInterval(10)
        .build()
Braze.configure(this, brazeConfig)

ID de publicidade do Google

O Google Advertising ID (GAID) é um ID opcional específico do usuário, anônimo, exclusivo e redefinível para publicidade, fornecido pelos serviços do Google Play. O GAID permite que os usuários redefinam seu identificador, aceitem anúncios baseados em interesses nos aplicativos do Google Play e fornece aos desenvolvedores um sistema simples e padrão para continuar a monetizar seus apps.

O ID de publicidade do Google não é coletado automaticamente pelo SDK da Braze e deve ser definido manualmente por meio do método Braze.setGoogleAdvertisingId().

• java
• kotlin

1
2
3
4
5
6
7
8
9
10
11
new Thread(new Runnable() {
  @Override
  public void run() {
    try {
      AdvertisingIdClient.Info idInfo = AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext());
      Braze.getInstance(getApplicationContext()).setGoogleAdvertisingId(idInfo.getId(), idInfo.isLimitAdTrackingEnabled());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}).start();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
suspend fun fetchAndSetAdvertisingId(
  context: Context,
  scope: CoroutineScope = GlobalScope
) {
  scope.launch(Dispatchers.IO) {
    try {
      val idInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
      Braze.getInstance(context).setGoogleAdvertisingId(
        idInfo.id,
        idInfo.isLimitAdTrackingEnabled
      )
    } catch (e: Exception) {
      e.printStackTrace()
    }
  }
}

monitoramento de localização

Para ativar a coleta de locais do Braze, defina com_braze_enable_location_collection como true em seu arquivo braze.xml:

1
<bool name="com_braze_enable_location_collection">true</bool>

Registro

Por padrão, o nível de registro do Braze Android SDK é definido como INFO. Você pode suprimir esses registros ou definir um nível de registro diferente, como VERBOSE, DEBUG ou WARN.

Capacitação de registros

Para ajudar a solucionar problemas no seu app, ou reduzir o tempo de resposta com o suporte da Braze, você vai querer ativar registros detalhados para o SDK. Quando você enviar registros detalhados para o suporte da Braze, certifique-se de que eles comecem assim que você lançar seu aplicativo e terminem muito depois que seu problema ocorrer.

Lembre-se de que registro detalhados são destinados apenas para o seu ambiente de desenvolvimento, então é interessante desativá-los antes de lançar seu app.

• aplicativo
• xml

1
BrazeLogger.setLogLevel(Log.MIN_LOG_LEVEL);

1
BrazeLogger.logLevel = Log.MIN_LOG_LEVEL

1
BrazeLogger.setLogLevel(Log.VERBOSE);

1
BrazeLogger.logLevel = Log.VERBOSE

1
<integer name="com_braze_logger_initial_log_level">MIN_LOG_LEVEL</integer>

1
<integer name="com_braze_logger_initial_log_level">2</integer>

Verificação de registros detalhados

Para verificar se seus registros estão definidos para VERBOSE, verifique se V/Braze ocorre em algum lugar nos seus registros. Se isso acontecer, os registros detalhados foram ativados com sucesso. Por exemplo:

1
2077-11-19 16:22:49.591 ? V/Braze v9.0.01 .bo.app.d3: Request started

Supressão de registros

Para suprimir todos os registros do Braze Android SDK, defina o nível de registro como BrazeLogger.SUPPRESS no método onCreate() do seu aplicativo antes de qualquer outro método.

• java
• kotlin

1
BrazeLogger.setLogLevel(BrazeLogger.SUPPRESS);

1
BrazeLogger.setLogLevel(BrazeLogger.SUPPRESS)

Múltiplas chaves de API

O caso de uso mais comum para várias chaves de API é separar chaves de API para variantes de build de depuração e release.

Para alternar facilmente entre várias chaves de API em suas compilações, recomendamos criar um arquivo braze.xml separado para cada variante de compilação relevante. Uma variante de compilação é uma combinação de tipo de compilação e sabor do produto. Por padrão, os novos projetos Android são configurados com os tipos de compilaçãodebug e release e nenhum tipo de produto.

Para cada variante de compilação relevante, crie um novo braze.xml no diretório src/<build variant name>/res/values/. Quando a variante de compilação for compilada, ela usará o nova chave de API.

1
2
3
4
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="com_braze_api_key">REPLACE_WITH_YOUR_BUILD_VARIANT_API_KEY</string>
</resources>

Mensagem exclusiva no app TalkBack

Em conformidade com as diretrizes de acessibilidade do Android, o SDK do Braze para Android oferece o Android Talkback por padrão. Para garantir que apenas o conteúdo das mensagens no app seja lido em voz alta - sem incluir outros elementos da tela, como a barra de título do app ou a navegação -, é possível ativar o modo exclusivo para o TalkBack.

Para ativar o modo exclusivo para mensagens no app:

• braze xml
• kotlin
• java

1
<bool name="com_braze_device_in_app_message_accessibility_exclusive_mode_enabled">true</bool>

1
2
3
val brazeConfigBuilder = BrazeConfig.Builder()
brazeConfigBuilder.setIsInAppMessageAccessibilityExclusiveModeEnabled(true)
Braze.configure(this, brazeConfigBuilder.build())

1
2
3
BrazeConfig.Builder brazeConfigBuilder = new BrazeConfig.Builder()
brazeConfigBuilder.setIsInAppMessageAccessibilityExclusiveModeEnabled(true);
Braze.configure(this, brazeConfigBuilder.build());

R8 e ProGuard

A configuração de redução de código é incluída automaticamente com sua integração Braze.

Os aplicativos do cliente que ofuscam o código da Braze devem armazenar arquivos de mapeamento de versão para que a Braze interprete os rastreamentos de pilha. Se você quiser manter todo o código da Braze, adicione o seguinte ao seu arquivo ProGuard:

1
2
-keep class bo.app.** { *; }
-keep class com.braze.** { *; }