Configuração do rastreamento de desinstalação no Android

Rastreie as desinstalações de aplicativos no Android para medir a retenção de usuários, identificar fontes de tráfego de baixa qualidade e otimizar o desempenho da campanha usando a integração do Firebase Cloud Messaging com o Singular SDK.

Visão geral

Como funciona o rastreamento de desinstalação

O Singular detecta desinstalações de aplicativos enviando notificações push silenciosas por meio do Firebase Cloud Messaging e monitorando as respostas de entrega para determinar se o aplicativo permanece instalado nos dispositivos.

Processo técnico:

1. Registro de token: o SDK do Singular registra tokens FCM nos servidores do Singular
2. Notificações silenciosas: o Singular envia notificações push silenciosas periódicas para dispositivos registrados
3. Feedback de entrega: o FCM relata o sucesso ou a falha na entrega
4. Detecção de desinstalação: entregas com falha indicam desinstalação do aplicativo
5. Registro de eventos: evento de desinstalação atribuído à fonte de instalação original

Requisitos

• Versão do SDK: SDK do Android 7.0+ necessário para rastreamento de desinstalação .
• Configuração do Firebase: projeto Firebase ativo com Cloud Messaging habilitado
• Google Play Services: os dispositivos devem ter o Google Play Services instalado
• Atualização do aplicativo: os usuários devem instalar a versão atualizada do aplicativo com o rastreamento de desinstalação ativado
• Permissões: Android 13+ requer permissão explícita de notificação para geração de token FCM

Considerações importantes

Compartilhamento restrito por domínio

Se sua organização do Google tiver o compartilhamento restrito por domínio ativado, conceda acesso à organização Singular para ativar a funcionalidade de rastreamento de desinstalação .

Etapas de configuração:

1. Acesse as políticas da organização: navegue até a página Políticas da organização no Google Cloud Console
2. Selecione o recurso: escolha a organização onde a política está configurada
3. Encontre a restrição: localize a restrição "Compartilhamento restrito ao domínio" .
4. Gerenciar política: Clique no botão "Gerenciar política"
5. Adicione a organização Singular: em Valores da política, selecione Personalizado e adicione o seguinte:

is:principalSet://iam.googleapis.com/organizations/626787461583

Isso concede à conta de serviço da Singular acesso para enviar notificações FCM para detecção de desinstalação.

Configuração da API HTTP v1 (recomendado)

Configure o rastreamento de desinstalação usando a API HTTP v1 do Firebase Cloud Messaging com segurança aprimorada por meio de tokens de acesso OAuth 2.0 e suporte aprimorado a mensagens entre plataformas .

Etapa 1: integrar o SDK do Android 7.x+

Atualizar a versão do SDK

Certifique-se de que seu aplicativo esteja usando o Singular SDK do Android versão 7.0 ou superior. Se você ainda não integrou o Singular SDK, conclua o Guia de integração do Android SDK antes de configurar o rastreamento de desinstalação.

Guia de integração completo: Guia de integração do SDK para Android

Etapa 2: Confirme a configuração do AndroidManifest.xml FCM

Verifique o serviço FCM e as permissões

Certifique-se de que seu aplicativo já esteja integrado ao Firebase Cloud Messaging e que o manifesto do Android declare um FirebaseMessagingService para receber mensagens FCM.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.your.package">

    <!-- FCM Permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application>

        <!-- App Firebase Messaging Service -->
        <service
            android:name=".MyFirebaseMessagingService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>

    </application>

</manifest>

Importante: substitua .MyFirebaseMessagingService pelo nome completo da sua classe que estende FirebaseMessagingService. Apenas um serviço deve lidar com a intenção com.google.firebase.MESSAGING_EVENT no seu aplicativo.

Configuração detalhada do manifesto: Guia do manifesto do Firebase FCM para Android.

Etapa 3: criar projeto Firebase

Inicialize o Firebase

Configure um projeto Firebase e recupere o ID do projeto necessário para a configuração do Singular .

1. Abra o Console do Firebase: Navegue até Console do Firebase
2. Criar projeto: selecione ou crie um novo projeto Firebase para seu aplicativo
3. Localize as configurações do projeto: clique no ícone de engrenagem → Configurações do projeto .
4. Copie o ID do projeto: copie o ID do seu projeto na guia Geral (você irá inseri-lo no Singular posteriormente)

Etapa 4: habilite a API Firebase Cloud Messaging

Ative a API HTTP v1

Habilite a API Firebase Cloud Messaging (v1) para que seu projeto use o protocolo HTTP v1 moderno.

1. Navegue até Cloud Messaging: No Firebase Console, vá para Configurações do projeto → guia Cloud Messaging
2. Habilite a API: Clique em "Habilitar" ao lado da API Firebase Cloud Messaging (V1)
3. Verifique a ativação: confirme se o status da API aparece como "Ativado"

Etapa 5: criar função IAM personalizada

Configurar permissões da conta de serviço

Crie uma função IAM personalizada com permissões específicas para o Singular enviar notificações FCM para detecção de desinstalação.

1. Acesse o IAM: em Configurações do projeto Firebase → Contas de serviço → Gerenciar permissões da conta de serviço
2. Abrir funções: Selecione "Funções" no menu de navegação à esquerda
3. Criar função: clique no botão "Criar função"
4. Configurar detalhes da função:
   • Título: Singular Uninstall Tracking
   • ID: singular_uninstalls
   • Estágio de lançamento da função: General Availability

Adicionar permissão necessária

Conceda a função personalizada permissão para enviar mensagens FCM.

1. Adicionar permissões: Clique no botão "Adicionar permissões"
2. Filtrar permissões: procure por "Firebase Cloud Messaging API Admin"
3. Selecione a permissão: Marque cloudmessaging.messages.create
4. Adicionar à função: clique no botão "Adicionar"
5. Criar função: clique em "Criar" para concluir a criação da função

Etapa 6: Atribuir conta de serviço Singular

Conceder acesso ao Singular

Atribua a função personalizada à conta de serviço do Singular para autorizar operações de rastreamento de desinstalação. Abrir página IAM: Selecione "IAM" no menu de navegação à esquerda

1. Abrir a página IAM: Selecione "IAM" no menu de navegação à esquerda
2. Conceder acesso: Clique no botão "Conceder acesso" na guia Permissões .
3. Adicionar principal: No campo "Novos principais", insira:

   singular-uninstall-tracking@singular-uninstall-tracking.iam.gserviceaccount.com

Atribuir função personalizada

Selecione a função "Rastreamento de desinstalação singular" criada nas etapas anteriores.

1. Selecionar função: Em "Atribuir funções", procure e selecione "Rastreamento de desinstalação singular"
2. Verificar configuração: Confirme se a configuração corresponde à captura de tela abaixo
3. Salvar: Clique no botão "Salvar" para aplicar as permissões

Configuração final:

Etapa 7: Configure as configurações do aplicativo Singular

Adicione o ID do projeto ao Singular

Insira o ID do seu projeto Firebase na configuração do aplicativo Singular para habilitar o rastreamento de desinstalações.

1. Abrir aplicativos Singular: Navegue até a página de aplicativos Singular
2. Selecione o aplicativo: escolha seu aplicativo Android na lista
3. Configurações avançadas: role até a seção Configurações avançadas
4. Rastreamento de desinstalação: localize a configuração de rastreamento de desinstalação
5. Insira o ID do projeto: Cole o ID do seu projeto Firebase da Etapa 3
6. Salvar: clique em Salvar para aplicar a configuração

Testando o rastreamento de desinstalação

Verifique se o rastreamento de desinstalação está configurado corretamente antes de lançar a atualização do aplicativo para produção.

Procedimento de teste

Etapas de validação

1. Instalar a versão de teste: Implante o aplicativo com o rastreamento de desinstalação ativado para testar o dispositivo
2. Inicie o aplicativo: abra o aplicativo para acionar a inicialização do SDK e o registro do token FCM
3. Verifique o registro do token: verifique os logs do SDK para confirmar o registro bem-sucedido do token FCM com o Singular
4. Aguarde o processamento em lote: aguarde 24 a 48 horas para que o Singular envie a primeira notificação silenciosa
5. Desinstalar o aplicativo: Remova o aplicativo do dispositivo de teste
6. Monitorar painel: verifique o painel do Singular após 24-48 horas para ver se houve algum evento de desinstalação

Verificação do log do SDK

Verifique o logcat do Android para mensagens do SDK Singular confirmando a configuração correta.

Mensagens de log esperadas:

D/SingularSDK: FCM token registered successfully
D/SingularSDK: Uninstall tracking enabled
D/SingularSDK: Token sent to Singular servers

Problemas comuns

API HTTP legada (obsoleta)

A API HTTP legada foi desativada em 22 de julho de 2024. Todas as implementações devem migrar para a API HTTP v1.

Migração necessária

Se o seu aplicativo usa atualmente a API HTTP legada com configuração de chave do servidor e ID do remetente , siga estas etapas de migração:

1. Revise a configuração atual: verifique se as configurações do aplicativo Singular mostram o campo "Chave do servidor" em vez de "ID do projeto"
2. Siga a configuração HTTP v1: Conclua todas as etapas na seção Configuração da API HTTP v1 acima
3. Atualize a configuração do aplicativo: substitua a chave do servidor pelo ID do projeto Firebase nas configurações do Singular
4. Teste a implementação: verifique se o rastreamento de desinstalação funciona com a nova configuração da API v1
5. Lance a atualização: Implante o aplicativo atualizado para os usuários de produção

Guia de migração: Migração da API HTTP v1 do Firebase

Benefícios da API HTTP v1

• Segurança aprimorada: usa tokens de acesso OAuth 2.0 de curta duração em vez de chaves de servidor estáticas
• Melhor suporte entre plataformas: estrutura de mensagens unificada para Android, iOS e web
• Substituições específicas da plataforma: personalize o comportamento das notificações por plataforma em uma única solicitação
• Preparação para o futuro: suporte contínuo do Firebase e novos recursos disponíveis apenas na v1
• Tratamento de erros aprimorado: respostas de erro mais detalhadas para solução de problemas

Analisando dados de desinstalação

Use os dados de desinstalação nos relatórios do Singular para otimizar o desempenho da campanha e identificar problemas de qualidade do tráfego.

Métricas disponíveis

Métricas de rastreamento de desinstalação

• Contagem de desinstalações: número total de desinstalações de aplicativos detectadas
• Taxa de desinstalação: porcentagem de instalações que resultaram em desinstalações
• Dias até a desinstalação: tempo médio entre os eventos de instalação e desinstalação
• Desinstalações por fonte: detalhamento das desinstalações por campanha, editor, criativo
• Análise de coorte: padrões de desinstalação em diferentes coortes de usuários

Casos de uso

Otimização de campanha:

• Identifique campanhas que geram tráfego de baixa qualidade com altas taxas de desinstalação .
• Compare as taxas de desinstalação entre diferentes fontes de tráfego
• Otimize estratégias de licitação com base na retenção prevista de usuários

Detecção de fraudes:

• Detecte padrões anormais de desinstalação que indiquem fraude de instalação
• Sinalize editores com taxas de desinstalação suspeitamente altas
• Monitore o tempo até a desinstalação para detectar sinais de tráfego de bots

Análise de retenção de usuários:

• Acompanhe a aderência e o envolvimento do aplicativo ao longo do tempo
• Correlacione as desinstalações com atualizações do aplicativo ou lançamentos de recursos
• Identifique os fatores que contribuem para a perda de usuários

Melhores práticas

Estratégias de otimização

• Defina referências: estabeleça limites aceitáveis para a taxa de desinstalação para diferentes tipos de campanha
• Monitore as tendências: acompanhe as taxas de desinstalação ao longo do tempo para identificar padrões sazonais ou anomalias
• Análise de segmentos: compare as taxas de desinstalação entre demografias, regiões geográficas e dispositivos dos usuários
• Janelas de atribuição: considere o momento da desinstalação ao avaliar o desempenho da campanha
• Pontuação de qualidade: incorpore as taxas de desinstalação nos modelos de pontuação de qualidade do tráfego