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

Configurar caminhos de link de envio

Defina os caminhos JSON onde os links de rastreamento Singular estão localizados dentro da sua estrutura de carga de notificação push.

Configure os caminhos de link de envio usando cadeias de caracteres delimitadas por barras que especificam o caminho principal para o link Singular na sua estrutura de dados de notificação.

// Configure push link paths in SDK initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .WithPushNotificationsLinkPaths(new List<string> 
    {
        "sng_link",                                    // Top-level key
        "path/to/url",                                 // Nested path
        "rootObj/nestedObj/singularLink"               // Deep nested path
    });

SingularSDK.InitializeSingularSDK();

Exemplos de configuração de caminho:

• Chaves simples: Use "sng_link" para chaves de nível superior na carga útil
• Chaves aninhadas: Use "rootObj/nestedObj/key"para percorrer estruturas JSON aninhadas
• Vários caminhos: Defina várias cadeias de caminhos para verificar diferentes localizações possíveis para ligações Singular

Manipulação específica da plataforma

Tratamento de notificações push do iOS

Estado terminado (aplicativo não em execução)

Nenhuma ação manual é necessária para aplicativos iOS em estado terminado. A integração do Singular iOS manipula automaticamente o rastreamento por push usando SingularAppController.

Estado em segundo plano (aplicativo em execução em segundo plano)

Quando uma notificação é recebida enquanto o aplicativo está em segundo plano, use HandlePushNotification() para passar dados de push para o SDK.

using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;

public class PushNotificationHandler : MonoBehaviour
{
    void Start()
    {
        // Subscribe to Firebase message received event
        Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
    }

    private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
    {
        Debug.Log("Received Firebase push notification");

        // Extract notification data
        var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);

        // Pass notification data to Singular SDK
        SingularSDK.HandlePushNotification(pushDataDictionary);

        // Your additional notification handling logic
        DisplayNotification(e.Message);
    }
}

Tratamento de notificações push do Android

Tratamento automático (recomendado)

Certifique-se de que sua atividade principal do Unity estende SingularUnityActivitypara o tratamento automático de notificações push nos estados em segundo plano e finalizado.

import com.singular.unitybridge.SingularUnityActivity;

public class MessagingUnityPlayerActivity extends SingularUnityActivity {
    // Your custom activity logic here

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Your initialization code
    }
}

Exemplo de integração do Firebase

Se você precisar de uma lógica personalizada de tratamento de mensagens do Firebase, implemente um ouvinte e encaminhe os dados de notificação para o Singular.

using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;

public class AndroidPushHandler : MonoBehaviour
{
    void Start()
    {
        // Subscribe to Firebase messaging events
        Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
        Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
    }

    private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
    {
        Debug.Log("Received a new Firebase message");

        // Convert message data to dictionary
        var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);

        // Forward to Singular SDK for attribution
        SingularSDK.HandlePushNotification(pushDataDictionary);

        // Your custom handling logic
        ProcessNotificationContent(e.Message);
    }

    private void OnTokenReceived(object sender, TokenReceivedEventArgs token)
    {
        Debug.Log($"FCM Token received: {token.Token}");

        // Store or use token as needed
        // Note: Singular automatically handles token registration
    }

    private void ProcessNotificationContent(FirebaseMessage message)
    {
        // Your custom notification display or routing logic
        string title = message.Notification?.Title ?? "Notification";
        string body = message.Notification?.Body ?? "";

        Debug.Log($"Notification: {title} - {body}");
    }
}

Guia de validação

Verificar 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 Singular 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=com.yourcompany.app
&s=1740905574084
&sdk=Singular/Unity-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.

// Configure ESP domains for wrapped Singular links
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .WithESPDomains(new List<string> { "sl.esp.link", "custom.domain.com" });

SingularSDK.InitializeSingularSDK();

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 em destaque: 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 SetSingularLinkHandler, 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 trata automaticamente as notificações de estado terminado, enquanto o Android requer a extensão de SingularUnityActivity para o tratamento automático