Suporte a notificações push

Acompanhe as interações dos usuários com notificações push para medir campanhas de re-engajamento e atribuir conversões com precisão, integrando o Apple Push Notification Service (APNs) ao SDK do Singular.

Siga as diretrizes de implementação abaixo para garantir que os dados das notificações sejam corretamente repassados ao SDK do Singular para uma atribuição adequada.

Guia de implementação

Registrar para notificações push

Solicite autorização dos usuários para receber notificações push e registre o app junto ao APNs usando UNUserNotificationCenter.

import UserNotifications

// Set the current instance as the delegate for UNUserNotificationCenter
UNUserNotificationCenter.current().delegate = self

// Define the notification authorization options (alert, badge, sound)
let pushAuthOptions: UNAuthorizationOptions = [.alert, .badge, .sound]

// Request notification authorization from the user
UNUserNotificationCenter.current().requestAuthorization(options: pushAuthOptions) { granted, error in
    // If an error occurs during authorization, print the error description
    if let error = error {
        print("registerForPushNotifications : failure - \(error.localizedDescription)")
    }

    // If the user granted permission, register for remote notifications
    if granted {
        // Ensure registration is done on the main thread
        DispatchQueue.main.async {
            UIApplication.shared.registerForRemoteNotifications()
        }
    }
}

- (void)registerForPushNotifications:(UIApplication *)application {
    // Set delegate to self
    [UNUserNotificationCenter currentNotificationCenter].delegate = self;

    // Define the push notification options
    UNAuthorizationOptions pushAuthOptions = UNAuthorizationOptionAlert |
        UNAuthorizationOptionBadge |
        UNAuthorizationOptionSound;

    // Request push notification authorization
    [[UNUserNotificationCenter currentNotificationCenter]
        requestAuthorizationWithOptions:pushAuthOptions
        completionHandler:^(BOOL granted, NSError * _Nullable error) {
            if (error) {
                NSLog(@"registerForPushNotifications : failure - %@", error.localizedDescription);
            }

            if (granted) {
                dispatch_async(dispatch_get_main_queue(), ^{
                    [application registerForRemoteNotifications];
                });
            }
        }];
}

Tratar respostas de notificação

Processe as respostas de notificação quando os usuários tocarem nas notificações push e encaminhe os dados do payload ao Singular para rastreamento.

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {

    // Extract the notification payload
    let userInfo = response.notification.request.content.userInfo

    // Pass the notification data to Singular for tracking
    Singular.handlePushNotification(userInfo)

    // Call the completion handler to indicate processing is complete
    completionHandler()
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
    didReceiveNotificationResponse:(UNNotificationResponse *)response
    withCompletionHandler:(void (^)(void))completionHandler {

    // Extract the push notification payload (user info)
    NSDictionary *userInfo = response.notification.request.content.userInfo;

    // Log the userInfo dictionary for debugging purposes
    NSLog(@"didReceiveNotificationResponse userInfo = %@", userInfo);

    // Pass the notification data to Singular for tracking
    [Singular handlePushNotification:userInfo];

    // Call the completion handler to indicate processing is complete
    completionHandler();
}

Configurar o SDK para payloads push

Adicione seletores de payload de notificação push à configuração do seu SDK para especificar onde os Singular links estão localizados na estrutura de dados da notificação.

func getConfig() -> SingularConfig? {
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }

    // Configure push notification link paths
    config.pushNotificationLinkPath = [
        ["sng_link"],
        ["rootObj", "nestedObj", "anotherNested", "singularLink"]
    ]

    return config
}

// Start the Singular SDK with the configuration
if let config = getConfig() {
    Singular.start(config)
}

- (SingularConfig *)getConfig {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
        andSecret:@"SDK_SECRET"];

    // Configure push notification link paths
    config.pushNotificationLinkPath = @[
        @[@"sng_link"],
        @[@"rootObj", @"nestedObj", @"anotherNested", @"singularLink"]
    ];

    return config;
}

// Start the Singular SDK with the configuration
SingularConfig *config = [self getConfig];
[Singular start:config];

Configuração de seletores:

• Chaves simples: Use ["sng_link"] para chaves de nível superior no payload
• Chaves aninhadas: Use ["rootObj", "nestedObj", "key"] para percorrer estruturas JSON aninhadas
• Múltiplos caminhos: Defina múltiplos arrays de seletores para verificar diferentes locais possíveis dos Singular links

Guia de validação

Verificar o payload no Start Session

Confirme que os links de notificação push são corretamente repassados ao Singular inspecionando a chamada de API de start session.

O SDK do Singular inclui o payload de notificação push no parâmetro singular_link da solicitação de start session quando os usuários tocam nas notificações.

Exemplo de solicitação de Start Session:

https://skan.singular.net:443/api/v1/start?
dnt=-1
&update_time=0
&singular_link=https://sl.sng.link/Cclbu/2a7n?_dl=com.singular.app&_smtype=3
&i=com.singular.SwiftScene
&sdk=Singular/12.7.1
&p=iOS
&v=18.2.1

Configuração avançada

Configuração de domínios ESP

Configure domínios externos se você envelopar os Singular links dentro de um Email Service Provider (ESP) ou outros domínios de terceiros.

func getConfig() -> SingularConfig? {
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }

    // Configure ESP domains for wrapped links
    config.espDomains = ["sl.esp.link", "custom.domain.com"]

    return config
}

- (SingularConfig *)getConfig {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
        andSecret:@"SDK_SECRET"];

    // Configure ESP domains for wrapped links
    config.espDomains = @[@"sl.esp.link", @"custom.domain.com"];

    return config;
}

Roteamento dinâmico de deep links

Implemente múltiplos destinos de deep link a partir de uma única notificação configurando um Singular tracking link com substituições de redirecionamento dinâmicas.

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

• Ler as últimas notícias: newsapp://article?id=12345
• Em alta: newsapp://trending
• Esportes: newsapp://sports

Em vez de criar múltiplos tracking links, use um único Singular link e substitua os redirecionamentos dinamicamente com base na seleção do usuário. Consulte Substituindo redirecionamentos em Singular Tracking Links para detalhes de implementação.

Considerações importantes

Notas de implementação

• Sem callback handler: Diferente de singularLinksHandler , o recurso de notificações push não fornece callbacks de payload. Implemente sua própria lógica de deep linking para encaminhar os usuários a conteúdos específicos dentro do seu app
• Fluxo de atribuição: Quando os usuários tocam nas notificações, o Singular recupera o payload e o inclui no evento de start session disparado por Singular.start() . O backend processa esses dados para atribuir o touchpoint da notificação push e registrar o rastreamento de re-engajamento
• Restrições de domínio: Por padrão, apenas os domínios de Singular link ( sng.link ) da página Manage Links são permitidos. Configure os domínios ESP explicitamente para links envelopados usando espDomains