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 em seu projeto React Native usando as instruções de instalação padrão, conforme documentado no guia Singular SDK do React Native.

Configurar o serviço de mensagens em nuvem do Firebase

Instale os pacotes do Firebase e defina as configurações específicas da plataforma para suporte à notificação por push.

Instalar os pacotes do Firebase

Adicione as dependências do React Native Firebase para a funcionalidade principal e suporte a mensagens.

npm install @react-native-firebase/app
npm install @react-native-firebase/messaging

Configuração do iOS

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

1. Registrar o aplicativo iOS: Crie um aplicativo iOS no seu projeto do Firebase Console
2. Adicionar arquivo de configuração: Baixe GoogleService-Info.plist e adicione-o ao seu projeto Xcode
3. Habilitar recursos: Nas configurações do projeto Xcode, ative o recurso Notificações por push
4. Habilitar modos de 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 android/app/
3. Verificar dependências: Verifique se as dependências de mensagens do Firebase foram adicionadas e se as permissões 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.

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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

const config: SingularConfig = {
  apikey: 'YOUR_SDK_KEY',
  secret: 'YOUR_SDK_SECRET',
  pushNotificationsLinkPaths: [
    ['sng_link'],                            // Top-level key
    ['path', 'to', 'url'],                   // Nested path
    ['rootObj', 'nestedObj', 'singularLink'] // Deep nested path
  ]
};

NativeSingular.init(config);

import { Singular, SingularConfig } from 'singular-react-native';

const config = new SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
)
  .withPushNotificationsLinkPaths([
    ['sng_link'],                              // Top-level key
    ['path', 'to', 'url'],                     // Nested path
    ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
  ]);

Singular.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

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.

Em AppDelegate, adicione o seguinte dentro de didFinishLaunchingWithOptions:

// Import at the top of the file
import Singular

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
  let delegate = ReactNativeDelegate()
  let factory = RCTReactNativeFactory(delegate: delegate)
  delegate.dependencyProvider = RCTAppDependencyProvider()

  reactNativeDelegate = delegate
  reactNativeFactory = factory

  window = UIWindow(frame: UIScreen.main.bounds)

  if let singularBridge = NSClassFromString("SingularBridge") {
    let selector = NSSelectorFromString("startSessionWithLaunchOptions:")
    if singularBridge.responds(to: selector) {
      singularBridge.perform(selector, with: launchOptions, afterDelay: 1)
    }
  }

  factory.startReactNative(
    withModuleName: "YourAppName", // Update with your App Name
    in: window,
    launchOptions: launchOptions
  )

  return true
}

// Import at the top of the file
#import <Singular-React-Native/SingularBridge.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Pass launch options to Singular for push tracking
    [SingularBridge startSessionWithLaunchOptions: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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import messaging from '@react-native-firebase/messaging';

export default function App() {
  useEffect(() => {
    // Handle foreground messages
    const unsubscribeBackground = messaging().onMessage(handleForegroundMessage);

    // Handle messages that opened the app from background
    messaging().onNotificationOpenedApp(handleBackgroundMessage);

    return () => {
      unsubscribeBackground();
    };
  }, []);

  function handleForegroundMessage(remoteMessage) {
    console.log('Foreground message received:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      NativeSingular.handlePushNotification(remoteMessage.data);
    }

    // Your custom notification handling
    displayLocalNotification(remoteMessage);
  }

  function handleBackgroundMessage(remoteMessage) {
    console.log('Background message opened app:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      NativeSingular.handlePushNotification(remoteMessage.data);
    }

    // Navigate to appropriate screen
    navigateFromNotification(remoteMessage);
  }

  function displayLocalNotification(remoteMessage) {
    // Your notification display logic
    console.log('Displaying notification:', remoteMessage.notification?.title);
  }

  function navigateFromNotification(remoteMessage) {
    // Your navigation logic based on notification data
    const route = remoteMessage.data?.route;
    console.log('Navigating to:', route);
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular } from 'singular-react-native';
import messaging from '@react-native-firebase/messaging';

export default function App() {
  useEffect(() => {
    // Handle background messages
    const unsubscribeBackground = messaging().onMessage(handleForegroundMessage);

    // Handle messages that opened the app from background
    messaging().onNotificationOpenedApp(handleBackgroundMessage);

    return () => {
      unsubscribeBackground();
    };
  }, []);

  function handleForegroundMessage(remoteMessage) {
    console.log('Foreground message received:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      Singular.handlePushNotification(remoteMessage.data);
    }

    // Your custom notification handling
    displayLocalNotification(remoteMessage);
  }

  function handleBackgroundMessage(remoteMessage) {
    console.log('Background message opened app:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      Singular.handlePushNotification(remoteMessage.data);
    }

    // Navigate to appropriate screen
    navigateFromNotification(remoteMessage);
  }

  function displayLocalNotification(remoteMessage) {
    // Your notification display logic
    console.log('Displaying notification:', remoteMessage.notification?.title);
  }

  function navigateFromNotification(remoteMessage) {
    // Your navigation logic based on notification data
    const route = remoteMessage.data?.route;
    console.log('Navigating to:', route);
  }

  return (
    // Your app components
  );
}

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

Tratamento de notificações push do Android

Aplicativo em estado terminado

Nenhuma ação é necessária para aplicativos Android em estado finalizado. A camada de ponte do React Native 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 MainActivity (por exemplo, MainActivity.java ou MainActivity.kt), substitua onNewIntent:

// Add imports at the top
import android.content.Intent;
import net.singular.react_native.SingularBridgeModule;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    // Pass intent to Singular for push tracking
    SingularBridgeModule.onNewIntent(intent);
}

// Add imports at the top
import android.content.Intent
import net.singular.react_native.SingularBridgeModule

// Add to MainActivity class
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    // Pass intent to Singular for push tracking
    SingularBridgeModule.onNewIntent(intent)
}

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

Guia de validação

Verificar a carga útil na sessão inicial

Confirme que os links de notificação push são passados corretamente para o Singular inspecionando a chamada da API de início de sessão.

O SDK do Singular inclui a carga útil da notificação por push no parâmetro singular_link na solicitação da 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.sampleapp
&s=1740905574084
&sdk=Singular/React-Native-v1.0.0

Configuração avançada

Configuração de domínio ESP

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Configure ESP domains for wrapped Singular links
const config: SingularConfig = {
  apikey: 'YOUR_SDK_KEY',
  secret: 'YOUR_SDK_SECRET',
  espDomains: ['sl.esp.link', 'custom.domain.com']
};

NativeSingular.init(config);

import { Singular, SingularConfig } from 'singular-react-native';

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

Singular.init(config);

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

Roteamento dinâmico de deep link

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.

Considerações importantes

Notas de implementação

• Nenhum manipulador de retorno de chamada: Ao contrário de withSingularLink, o recurso de notificação por push não fornece retornos de chamada de carga. Implemente a sua própria lógica de ligação profunda para encaminhar os utilizadores para conteúdos específicos na sua aplicaçã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 pela inicialização do SDK. 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 padrão, somente domínios de link único (sng.link) da página Gerenciar links são permitidos. 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 estado terminado, enquanto o Android trata disso automaticamente através do módulo de ponte