SDK do Cordova - Rastreio de desinstalação

Seguir
Avatar
Jared Ornstead
Updated
Documento

Rastreamento de desinstalação

Rastreie desinstalações de aplicativos para medir a retenção de usuários e otimizar campanhas de reengajamento integrando serviços de notificação por push com o SDK Singular.

Importante: o Google descontinuou as APIs do GCM em abril de 2018. Use o Firebase Cloud Messaging (FCM) para todas as implementações de rastreamento de desinstalação do Android.

Visão geral

Como funciona o rastreamento de desinstalação

O rastreamento de desinstalação monitora as remoções de aplicativos registrando tokens de notificação por push com o Singular. Quando os dispositivos não respondem mais às notificações push, o Singular identifica o aplicativo como desinstalado.

  • Android: Usa tokens do Firebase Cloud Messaging (FCM) para detetar desinstalações
  • iOS: Usa tokens do serviço de notificação por push da Apple (APNs) para detetar desinstalações
  • Precisão dos dados: Fornece informações sobre a retenção e o envolvimento do utilizador ao longo do tempo

Rastreamento de desinstalação do Android

Pré-requisitos

Antes de implementar o rastreamento de desinstalação do Android, configure seu aplicativo na plataforma Singular seguindo o Guia de configuração do rastreamento de desinstalação do Android.

Requisitos:

  • Versão do Android: Os dispositivos devem executar o Android 4.1 (API 16) ou superior
  • Google Play Services: Os dispositivos devem ter o aplicativo Google Play Store instalado
  • Configuração do Firebase: O Firebase Cloud Messaging deve ser configurado no seu projeto
  • Permissões: Android 13+ requer permissão explícita de notificação

Etapas de implementação

Passo 1: Instalar o plugin do Firebase

Adicione um plug-in do Firebase ao seu projeto Cordova para obter suporte a notificações por push. O plug-in cordova-plugin-firebase-messaging é recomendado.

bash 
cordova plugin add cordova-plugin-firebase-messaging

Para obter instruções detalhadas de configuração do Firebase, consulte a documentação do plug-in.

Etapa 2: Configurar o Firebase

Adicione arquivos de configuração do Firebase ao seu projeto Cordova para Android.

  1. Registre seu aplicativo Android no seu projeto do Console do Firebase
  2. Baixe google-services.json e coloque-o na raiz do seu projeto ou em platforms/android/app/
  3. Verifique se as dependências de mensagens do Firebase foram adicionadas ao seu projeto durante a instalação do plug-in

Etapa 3: Solicitar permissão de notificação

Solicite permissões de notificação dos usuários (necessário para Android 13+) antes de recuperar o token FCM.

JavaScript 
document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  if (device.platform === 'Android') {
    // Request notification permission (Android 13+)
    requestAndroidNotificationPermission();
  }
}

function requestAndroidNotificationPermission() {
  // Check Android version
  if (device.version >= 13) {
    cordova.plugins.permissions.requestPermission(
      cordova.plugins.permissions.POST_NOTIFICATIONS,
      function(status) {
        if (status.hasPermission) {
          console.log('Notification permission granted');
          retrieveAndRegisterFCMToken();
        } else {
          console.warn('Notification permission denied - uninstall tracking unavailable');
        }
      },
      function(error) {
        console.error('Permission request error:', error);
      }
    );
  } else {
    // Android 12 and below automatically have permission
    retrieveAndRegisterFCMToken();
  }
}

Nota: Para solicitar permissões, instale o plug-in cordova-plugin-android-permissions: 

cordova plugin add cordova-plugin-android-permissions

Passo 4: Recuperar e registar o Token FCM

Obtenha o token de dispositivo FCM e registe-o no Singular utilizando o método setUninstallToken() depois de as permissões serem concedidas.

JavaScript 
function retrieveAndRegisterFCMToken() {
  // Get FCM token
  cordova.plugins.firebase.messaging.getToken().then(function(token) {
    if (token) {
      console.log('FCM token retrieved:', token);
      
      // Register token with Singular for uninstall tracking
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
      
      console.log('FCM token registered with Singular');
    } else {
      console.warn('No FCM token available');
    }
  }).catch(function(error) {
    console.error('Error retrieving FCM token:', error);
  });
}

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

Etapa 5: lidar com a atualização do token

Atualize o token FCM com o Singular sempre que ele for atualizado para manter o rastreamento preciso da desinstalação.

JavaScript 
document.addEventListener('deviceready', setupTokenRefreshListener, false);

function setupTokenRefreshListener() {
  if (device.platform === 'Android') {
    // Listen for FCM token refresh events
    cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
      console.log('FCM token refreshed:', token);
      
      // Update Singular with new token
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
    });
  }
}

Melhores práticas: Os tokens FCM podem ser atualizados a qualquer momento (atualizações de aplicativos, restauração de dispositivos, etc.). Sempre assine eventos de atualização de token para manter o Singular atualizado com o token mais recente.

Rastreamento de desinstalação do iOS

Pré-requisitos

Configure seu aplicativo iOS na plataforma Singular seguindo o Guia de configuração do rastreamento de desinstalação do iOS.

O rastreamento de desinstalação no iOS usa a tecnologia do serviço de notificação por push da Apple (APNs). Se o seu aplicativo não for compatível com notificações por push, consulte o guia da Apple para Registrar seu aplicativo com APNs.

Passos de implementação

Passo 1: Pedir autorização de notificação do iOS

Solicite permissões de notificação ao utilizador e recupere o token de dispositivo APNS.

JavaScript 
document.addEventListener('deviceready', initializeIOSTracking, false);

function initializeIOSTracking() {
  if (device.platform === 'iOS') {
    requestIOSNotificationPermission();
  }
}

function requestIOSNotificationPermission() {
  // Request iOS notification authorization
  cordova.plugins.firebase.messaging.requestPermission({
    forceShow: true
  }).then(function(hasPermission) {
    if (hasPermission) {
      console.log('iOS notification permission granted');
      retrieveAndRegisterAPNSToken();
    } else {
      console.warn('iOS notification permission denied - uninstall tracking unavailable');
    }
  }).catch(function(error) {
    console.error('Error requesting iOS notification permission:', error);
  });
}

Passo 2: Recuperar e registar o Token APNS

Obtenha o token de dispositivo APNS e registre-o no Singular usando o método setUninstallToken() após a autorização ser concedida.

JavaScript 
function retrieveAndRegisterAPNSToken() {
  // Get APNS token (iOS)
  cordova.plugins.firebase.messaging.getToken().then(function(token) {
    if (token) {
      console.log('APNS token retrieved:', token);
      
      // Register token with Singular for uninstall tracking
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
      
      console.log('APNS token registered with Singular');
    } else {
      console.warn('No APNS token available');
    }
  }).catch(function(error) {
    console.error('Error retrieving APNS token:', error);
  });
}

Formato do token: O token APNS recuperado do Firebase Messaging já está formatado corretamente para o Singular. Nenhuma conversão adicional é necessária.

Etapa 3: lidar com a atualização do token (iOS)

Atualize o token APNS com o Singular se ele for alterado durante o ciclo de vida do aplicativo.

JavaScript 
document.addEventListener('deviceready', setupIOSTokenRefreshListener, false);

function setupIOSTokenRefreshListener() {
  if (device.platform === 'iOS') {
    // Listen for APNS token refresh events
    cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
      console.log('APNS token refreshed:', token);
      
      // Update Singular with new token
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
    });
  }
}

Implementação completa entre plataformas

Configuração unificada de rastreamento de desinstalação

Implemente o rastreamento de desinstalação para as plataformas Android e iOS com tratamento adequado de erros e lógica de atualização de token.

JavaScript 
document.addEventListener('deviceready', initializeUninstallTracking, false);

function initializeUninstallTracking() {
  console.log('Initializing uninstall tracking for:', device.platform);
  
  // Setup token refresh listener for both platforms
  setupTokenRefreshListener();
  
  // Platform-specific initialization
  if (device.platform === 'Android') {
    setupAndroidUninstallTracking();
  } else if (device.platform === 'iOS') {
    setupIOSUninstallTracking();
  }
}

function setupAndroidUninstallTracking() {
  // Check Android version for permission requirements
  if (device.version >= 13) {
    // Request notification permission for Android 13+
    cordova.plugins.permissions.requestPermission(
      cordova.plugins.permissions.POST_NOTIFICATIONS,
      function(status) {
        if (status.hasPermission) {
          retrieveAndRegisterToken();
        } else {
          console.warn('Android notification permission denied');
        }
      },
      function(error) {
        console.error('Permission request error:', error);
      }
    );
  } else {
    // Android 12 and below - permission not required
    retrieveAndRegisterToken();
  }
}

function setupIOSUninstallTracking() {
  // Request iOS notification authorization
  cordova.plugins.firebase.messaging.requestPermission({
    forceShow: true
  }).then(function(hasPermission) {
    if (hasPermission) {
      retrieveAndRegisterToken();
    } else {
      console.warn('iOS notification permission denied');
    }
  }).catch(function(error) {
    console.error('Error requesting iOS permission:', error);
  });
}

function retrieveAndRegisterToken() {
  // Get push notification token (FCM for Android, APNS for iOS)
  cordova.plugins.firebase.messaging.getToken()
    .then(function(token) {
      if (token) {
        console.log('Token retrieved for ' + device.platform + ':', token);
        
        // Register token with Singular
        cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
        
        console.log('Token registered with Singular successfully');
      } else {
        console.warn('No token available for ' + device.platform);
      }
    })
    .catch(function(error) {
      console.error('Error retrieving token:', error);
    });
}

function setupTokenRefreshListener() {
  // Listen for token refresh events on both platforms
  cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
    console.log('Token refreshed for ' + device.platform + ':', token);
    
    // Update Singular with new token
    cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
  });
}

Verificação e solução de problemas

Verificar a implementação

Confirme se o rastreamento de desinstalação está funcionando corretamente antes de implantar na produção.

  1. Verifique os logs: Verifique se o registro do token aparece nos logs do console com o formato correto
  2. Teste a geração de tokens: Certifique-se de que os tokens sejam gerados na primeira inicialização do aplicativo após a concessão de permissões
  3. Monitorar o painel: Verifique o painel do Singular para obter dados de rastreamento de desinstalação após 24-48 horas
  4. Testar atualização de token: Limpar os dados do aplicativo e verificar se o token é atualizado corretamente quando o aplicativo é reiniciado

Problemas comuns

  • Token não gerado: Verifique se o plug-in do Firebase está instalado corretamente e se o Firebase está configurado no seu projeto Cordova
  • Permissão negada: Verifique se os usuários concederam permissões de notificação (necessário para Android 13+ e todas as versões do iOS)
  • Token não está sendo atualizado: Certifique-se de que você se inscreveu no evento onTokenRefresh para ambas as plataformas
  • Dados ausentes: Confirme se os dispositivos cumprem os requisitos da plataforma (Android 4.1+ com Google Play Services, iOS com suporte para APNs)
  • Erro de configuração: Verifique se o rastreamento de desinstalação está ativado nas configurações da plataforma Singular para seu aplicativo
  • Configuração do Firebase: Para Android, verifique se google-services.json está no local correto. Para iOS, verifique se GoogleService-Info.plist foi adicionado ao projeto Xcode

Recursos adicionais: Para obter uma solução de problemas detalhada, consulte o Guia de configuração do rastreamento de desinstalação do Android, o Guia de configuração do rastreamento de desinstalação do iOS e a Documentação do plug-in de mensagens do Firebase.

Práticas recomendadas

  • Solicitar permissões antecipadamente: Solicite permissões de notificação durante a integração ou quando o valor do usuário for estabelecido
  • Lidar com rejeições graciosamente: Forneça mensagens claras quando as permissões forem negadas e explique o benefício para os usuários
  • Testar ambas as plataformas: Verificar se a implementação funciona tanto no Android como no iOS com diferentes versões do sistema operativo
  • Monitorizar a atualização do token: Implemente sempre ouvintes de atualização de token para tratar automaticamente as actualizações de token
  • Registo para depuração: Ativar o registo detalhado durante o desenvolvimento para acompanhar a geração e o registo de tokens