Suporte a notificações push

Acompanhe as interações do usuário com notificações push para medir campanhas de reengajamento e atribuir conversões com precisão, integrando o Firebase Cloud Messaging (FCM) com o Singular SDK.

Siga as diretrizes de implementação abaixo para garantir que os dados de notificação sejam passados corretamente para o Singular SDK para atribuição adequada.

Guia de Implementação

Integrar o SDK da Singular

Integre o Singular SDK no seu projeto Cordova usando as instruções de instalação padrão, conforme documentado no guia Singular SDK do Cordova.

Configurar o Firebase Cloud Messaging

Configure as notificações push no seu projeto Cordova usando um plug-in como @havesource/cordova-plugin-push e siga o guia de configuração do Firebase para integração específica da plataforma.

Configuração do iOS

Registre seu aplicativo iOS no Firebase e configure os recursos de notificação por push no Xcode.

1. Registrar aplicativo iOS: Crie um aplicativo iOS no seu projeto do Firebase Console
2. Adicionar arquivo de configuração: Baixe GoogleService-Info.plist e inclua-o na pasta da plataforma iOS
3. Habilitar recursos: Nas configurações do projeto Xcode, ative o recurso Notificações por push
4. Habilitar modos em segundo plano: Habilite os Modos em segundo plano e marque as Notificações remotas

Configuração do Android

Registre seu aplicativo Android no Firebase e adicione o arquivo de configuração ao seu projeto.

1. Registar a aplicação Android: Crie um aplicativo Android no seu projeto do Firebase Console
2. Adicionar arquivo de configuração: Baixe google-services.json e coloque-o em platforms/android/app/
3. Verificar dependências: Verifique se o plug-in do Firebase está instalado corretamente e se as permissões de mensagens foram concedidas

Configurar caminhos de link de envio

Defina os caminhos JSON onde os links de rastreamento Singular estão localizados na estrutura de carga útil da notificação por push para permitir o rastreamento de atribuição adequado.

Configure os caminhos do link de envio passando matrizes de cadeias de caracteres que especificam o caminho principal para o link Singular na estrutura de dados da notificação. Cada caminho é uma matriz que representa a estrutura aninhada de chaves.

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure paths where Singular links appear in push payload
config.withPushNotificationsLinkPaths([
  ['sng_link'],                              // Top-level key
  ['path', 'to', 'url'],                     // Nested path
  ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
]);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

Exemplos de configuração de caminho:

• Chaves simples: Use ['sng_link'] para chaves de nível superior no payload
• Chaves aninhadas: Use ['rootObj', 'nestedObj', 'key'] para percorrer estruturas JSON aninhadas
• Vários caminhos: Defina várias matrizes de caminho para verificar diferentes locais possíveis para links Singulares

Para obter a documentação completa do método, consulte a referência withPushNotificationsLinkPaths.

Tratamento específico da plataforma

Configure o código específico da plataforma para passar dados de notificação para o SDK Singular com base no estado do aplicativo quando os usuários interagem com notificações push.

Tratamento de notificações push do iOS

Aplicativo em estado terminado

Configure seu AppDelegate do iOS para passar opções de inicialização para o SDK Singular para rastreamento automático de push quando o aplicativo for aberto a partir de um estado finalizado.

No seu código iOS nativo dentro de AppDelegate.m, chame o seguinte método dentro de didFinishLaunchingWithOptions:

// Import at the top of the file
#import <SingularCordovaSdk/SingularCordovaSdk.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // Pass launch options to Singular for push tracking
    [SingularCordovaSdk setLaunchOptions:launchOptions];
    
    // Your other initialization code
    return YES;
}

Aplicativo em segundo plano ou em primeiro plano

Use o método handlePushNotification() para passar dados push para o SDK quando o aplicativo receber notificações em estados de segundo ou primeiro plano.

Chame o seguinte método no seu código JavaScript onde a notificação push é tratada:

// Handle push notification when app is in background or foreground
document.addEventListener('deviceready', initializePushHandling, false);

function initializePushHandling() {
  // Initialize push plugin
  var push = PushNotification.init({
    android: {},
    ios: {
      alert: true,
      badge: true,
      sound: true
    }
  });
  
  // Handle notification when app is in foreground or background
  push.on('notification', function(data) {
    console.log('Push notification received:', data);
    
    // Pass notification data to Singular
    cordova.plugins.SingularCordovaSdk.handlePushNotification(data.additionalData);
    
    // Your custom notification handling logic
    handleNotificationNavigation(data);
  });
}

function handleNotificationNavigation(data) {
  // Navigate to appropriate screen based on notification data
  if (data.additionalData && data.additionalData.route) {
    console.log('Navigating to:', data.additionalData.route);
    // Your navigation logic
  }
}

Para obter a documentação completa do método, consulte a referência handlePushNotification.

Tratamento de notificações push do Android

Aplicação em estado terminado

Nenhuma ação é necessária para aplicativos Android em estado finalizado. A camada de ponte do Cordova lida com esse cenário automaticamente quando os usuários tocam nas notificações.

Aplicativo em segundo ou primeiro plano

Configure sua MainActivity do Android para passar intenções de notificação para o SDK do Singular quando o aplicativo estiver em estados de segundo ou primeiro plano.

Na sua atividade principal do Cordova (por exemplo, MainActivity.java), substitua onNewIntent:

// Add imports at the top
import android.content.Intent;
import singular_cordova_sdk.SingularCordovaSdk;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    
    // Pass intent to Singular for push tracking
    SingularCordovaSdk.handleNewIntent(intent);
}

Além disso, implemente o tratamento de mensagens push no seu código JavaScript usando a mesma abordagem mostrada acima para o tratamento de fundo/primeiro plano do iOS.

Guia de validação

Verifique se o rastreamento de notificações push está funcionando corretamente inspecionando as chamadas de sessão inicial do Singular SDK e monitorando os dados de atribuição.

Verificar a carga útil na sessão inicial

Verificar parâmetros de chamada de API

Confirme se os links de notificação push são passados corretamente para o Singular inspecionando a chamada da API da sessão inicial.

O Singular SDK inclui a carga útil da notificação push no parâmetro singular_link na solicitação de sessão inicial quando os usuários tocam nas notificações.

Exemplo de solicitação de início de sessão:

https://sdk-api-v1.singular.net/api/v1/start?
a=<SDK-Key>
&singular_link=https://singularassist2.sng.link/C4nw9/r1m0?_dl=singular%3A%2F%2Ftest&_smtype=3
&i=net.singular.singularsampleapp
&install_time=1740905507036
&s=1740905574084
&sdk=Singular/v12.6.2
&singular_install_id=2dc5dfc2-a2a8-484a-aad1-fed6cb7a3023
&u=75f7b911-5a77-597d-8892-56f5e0e210ff

Configuração avançada

Implemente recursos avançados de notificação por push, incluindo configuração de domínio ESP e roteamento dinâmico de deep link para cenários de notificação complexos.

Configuração de domínio ESP

Configurar domínios externos

Configure domínios externos se você envolver links Singular no Provedor de serviços de e-mail (ESP) ou em outros domínios de terceiros.

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure ESP domains for wrapped Singular links
config.withESPDomains(['sl.esp.link', 'custom.domain.com']);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

Para obter a documentação completa do método, consulte a referência withESPDomains.

Roteamento dinâmico de links profundos

Várias ações a partir de uma única notificação

Implemente vários destinos de deep link a partir de uma única notificação, configurando um link de rastreamento Singular com substituições de redirecionamento dinâmico.

Exemplo de caso de uso: Uma notificação de notícias de última hora com várias opções de ação

• Ler as últimas notícias: newsapp://article?id=12345
• Tópicos de tendência: newsapp://trending
• Desporto: newsapp://sports

Em vez de criar várias ligações de seguimento, utilize uma ligação Singular e substitua os redireccionamentos dinamicamente com base na seleção do utilizador. Consulte Substituição de redirecionamentos em links de rastreamento singularespara obter detalhes de implementação.

// Handle multiple deep link options from single notification
function handleNotificationWithActions(notificationData) {
  // Extract action selection from notification data
  var selectedAction = notificationData.action;
  var singularLink = notificationData.sng_link;
  
  // Route based on action
  switch (selectedAction) {
    case 'read_news':
      navigateToArticle(notificationData.article_id);
      break;
    case 'trending':
      navigateToTrending();
      break;
    case 'sports':
      navigateToSports();
      break;
    default:
      navigateToHome();
  }
  
  // Pass notification to Singular for attribution
  cordova.plugins.SingularCordovaSdk.handlePushNotification(notificationData);
}

function navigateToArticle(articleId) {
  console.log('Navigating to article:', articleId);
  // Your navigation logic
}

function navigateToTrending() {
  console.log('Navigating to trending');
  // Your navigation logic
}

function navigateToSports() {
  console.log('Navigating to sports');
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

Considerações importantes

Entenda os principais detalhes de implementação e limitações ao integrar o rastreamento de notificações push com o SDK Singular.

Notas de implementação

Principais comportamentos e limitações

• Nenhum manipulador de retorno de chamada: Ao contrário de withSingularLink, o recurso de notificação push não fornece retornos de chamada de carga. É necessário implementar a sua própria lógica de ligação profunda para encaminhar os utilizadores para conteúdos específicos na sua aplicação com base nos dados da notificação
• Fluxo de atribuição: quando os usuários tocam nas notificações, o Singular recupera o payload e o inclui no evento de início de sessão acionado por Singular.init(config). O backend processa esses dados para atribuir o ponto de contato da notificação push e registrar o rastreamento de reengajamento
• Restrições de domínio: Por predefinição, só são permitidos os domínios de ligação Singular (sng.link) da página Gerir ligações. Configure explicitamente os domínios ESP para links agrupados usando withESPDomains()
• Diferenças de plataforma: o iOS requer a configuração do AppDelegate para o tratamento do estado terminado, enquanto o Android trata-o automaticamente através do módulo de ponte para cenários de estado terminado
• Configuração de caminho: O SDK procura ligações Singular utilizando os caminhos definidos em withPushNotificationsLinkPaths(). Certifique-se de que a estrutura de carga útil da sua notificação corresponde aos caminhos configurados para a extração adequada do link

Recomendações de teste

1. Teste todos os estados do aplicativo: Verifique se o rastreamento por push funciona corretamente quando o aplicativo é encerrado, colocado em segundo plano e em primeiro plano
2. Validar a estrutura da carga útil: Confirme se a carga útil da notificação inclui links Singular nos caminhos configurados
3. Verifique as chamadas de início de sessão: Use ferramentas de monitoramento de rede para verificar se o parâmetro singular_link aparece nas solicitações de início de sessão
4. Monitorar atribuição: Verifique o Singular SDK Console para confirmar que as notificações push são atribuídas corretamente nos dados da sua campanha
5. Testar Deep Linking: Verifique se os utilizadores são corretamente encaminhados para o conteúdo pretendido quando tocam em diferentes tipos de notificação