Suporte a notificações push

Acompanhe as interações dos usuários com notificações push para medir campanhas de reengajamento e atribuir conversões com precisão, integrando o Firebase Cloud Messaging (FCM) ou o serviço de Notificação Push da Apple (APNs) 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 SDK do Singular em seu projeto do Unreal Engine usando as instruções de instalação padrão, conforme documentado no guia do SDK do Singular Unreal Engine.

Registrar token de push

Registre seu token de notificação por push com o Singular para habilitar o rastreamento de desinstalação e a atribuição de push.

// Register push token for uninstall tracking
void UYourGameInstance::OnPushTokenReceived(const FString& Token)
{
    // Pass the FCM or APNs token to Singular
    USingularSDKBPLibrary::SetUninstallToken(Token);
    UE_LOG(LogTemp, Log, TEXT("Push token registered: %s"), *Token);
}

Assinatura do método:

static void SetUninstallToken(FString token);

Tratamento específico da plataforma

Manuseio de notificações por push do iOS

Configurar caminhos de notificação por push

Para implementações do iOS, configure os caminhos JSON onde os links de rastreamento Singular estão localizados na estrutura de carga de notificação por push durante a inicialização do SDK.

// iOS: Configure push notification link paths in initialization
// Note: This is typically configured through the iOS native bridge
// The Singular SDK do iOS automatically handles push tracking when configured

// Example configuration in iOS native code (Objective-C):
// SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" andSecret:@"API_SECRET"];
// config.singularLinksHandler = ^(SingularLinkParams * _Nonnull params) {
//     // Handle deep link from push notification
// };
// [Singular start:config];

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

Nenhuma ação manual é necessária para aplicativos iOS em estado terminado. A integração Singular iOS lida automaticamente com o rastreamento push quando os usuários tocam nas notificações enquanto seu aplicativo não está em execução.

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

Quando uma notificação é recebida enquanto o aplicativo está em segundo plano, o SDK do iOS processa automaticamente os dados da notificação. Não é necessário qualquer código C++ adicional para além do registo inicial do token.

Manuseio de notificações push do Android

Integração de mensagens na nuvem do Firebase

Para implementações Android, integre o Firebase Cloud Messaging (FCM) e encaminhe os tokens push para o Singular SDK para rastreamento.

// Android: Register FCM token with Singular
void UYourGameInstance::OnFirebaseTokenReceived(const FString& FcmToken)
{
    // Register the FCM token for uninstall tracking
    USingularSDKBPLibrary::SetUninstallToken(FcmToken);
    UE_LOG(LogTemp, Log, TEXT("FCM token registered with Singular: %s"), *FcmToken);
}

Manipulação de dados de notificação push

Quando os usuários tocam em notificações push contendo links de rastreamento Singular, certifique-se de que os dados da notificação sejam passados para o manipulador de deep link do seu aplicativo para atribuição adequada.

// Handle notification tap event
void UYourGameInstance::OnNotificationTapped(const FString& NotificationData)
{
    // Parse notification data for Singular links
    // Example: Extract "sng_link" or custom key from notification payload

    // If notification contains a Singular tracking link, it will be
    // automatically processed by the SDK's deep link handler

    UE_LOG(LogTemp, Log, TEXT("Notification tapped: %s"), *NotificationData);

    // Route user to appropriate content
    ProcessNotificationDeepLink(NotificationData);
}

void UYourGameInstance::ProcessNotificationDeepLink(const FString& LinkData)
{
    // Your custom deep link routing logic
    if (LinkData.Contains(TEXT("article")))
    {
        // Navigate to article
        OpenArticleScreen();
    }
    else if (LinkData.Contains(TEXT("promotion")))
    {
        // Navigate to promotion
        OpenPromotionScreen();
    }
}

Guia de validação

Verificar o registro do token de push

Confirme se os tokens de notificação push estão registrados corretamente no Singular verificando os logs do SDK durante a inicialização do aplicativo.

// Enable SDK logging to verify token registration
bool Success = USingularSDKBPLibrary::Initialize(
    TEXT("YOUR_SDK_KEY"),
    TEXT("YOUR_SDK_SECRET"),
    60,                      // Session timeout
    TEXT(""),                // Custom user ID
    true,                    // Enable SKAdNetwork
    false,                   // Manual SKAN management
    0,                       // Wait for tracking authorization
    false,                   // OAID collection
    true,                    // Enable logging for debugging
    5,                       // Verbose log level
    false,                   // Clipboard attribution
    TEXT(""),                // Facebook App ID
    TEXT("")                 // Custom SDID
);

// After receiving push token
FString PushToken = GetPushNotificationToken();
USingularSDKBPLibrary::SetUninstallToken(PushToken);

// Check logs for confirmation:
// "Push token registered successfully" or similar message

Verificar a atribuição no painel

Use o painel Singular para verificar se as interações de notificação por push estão sendo rastreadas corretamente.

• Campanhas de reengajamento: Verifique a seção Reengajamento em seu painel para ver o desempenho da campanha de notificação por push.
• Dados no nível do usuário: Exporte dados no nível do usuário para verificar se os pontos de contato da notificação por push estão sendo registrados com a atribuição correta.
• Eventos de conversão: Confirme se os eventos acionados após os toques na notificação por push são atribuídos à campanha correta.

Configuração avançada

Estrutura de carga de notificação personalizada

Estruture suas cargas de notificação por push para incluir parâmetros de rastreamento Singular juntamente com seus dados personalizados.

Estrutura de carga útil recomendada (JSON):

{
  "notification": {
    "title": "Special Offer!",
    "body": "Get 50% off today only"
  },
  "data": {
    "sng_link": "https://yourapp.sng.link/Abc12?_dl=myapp://promo",
    "campaign_id": "summer_sale_2025",
    "promo_code": "SAVE50",
    "deep_link": "myapp://promo/summer"
  }
}

Elementos principais:

• sng_link: O link de rastreamento Singular para atribuição (necessário para rastreamento por push).
• campaign_id: Seu identificador de campanha interno para referência.
• deep_link: O deep link personalizado do seu aplicativo para roteamento de conteúdo.
• Dados personalizados: Quaisquer dados adicionais necessários para a sua aplicação (códigos promocionais, segmentos de utilizadores, etc.).

Implementação de roteamento de deep link

Implemente um manipulador de deep link centralizado para encaminhar os usuários para um conteúdo específico quando eles tocam nas notificações push.

// Centralized deep link handler
class UDeepLinkHandler : public UObject
{
public:
    void HandleDeepLink(const FString& DeepLink)
    {
        // Parse the deep link URL
        if (DeepLink.StartsWith(TEXT("myapp://article/")))
        {
            FString ArticleId = ExtractArticleId(DeepLink);
            NavigateToArticle(ArticleId);
        }
        else if (DeepLink.StartsWith(TEXT("myapp://promo/")))
        {
            FString PromoId = ExtractPromoId(DeepLink);
            NavigateToPromotion(PromoId);
        }
        else if (DeepLink.StartsWith(TEXT("myapp://profile")))
        {
            NavigateToUserProfile();
        }
        else
        {
            // Default: Navigate to home screen
            NavigateToHome();
        }
    }

private:
    FString ExtractArticleId(const FString& Url)
    {
        // Extract article ID from URL
        FString ArticleId;
        Url.Split(TEXT("article/"), nullptr, &ArticleId);
        return ArticleId;
    }

    FString ExtractPromoId(const FString& Url)
    {
        // Extract promo ID from URL
        FString PromoId;
        Url.Split(TEXT("promo/"), nullptr, &PromoId);
        return PromoId;
    }

    void NavigateToArticle(const FString& ArticleId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to article: %s"), *ArticleId);
        // Your navigation logic
    }

    void NavigateToPromotion(const FString& PromoId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to promotion: %s"), *PromoId);
        // Your navigation logic
    }

    void NavigateToUserProfile()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to user profile"));
        // Your navigation logic
    }

    void NavigateToHome()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to home screen"));
        // Your navigation logic
    }
};

Considerações importantes

Notas de implementação

• Tempo de registro do token: Registre o token push com a Singular assim que ele estiver disponível no FCM ou nos APNs, idealmente durante ou imediatamente após a inicialização do SDK.
• Fluxo de Atribuição: Quando os usuários tocam em notificações contendo links da Singular, o SDK processa automaticamente os dados de atribuição durante o evento de início da sessão. Nenhum manuseio manual é necessário para o rastreamento de atribuição.
• Tratamento de Deep Link: Embora o Singular trate a atribuição automaticamente, é necessário implementar uma lógica de roteamento de deep link personalizada para navegar os usuários até o conteúdo in-app correto.
• Consistência do payload: Use nomes de chave consistentes (por exemplo, "sng_link") em todas as campanhas de notificação por push para garantir um rastreamento confiável.
• Diferenças de plataforma: iOS e Android lidam com notificações push de forma diferente no nível do sistema. Certifique-se de que sua implementação leve em conta o comportamento específico da plataforma.
• Rastreamento de desinstalação: O token de push também é usado para rastreamento de desinstalação. O Singular envia notificações push silenciosas para detetar aplicativos desinstalados, fornecendo informações valiosas sobre retenção.

Privacidade e permissões

Garanta a conformidade com os requisitos da plataforma e os regulamentos de privacidade do usuário ao implementar notificações por push.

• Permissões do iOS: Os usuários devem conceder permissão para receber notificações por push. Solicite permissão em um momento apropriado no fluxo do aplicativo, não imediatamente na primeira inicialização.
• Permissões do Android: A partir do Android 13 (nível 33 da API), as aplicações têm de solicitar a permissão POST_NOTIFICATIONS para enviar notificações.
• Consentimento do utilizador: Respeite as preferências do utilizador para receber comunicações de marketing. Forneça mecanismos claros de auto-exclusão nas definições da aplicação.
• Privacidade dos dados: Evite incluir informações de identificação pessoal (PII) nos payloads de notificações push. Utilize IDs de utilizador ou outros identificadores que não sejam PII.