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

Acompanhe 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

A Singular detecta desinstalações de aplicativos enviando notificações push silenciosas via 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 da Singular registra os tokens FCM com os servidores da Singular
2. Notificações silenciosas: A Singular envia periodicamente notificações push silenciosas para os dispositivos registados
3. Feedback de entrega: FCM relata sucesso ou falha na entrega
4. Deteção de desinstalação: As entregas falhadas indicam a desinstalação da aplicação
5. Registo 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 ativado
• 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 de notificação explícita para geração de token FCM

Considerações importantes

Partilha com restrição de domínio

Se a sua Organização Google tiver a Partilha restritaao domínioactivada, conceda acesso à Organização Singular para ativar a funcionalidade de monitorização de desinstalações.

Etapas de configuração:

1. Acessar as políticas da organização: Navegue até a página Políticas da organização no Google Cloud Console
2. Selecionar recurso: Escolha a organização onde a política está configurada
3. Localizar restrição: Localize a restrição "Compartilhamento restrito de domínio"
4. Gerenciar política: Clique no botão "Manage policy" (Gerir política)
5. Adicionar 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 deteção de desinstalação.

Configuração da API HTTP v1 (recomendada)

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

Atualize para o SDK do Android 7.0 ou superior para habilitar a funcionalidade de rastreamento de desinstalação.

Configuração do Gradle:

dependencies {
    // Singular SDK do Android 7.x+
    implementation("com.singular.sdk:singular_sdk:12.6.2")
}

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

Etapa 2: Configurar o AndroidManifest.xml

Adicionar recetor FCM

Configure o manifesto do Android para receber notificações do FCM para deteção de desinstalação.

<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>
        
        <!-- Singular FCM Receiver Service -->
        <service
            android:name="com.singular.sdk.SingularFcmService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>

    </application>

</manifest>

Configuração detalhada do manifesto: Guia de rastreamento de desinstalação do SDK do Android

Etapa 3: Criar projeto do Firebase

Inicializar o Firebase

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

1. Abra o Console do Firebase: Navegue até o Console do Firebase
2. Criar projeto: Selecione ou crie um novo projeto do Firebase para seu aplicativo
3. Localize Configurações do projeto: Clique no ícone de engrenagem → Configurações do projeto
4. Copiar ID do projeto: Copie o ID do projeto da guia Geral (você digitará isso no Singular mais tarde)

Passo 4: Habilitar a API de mensagens da nuvem do Firebase

Ativar a API HTTP v1

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

1. Navegue até Mensagens na Nuvem: No Console do Firebase, vá para Configurações do projeto → aba Mensagens na nuvem
2. Habilitar API: Clique em "Ativar" ao lado de Firebase Cloud Messaging API (V1)
3. Verificar ativação: Confirme se o status da API é exibido como "Ativado"

Etapa 5: criar função de IAM personalizada

Configurar permissões da conta de serviço

Crie uma função IAM personalizada com permissões específicas para que o Singular envie notificações FCM para deteçã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. Abra as funções: Selecione "Roles" no menu de navegação esquerdo
3. Criar função: Clique no botão "Create Role" (Criar função)
4. Configurar detalhes da função:
   • Título: Singular Uninstall Tracking
   • ID: singular_uninstalls
   • Fase de lançamento da função: General Availability

Adicionar permissão necessária

Conceder permissão à função personalizada para enviar mensagens FCM.

1. Adicionar permissões: Clique no botão "Add Permissions" (Adicionar permissões)
2. Filtrar permissões: Procurar por "Firebase Cloud Messaging API Admin"
3. Selecionar permissão: Verificar cloudmessaging.messages.create
4. Adicionar à função: Clique no botão "Add" (Adicionar)
5. Criar função: Clique em "Create" (Criar) para concluir a criação da função

Passo 6: Atribuir conta de serviço Singular

Conceder acesso à Singular

Atribua a função personalizada à conta de serviço do Singular para autorizar operações de rastreamento de desinstalação.

1. Abra a página do IAM: Selecione "IAM" no menu de navegação esquerdo
2. Conceder acesso: Clique no botão "Grant Access" (Conceder acesso) na guia Permissions (Permissões)
3. Adicionar Principal: No campo "Novos principais", digite:

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

Assign Custom Role (Atribuir função personalizada)

Selecione a função "Singular Uninstall Tracking" criada nos passos anteriores.

1. Selecionar função: Em "Assign roles" (Atribuir funções), procure e selecione "Singular Uninstall Tracking" (Monitorização de desinstalação singular)
2. Verificar a configuração: Confirme se a configuração corresponde à captura de ecrã abaixo
3. Guardar: Clique no botão "Save" (Guardar) para aplicar as permissões

Configuração final:

Etapa 7: Configurar as definições do Singular App

Adicionar ID do projeto ao Singular

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

1. Abra o Singular Apps: Navegue até a página do Singular Apps
2. Selecionar aplicativo: Escolha seu aplicativo Android na lista
3. Configurações avançadas: Desloque-se para a secção Definições avançadas
4. Desinstalar rastreio: Localizar a configuração Desinstalar seguimento
5. Inserir ID do projeto: Cole o ID do 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 liberar o aplicativo atualizado para produção.

Procedimento de teste

Etapas de validação

1. Instalar a compilação de teste: Implantar o aplicativo com o rastreamento de desinstalação ativado no dispositivo de teste
2. Iniciar aplicativo: Abrir a aplicação para ativar a inicialização do SDK e o registo do token FCM
3. Verificar o registo do token: Verificar os logs do SDK para registro bem-sucedido do token FCM com o Singular
4. Aguardar o processo de lote: Aguarde de 24 a 48 horas para que o Singular envie a primeira notificação silenciosa
5. Desinstalar o aplicativo: Remover o aplicativo do dispositivo de teste
6. Monitorar painel de controle: Verificar o painel do Singular após 24-48 horas para o evento de desinstalação

Verificação de log do SDK

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

Mensagens de registo 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 herdada com a configuração de Chave do servidor e ID do remetente, siga estas etapas de migração:

1. Rever a configuração atual: Verifique se as definições da aplicação Singular mostram o campo "Chave do servidor" em vez de "ID do projeto"
2. Seguir a configuração HTTP v1: Conclua todas as etapas na seção Configuração da API HTTP v1 acima
3. Atualizar a configuração do aplicativo: Substituir 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. Atualização da versão: implantar o aplicativo atualizado para 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 mensagem unificada para Android, iOS e Web
• Substituições específicas da plataforma: Personalize o comportamento de notificação por plataforma em uma única solicitação
• Preparado para o futuro: Suporte contínuo ao Firebase e novos recursos disponíveis apenas na v1
• Tratamento de erros aprimorado: Respostas de erro mais detalhadas para solução de problemas

Análise de dados de desinstalação

Use dados de desinstalação em relatórios Singular para otimizar o desempenho da campanha e identificar problemas de qualidade de 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 para 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 cohort: Padrões de desinstalação em diferentes grupos de utilizadores

Casos de uso

Otimização de campanhas:

• Identificar campanhas que geram tráfego de baixa qualidade com altas taxas de desinstalação
• Comparar taxas de desinstalação entre diferentes fontes de tráfego
• Otimizar estratégias de licitação com base na retenção de utilizadores prevista

Deteção de fraude:

• Detetar padrões anormais de desinstalação que indicam fraude na instalação
• Sinalizar editores com taxas de desinstalação suspeitamente altas
• Monitorizar o tempo até à desinstalação para detetar sinais de tráfego de bots

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

• Acompanhar a aderência e o envolvimento do aplicativo ao longo do tempo
• Correlacionar desinstalações com actualizações de aplicações ou lançamentos de funcionalidades
• Identificar factores que contribuem para a rotatividade de utilizadores

Melhores práticas

Estratégias de otimização

• Definir parâmetros de referência: Estabelecer limites aceitáveis de taxa de desinstalação para diferentes tipos de campanha
• Monitorizar 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 com os dados demográficos, geográficos e dispositivos dos utilizadores
• Janelas de atribuição: Considere o momento da desinstalação ao avaliar o desempenho da campanha
• Pontuação de qualidade: Incorporar as taxas de desinstalação nos modelos de pontuação da qualidade do tráfego