Rastrear sessões

Saiba como rastrear sessões por meio do SDK da Braze.

Nota

Para wrapper SDKs não listados, use o método nativo relevante do Android ou Swift.

Sobre o ciclo de vida da sessão

Uma sessão refere-se ao período de tempo em que o SDK do Braze rastreia a atividade do usuário em seu app após ser iniciado. Você também pode forçar uma nova sessão chamando o método changeUser().

• web
• android
• swift

Por padrão, uma sessão começa quando você chama braze.openSession() pela primeira vez. A sessão permanecerá ativa por até 30 minutos de inatividade (a menos que você altere o tempo limite padrão da sessão ou o usuário feche o app).

Nota

Se você configurou o callback do ciclo de vida da atividade para Android, o Braze chamará automaticamente openSession() e closeSession() para cada atividade em seu app.

Por padrão, uma sessão começa quando openSession() é chamado pela primeira vez. Se seu app for para o segundo plano e depois retornar ao primeiro plano, o SDK verificará se mais de 10 segundos se passaram desde que a sessão começou (a menos que você altere o tempo limite padrão da sessão). Se sim, uma nova sessão começará. Lembre-se de que, se o usuário fechar seu app enquanto ele estiver em segundo plano, os dados da sessão podem não ser enviados ao Braze até que eles reabram o app.

Chamar closeSession() não encerrará imediatamente a sessão. Em vez disso, encerrará a sessão após 10 segundos se openSession() não for chamado novamente pelo usuário iniciando outra atividade.

Por padrão, uma sessão começa quando você chama Braze.init(configuration:). Isso ocorre quando a notificação UIApplicationWillEnterForegroundNotification é acionada, significando que o app entrou no primeiro plano.

Se seu app for para o segundo plano, UIApplicationDidEnterBackgroundNotification é acionado. O app não permanece em uma sessão ativa enquanto está em segundo plano. Quando seu app retorna ao primeiro plano, o SDK compara o tempo decorrido desde o início da sessão com o tempo limite da sessão (a menos que você altere o tempo limite padrão da sessão). Se o tempo desde o início da sessão exceder o período de tempo limite, uma nova sessão começa.

Definindo inatividade

Entender como a inatividade é definida e medida é fundamental para gerenciar ciclos de vida de sessão de forma eficaz no Web SDK. Inatividade se refere a um período durante o qual o Braze Web SDK não detecta nenhum evento rastreado do usuário.

Como a inatividade é medida

O Web SDK rastreia a inatividade com base em eventos rastreados pelo SDK. O SDK mantém um temporizador interno que é reiniciado cada vez que um evento rastreado é enviado. Se nenhum evento rastreado pelo SDK ocorrer dentro do período de tempo limite configurado, a sessão é considerada inativa e encerrada.

Para saber mais sobre como o ciclo de vida da sessão é implementado no Web SDK, consulte o código-fonte de gerenciamento de sessões no repositório do Braze Web SDK no GitHub.

O que conta como atividade por padrão:

• Abrir ou atualizar o app web
• Interagir com elementos de interface orientados pela Braze (como In-App Messages ou Content Cards)
• Chamar métodos do SDK que enviam eventos rastreados (como eventos personalizados ou atualizações de atributos de usuário)

O que não conta como atividade por padrão:

• Alternar para uma guia diferente do navegador
• Minimizar a janela do navegador
• Eventos de foco ou desfoque do navegador
• Rolagem ou movimentos do mouse na página

Nota

O Web SDK não rastreia automaticamente alterações de visibilidade do navegador, troca de guias ou foco do usuário. No entanto, você pode rastrear essas interações no nível do navegador implementando ouvintes de eventos personalizados usando a API de visibilidade de página do navegador e enviando eventos personalizados para a Braze. Para um exemplo de implementação, consulte Rastreamento de inatividade personalizada.

Configuração do tempo limite da sessão

Por padrão, o Web SDK considera uma sessão inativa após 30 minutos sem nenhum evento rastreado. Você pode personalizar esse limite ao inicializar o SDK usando o parâmetro sessionTimeoutInSeconds. Para detalhes sobre como configurar esse parâmetro, incluindo exemplos de código, consulte Alterando o tempo limite padrão da sessão.

Exemplo: entendendo cenários de inatividade

Considere o seguinte cenário:

1. Um usuário abre seu website, e o SDK inicia uma sessão chamando braze.openSession().
2. O usuário alterna para uma guia diferente do navegador para visualizar outro website por 30 minutos.
3. Durante esse tempo, nenhum evento rastreado pelo SDK ocorre no seu website.
4. Após 30 minutos de inatividade, a sessão é encerrada automaticamente.
5. Quando o usuário retorna à guia do seu website e dispara um evento do SDK (como visualizar uma página ou interagir com conteúdo), uma nova sessão é iniciada.

Rastreamento de inatividade personalizada

Se você precisa rastrear inatividade com base na visibilidade do navegador ou na troca de guias, implemente ouvintes de eventos personalizados no seu código JavaScript. Use eventos do navegador como visibilitychange para detectar quando os usuários saem da sua página, e envie manualmente eventos personalizados para a Braze ou chame braze.openSession() quando apropriado.

1
2
3
4
5
6
7
8
9
10
11
// Example: Track when user switches away from tab
document.addEventListener('visibilitychange', function() {
  if (document.hidden) {
    // User switched away - optionally log a custom event
    braze.logCustomEvent('tab_hidden');
  } else {
    // User returned - optionally start a new session and/or log an event
    // braze.openSession();
    braze.logCustomEvent('tab_visible');
  }
});

Para saber mais sobre como registrar eventos personalizados, consulte Registrar eventos personalizados. Para detalhes sobre o ciclo de vida da sessão e configuração do tempo limite, consulte Alterando o tempo limite padrão da sessão.

Assinando atualizações de sessão

Etapa 1: Assinar atualizações

Para assinar atualizações de sessão, use o método subscribeToSessionUpdates().

• web
• android
• swift
• react native

1
2
3
4
5
6
7
8
Braze.getInstance(this).subscribeToSessionUpdates(new IEventSubscriber<SessionStateChangedEvent>() {
  @Override
  public void trigger(SessionStateChangedEvent message) {
    if (message.getEventType() == SessionStateChangedEvent.ChangeType.SESSION_STARTED) {
      // A session has just been started
    }
  }
});

1
2
3
4
5
Braze.getInstance(this).subscribeToSessionUpdates { message ->
  if (message.eventType == SessionStateChangedEvent.ChangeType.SESSION_STARTED) {
    // A session has just been started
  }
}

1
2
3
4
5
6
7
8
9
10
11
// This subscription is maintained through a Braze cancellable, which will observe changes until the subscription is cancelled.
// You must keep a strong reference to the cancellable to keep the subscription active.
// The subscription is canceled either when the cancellable is deinitialized or when you call its `.cancel()` method.
let cancellable = AppDelegate.braze?.subscribeToSessionUpdates { event in
  switch event {
  case .started(let id):
    print("Session \(id) has started")
  case .ended(let id):
    print("Session \(id) has ended")
  }
}

1
2
3
4
5
6
7
8
for await event in braze.sessionUpdatesStream {
  switch event {
  case .started(let id):
    print("Session \(id) has started")
  case .ended(let id):
    print("Session \(id) has ended")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// This subscription is maintained through a Braze cancellable, which will observe changes until the subscription is cancelled.
// You must keep a strong reference to the cancellable to keep the subscription active.
// The subscription is canceled either when the cancellable is deinitialized or when you call its `.cancel()` method.
BRZCancellable *cancellable = [AppDelegate.braze subscribeToSessionUpdates:^(BRZSessionEvent * _Nonnull event) {
  switch (event.state) {
    case BRZSessionStateStarted:
      NSLog(@"Session %@ has started", event.sessionId);
      break;
    case BRZSessionStateEnded:
      NSLog(@"Session %@ has ended", event.sessionId);
      break;
    default:
      break;
  }
}];

Etapa 2: Testar o rastreamento de sessão (opcional)

Para testar o rastreamento de sessão, inicie uma sessão no seu dispositivo e abra o dashboard da Braze e busque pelo usuário relevante. No perfil do usuário, selecione Sessions Overview. Se as métricas forem atualizadas conforme esperado, o rastreamento de sessão está funcionando corretamente.

Nota

Os detalhes específicos do app só são exibidos para usuários que usaram mais de um app.

Alterando o tempo limite padrão da sessão

Você pode alterar a duração do tempo que passa antes que uma sessão expire automaticamente.

• web
• android
• swift
• react native

1
2
// Sets the session timeout to 15 minutes instead of the default 30
braze.initialize('YOUR-API-KEY-HERE', { sessionTimeoutInSeconds: 900 });

1
2
<!-- Sets the session timeout to 60 seconds. -->
<integer name="com_braze_session_timeout">60</integer>

1
2
3
4
5
6
7
8
// Sets the session timeout to 60 seconds
let configuration = Braze.Configuration(
  apiKey: "<BRAZE_API_KEY>",
  endpoint: "<BRAZE_ENDPOINT>"
)
configuration.sessionTimeout = 60;
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

1
2
3
4
5
6
7
// Sets the session timeout to 60 seconds
BRZConfiguration *configuration =
  [[BRZConfiguration alloc] initWithApiKey:brazeApiKey
                                  endpoint:brazeEndpoint];
configuration.sessionTimeout = 60;
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;

Nota

Se você definir um tempo limite de sessão, todas as semânticas de sessão serão automaticamente estendidas para o tempo limite definido.

Solução de problemas

O perfil de usuário tem 0 sessões

Um perfil de usuário pode ter 0 sessões se o usuário foi criado fora do SDK:

• Criado pela REST API: Se um usuário é criado através do endpoint /users/track com um app_id na solicitação, o perfil aparece associado àquele app, mas não tem dados de sessão porque o SDK nunca foi inicializado para esse usuário.
• Criado por importação CSV: Se um usuário é importado via CSV sem valores para os campos de primeira ou última sessão, o perfil existe com 0 sessões.

Alguns usuários não estão registrando sessões

Como as sessões são rastreadas somente após a inicialização do SDK, usuários que não acionam a inicialização do SDK não registram nenhuma sessão. Isso geralmente acontece quando seu app utiliza lógica condicional antes de inicializar o SDK, como adiar a inicialização por trás de um fluxo de login, solicitação de consentimento ou Feature Flag. Para orientações de implementação, consulte Inicialização atrasada. Nesses casos, qualquer usuário que não satisfaça a condição nunca inicia uma sessão.

Se alguns usuários estão registrando sessões e outros não, verifique o seguinte:

• Verifique sua lógica de inicialização. Confirme que o SDK é inicializado para todos os usuários e pontos de entrada do app, não apenas para alguns.
• Procure por mudanças recentes no app. Nova lógica condicional na inicialização do SDK pode causar uma queda repentina na contagem de sessões.
• Compare usuários afetados e não afetados. Identifique diferenças na versão do app, tipo de dispositivo ou fluxo de usuário que possam explicar por que a inicialização é ignorada para determinados usuários.

Se o problema persistir após verificar sua implementação, reproduza o problema e colete as seguintes informações antes de entrar em contato com o suporte:

• Etapas para reproduzir o problema
• A versão do app afetada
• Logs detalhados do SDK, capturados enquanto o problema ocorre (ou por plataforma: Android, Swift, Web)
• O snippet de código para inicialização do SDK
• Um resumo de qualquer lógica condicional aplicada antes da inicialização