Documento
Depois de integrar o Singular SDK na sua aplicação ou de criar uma integração servidor a servidor, é essencial verificar se o Singular recebe os dados antes de entrar em funcionamento com a nova versão.
Guia para |
desenvolvedores |
Pré-requisitos |
- Implemente o SDK do Singular ou configure a integração servidor a servidor (S2S) para seu aplicativo.
- Certifique-se de ter um dispositivo móvel para teste se planeja usar o Console de teste.
|
A Singular fornece três ferramentas principais para testar sua integração:
-
Console de teste: Teste os recursos em tempo real à medida que os implementa.
-
Exportar logs: Faça o download de dados no nível do usuário com um atraso de pelo menos uma hora.
-
Relatório de Auditoria: Identifica automaticamente quaisquer problemas na sua integração.
Utilizar a Consola de Testes
A Consola de Testes permite-lhe transmitir dados em tempo real e em direto, adicionando e selecionando um dispositivo de teste. Observe que ela não fornece relatórios históricos. Para começar, certifique-se de que tem o seguinte:
-
Um dispositivo de teste limpo: Utilize um dispositivo que nunca tenha tido a aplicação de teste instalada.
-
Uma lista de eventos e atributos para testar: Prepare os eventos e atributos que planeia verificar.
-
Para iOS: Tenha em atenção se o pedido de App Tracking Transparency (ATT) será apresentado, uma vez que isso determinará se utiliza o identificador IDFV ou IDFA para testar.
1 |
Adicionar um dispositivo de teste
Para adicionar um dispositivo ao Console de teste:
- Na plataforma Singular, vá para Ferramentas de desenvolvedor > Console de teste.
-
Clique em Adicionar dispositivo.
- Forneça o Tipo de dispositivo. Para Android, quando disponível, recomendamos o Google Advertising ID (GAID/aifa), AppSetID (asid) ou AndroidID (andi), por esta ordem. Para dispositivos iOS, recomendamos o uso do IDFA, quando disponível.
-
Forneça o seu ID do dispositivo.
Capturar a ID do dispositivo
Para Android, recomendamos a utilização do ID de publicidade do Google (GAID/aifa). O aplicativo Singular Device Assist(Android) pode ajudá-lo a encontrá-lo.
O aifa também é encontrado no LogCat do Android quando o registro para a configuração do Singular está ativado.
SingularConfig config = new SingularConfig(SdkKey, SdkSecret) .withLoggingEnabled() .withLogLevel(1);
Exemplo de saída do LogCat:
2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - andi : 8868adc2f7ffffff
2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - asid : 12dc3652-5e46-f2bb-a93a-b3c092ffffff
2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - aifa : 3bbc76b0-cebb-4a9f-b6ec-10ca1affffff
Para iOS, pode utilizar o IDFA quando a estrutura ATT está em vigor e o rastreio é permitido. Certifique-se de que a opção Aguardar autorização de rastreamento com intervalo de tempo limite também seja implementada. Para todas as outras instâncias, use o IDFV.
O IDFA pode ser capturado usando um dos métodos listados abaixo:
- Utilizar a aplicação Singular Device Assist(iOS) da App Store. Certifique-se de que dá permissão para o rastreio.
- Registo do IDFA na consola de depuração do Xcode
//Example in Swift
print("IDFA", ASIdentifierManager.shared().advertisingIdentifier.uuidString)
//Example in Objective-C
NSString *IDFA = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
NSLog(@"IDFA: %@", IDFA);
O IDFV pode ser capturado na consola de depuração do Xcode.
//Example in Swift
print("IDFV", UIDevice.current.identifierForVendor!.uuidString)
//Example in Objective-C
NSString *IDFV = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
NSLog(@"IDFV: %@", IDFV);
-
Adicione um nome de dispositivo distinto e clique em Guardar dispositivo.
|
2 |
Teste de inicialização
A primeira coisa a testar é se a integração do seu SDK foi inicializada com sucesso e é capaz de enviar informações para o Singular (ou seja, o evento que você está procurando é chamado: session). Isso permite que o Singular comece a rastrear a atribuição para este aplicativo!
Para testar a inicialização:
-
No Registo de Eventos, selecione o nome do seu dispositivo no menu pendente Dispositivos. Procure o indicador 🟢 Live.
- Inicialize o aplicativo a partir da sua plataforma de teste / abra o aplicativo.
-
Quando você vê um evento de sessão, você inicializou com sucesso o Singular SDK.
Como faço para ler o Registro de eventos no Console de teste?
Depois de ter registado um dispositivo e enviado alguns eventos, os eventos começam a aparecer no registo de eventos na página da Consola de Testes.
Clique numa linha para ver os detalhes completos do evento tal como foi enviado pela aplicação.
Porque é que não aparecem eventos no registo de eventos da Consola de Testes?
Se registou um dispositivo de teste e está a seguir o guia para testar a integração do SDK, mas não estão a aparecer linhas no Registo de Eventos, verifique novamente o seguinte:
-
A Consola de Testes só mostra eventos em direto, ou seja, quando está na página com um dispositivo selecionado e o indicador 🟢 Em direto. Não procura eventos históricos do dispositivo. Se disparar eventos antes de selecionar um dispositivo, este não aparecerá na consola.
- Certifique-se de que abriu a aplicação no dispositivo de teste (para ver uma sessão de utilizador).
- Certifique-se de que criou alguns eventos na aplicação (se quiser testar os seus eventos).
- Verifique novamente se introduziu o ID de dispositivo correto
- Verifique se está a utilizar o tipo de ID de dispositivo correto (no caso do iOS, se não viu uma mensagem ATT, não pode utilizar o IDFA)
Por que o evento _InstallReferrer está ausente ao testar um aplicativo com o Singular SDK 12.0.0 e superior?
A partir do Singular SDK 12.0.0, não é necessário testar o evento _InstallReferrer. Uma vez que seu aplicativo é enviado para a loja, nosso SDK colocará os dados _InstallReferrer na primeira sessão. Você só precisa ver se a sessão aparece no Console de teste.
Se estiver a utilizar versões mais antigas do SDK do Android, terá de continuar a verificar o evento _InstallReferrer na Consola de Testes.
Como faço para redefinir um dispositivo e limpar suas informações de atribuição para que eu possa usá-lo para testar a atribuição de instalação novamente?
Se pretender testar novamente a integração do SDK com o mesmo dispositivo, tem de remover todos os dados armazenados localmente em cache do dispositivo, para além de limpar a atribuição do dispositivo na plataforma Singular.
Etapas para dispositivos Android
- Feche o aplicativo e confirme que ele não está em execução (use Forçar parada no menu Configurações, se houver essa opção).
- Vá para o menu Configurações tocando no ícone de roda na janela de notificação ou no menu Aplicativos.
- Aceda a Aplicações, selecione a aplicação que está a testar, prima sem soltar a aplicação e selecione Informações da aplicação.
- Selecione Armazenamento e, em seguida, selecione Limpar cache e Limpar dados.
-
Na Consola de Testes Singular, selecione o dispositivo no menu pendente e clique no ícone Editar (Lápis). Na prateleira que se abre, clique em Eliminar dispositivo para que o nosso sistema elimine a atribuição deste dispositivo.
Etapas para dispositivos iOS
- Feche a aplicação e, em seguida, desinstale-a.
-
Abra o Console de teste, encontre seu dispositivo no menu suspenso e clique no ícone Editar. Na prateleira que se abre, clique em Excluir dispositivo para que nosso sistema exclua a atribuição desse dispositivo.
Sugestão: Testar com janelas de inatividade de reengajamento
A janela de inatividade é uma definição que determina quanto tempo o utilizador tem de estar inativo antes de ser elegível para a atribuição de reengajamento. Se estiver a testar a atribuição de reengajamento antes de lançar campanhas, uma janela de inatividade dificultar-lhe-ia a tarefa. É por isso que os dispositivos de teste (dispositivos que foram adicionados à Consola de Testes e têm o ícone do olho ativado) estão isentos da janela de inatividade.
Estou a testar com o IDFA e não consigo fazer com que o iOS apareça na consola de testes. O que é que eu faço?
Verifique novamente se o seu IDFA está correto. É possível fazer isso de várias maneiras:
- Use o aplicativo Sing ular Use o aplicativo Singular Device Assist (iOS) da App Store. Certifique-se de que dá permissão para o rastreio.
- Registar o IDFA na consola de depuração do Xcode
- Se você já fez um teste há mais de uma hora, pode ir para exportar logs e ver se houve algum evento capturado. É possível extrair o IDFA/IDFV dos logs de exportação. Ao extrair do registo de exportação, tente adicionar também "App Tracking Transparency status" ao relatório. 0 - Indeterminado, significa que o prompt ATT não foi mostrado (geralmente porque as configurações gerais o estão bloqueando ou houve um tempo limite). Pode ler mais aqui
Outras coisas que pode verificar:
-
Verificar as definições do dispositivo: Certifique-se de que o identificador de publicidade do dispositivo (IDFA) não foi limitado. Aceda a Definições Rastreio de privacidade no dispositivo e certifique-se de que a opção "Permitir que as aplicações peçam para rastrear" está activada. Certifique-se de que viu o aviso da ATT durante o teste. Se não o viu, então não estamos a rastrear o IDFA.
-
Repor o identificador de publicidade: Se o dispositivo já tiver sido utilizado para testes, reponha o identificador de publicidade. Aceda a Definições Rastreio de privacidade e reponha o IDFA.
-
Implementação correta: Verifique se o Singular SDK foi corretamente integrado ao seu aplicativo e se você está usando a versão mais recente do SDK.
-
Aguardar o aparecimento dos dados: Não deve haver um atraso no aparecimento de dados na consola de testes. Se a espera for superior a um minuto, é porque algo não foi configurado corretamente.
-
Revisar a inicialização do SDK: Confirme se o Singular SDK foi inicializado corretamente no código do seu aplicativo, particularmente no AppDelegate ou SceneDelegate, dependendo da arquitetura do seu aplicativo.
-
Verificar se há erros: Procure por quaisquer erros no console do Xcode que possam indicar problemas com a inicialização do SDK ou rastreamento de eventos.
Se você tiver seguido essas etapas e o problema persistir, talvez seja necessário revisar o guia de integração detalhado ou entrar em contato com o engenheiro de integração da Singular para obter mais assistência.
|
3 |
Testar recursos específicos
Testar ID de usuário personalizado
Se a integração do SDK enviar um ID de usuário personalizado para o Singular, veja como testá-lo.
- Registre o dispositivo no Console de teste.
- Abra o aplicativo.
- Se necessário, em seu aplicativo, acione uma ação que envie a ID de usuário (como fazer login). A natureza da ação depende da sua implementação.
-
No próximo evento enviado ao Singular, expanda os detalhes do evento no Console de teste e verifique se os detalhes incluem um valor para "custom_user_id".
Se a ID do usuário não aparecer:
- Verifique se o método que define a ID do usuário está realmente sendo chamado em seu aplicativo quando você deseja que ele seja.
- Você pode querer adicionar um evento Singular SDK e chamá-lo de "setting custom user id" para que o evento apareça no Console de teste.
Eventos de teste
Se você implementou o rastreamento de eventos ou o rastreamento de receita na integração do SDK, siga as instruções abaixo para testá-los.
Para saber mais sobre eventos, consulte:
Para cada evento que você implementou na integração do SDK:
-
Acione o evento a partir do aplicativo e verifique se ele aparece no log do console de teste com o nome que você deu ao evento.
-
Se estiver a enviar quaisquer dados adicionais com o evento, clique na linha do evento na Consola de Testes para expandir os detalhes do evento e certifique-se de que os dados estão incluídos em"Dados do evento".
Se o evento não aparecer, é possível que a aplicação tenha sido aberta antes de o dispositivo ter sido completamente registado na Consola de Testes. Verifique os registos de exportação para o evento.
Receita de teste
Para cada tipo de evento de receita que implementou na integração do SDK:
- Acione o evento de receita no aplicativo e verifique o log de eventos. Deve aparecer uma linha com o nome do evento.
Nota: Se não atribuiu um nome personalizado ao evento, este recebe o nome predefinido para eventos de receitas, "__iap__".
-
Clique na linha para a expandir e certifique-se de que a moeda ("pcc"), o montante ("r") e quaisquer outros detalhes do evento foram recebidos.
Teste o Deep Linking
Se você implementou o deep linking na integração do SDK, siga as instruções abaixo para testar a funcionalidade do deep linking.
Nota: Este artigo pressupõe que a sua organização está a utilizar o Singular Links.
1. Configurar um destino de teste
Na plataforma Singular, vá para Configurações > Aplicativos, encontre o aplicativo e adicione um destino de deep link.
O destino deve ser um dos destinos de deep link que o código do manipulador na integração do SDK pode reconhecer e manipular.
2. Criar um link para testar
Agora que tem um destino para o qual criar uma ligação, pode criar uma ligação direta.
- Vá para Atribuição > Gerenciar links e selecione o aplicativo na barra lateral.
- Clique em Criar link.
- Em Tipo de link, selecione "Fonte personalizada" e, em Nome da fonte, selecione "E-mail".
- Dê um nome ao link.
- Clique na secção Definições da ligação e redireccionamentos para a expandir.
- Selecione o destino que acabou de criar na lista pendente Deep Link.
- Na caixa de texto Fallback Destination for Other Platforms (Destino alternativo para outras plataformas ), introduza o URL de um Web site.
-
Clique em Generate (Gerar ) e copie o link do campo Click-Through Tracking Link (Link de rastreamento de cliques).
3. Teste o link
Para testar o link:
- Certifique-se de que a aplicação está instalada no seu dispositivo de teste.
- Envie por correio eletrónico a ligação copiada para o seu dispositivo de teste.
- A partir do dispositivo, abra o e-mail e clique na ligação. A aplicação deve abrir e apresentar a página ou o conteúdo pretendido.
- Se você estiver usando o Console de teste do SDK durante o teste, deverá ver o Deep Link nos argumentos da sessão:
Maneira alternativa de testar o link (somente Android):
Testar os deep links do Android usando o ADB (Android Debug Bridge) é uma prática comum para verificar se seu aplicativo lida com os deep links corretamente. Aqui está um guia passo a passo sobre como configurar e usar o ADB para testes de deep link:
Pré-requisitos
Testando Deep Links com ADB
-
Use o ADB para enviar o Deep Link: Para testar um deep link, use o comando adb shell am start. Esse comando simula o clique em um deep link em um navegador ou outro aplicativo.
A sintaxe geral é:
adb shell am start -W -a android.intent.action.VIEW -d "your_deep_link_url"
-
No terminal do computador, acione o link:
adb shell am start -W -a android.intent.action.VIEW -d "https://seteam.sng.link/Bnuq6/i428?_dl=androidkotlinapplication%3A%2F%2Fmy_deeplink"
Resolução de problemas
"Quando meu aplicativo já está em execução, um link direto abre uma nova instância do aplicativo em vez de alternar para a existente." Para evitar isso, edite seu arquivo de manifesto e adicione o seguinte à sua atividade:
android:launchMode="singleTask"
Consulte a documentação <activity> do Google para obter mais informações sobre as opções launchMode.
Testar o Deferred Deep Linking
Para confirmar que o deferred deep linking está ativado:
-
Verifique o evento da sessão no Console de teste.
- Configure um destino de teste e um link conforme explicado acima em Testar links diretos.
- Desinstale o aplicativo do seu dispositivo de teste.
- Redefina o identificador de publicidade do dispositivo.
- Adicione o novo identificador ao Console de teste.
-
Envie o link direto por e-mail para o dispositivo e clique no link.
-
O link deve levá-lo para a loja de aplicativos. Nota: Se estiver a testar numa compilação local, não instale a versão da Loja, mas carregue a aplicação a partir do Android Studio ou do Xcode. Depois de instalar a aplicação e de a abrir, deverá ver a página ou o conteúdo pretendido.
- Se estiver a utilizar a Consola SDK para o teste, deverá encontrar o valor da ligação profunda diferida no primeiro evento de sessão.
Teste de rastreamento de desinstalação
Se você implementou o rastreamento de desinstalação na integração do seu SDK, siga as instruções abaixo para testá-lo.
Testar o rastreamento de desinstalação é mais complicado do que testar outras funções do SDK, porque o Singular depende dos serviços do Google/iOS para relatar a desinstalação, e o processo leva algum tempo. Não é possível ver o evento de desinstalação na plataforma Singular em tempo real e não é possível usar o Console de teste para isso.
Antes de testar, certifique-se de que está enviando seu token FCM/APNS para a Singular (consulte SDK do Android: rastreando desinstalações e SDK do iOS: rastreando desinstalações).
Além disso, verifique se você inseriu a chave do servidor FCM (para Android) ou o certificado push do iOS na página Configuração do aplicativo.
Para testar o rastreamento de desinstalação:
- Usando um dispositivo real (não um emulador), instale o aplicativo no dispositivo.
- Abra a aplicação para que a instalação seja registada.
- Desinstale o aplicativo.
-
Para verificar se o Singular recebeu o evento de desinstalação, você tem várias opções:
-
Exportar os registos de atribuição (registos de eventos) e encontrar o evento de desinstalação. Pode levar alguns dias para que ele apareça nos logs.
- Se tiver configurado postbacks para serem enviados para o seu sistema de BI interno, pode receber um postback sobre a desinstalação.
- Pode contactar o suporte da Singular ou o seu Gestor de Sucesso do Cliente para o ajudar a validar o seguimento da desinstalação.
Observação: Enquanto espera para validar o evento de desinstalação, não redefina a ID do dispositivo e não reinstale o aplicativo.
|
Nota: A consola de testes não suporta aplicações iOS TestFlight. Uma compilação do TestFlight redefine o IDFV em cada inicialização de aplicativo e os eventos ao vivo não podem ser capturados.
Usando os logs de exportação
Você também pode usar Atribuição > Exportar logs para verificar os resultados do teste com um atraso. A funcionalidade Exportar registos permite-lhe descarregar manualmente dados ao nível do utilizador, tais como Conversões (instalações), Eventos, etc.
Melhores práticas:
- Antes de obter os dados, verifique se a Data, a Aplicação e o site estão selecionados corretamente.
- Os dados nos logs de exportação estão cerca de 3 horas atrasados.
- Para obter mais ajuda, consulte esta FAQ.
Executando uma auditoria de SDK
A Singular oferece um relatório de auditoria de SDK que testa suas integrações de SDK e S2S para ver se elas estão implementadas corretamente. A auditoria gera uma lista de todos os problemas encontrados, com dicas de como resolvê-los. Para usar o relatório de auditoria do SDK:
1 |
Executar um relatório de auditoria do SDK
Aceda a Ferramentas de desenvolvimento > Consola de testes e clique em Executar auditoria no canto superior direito.
|
2 |
Descarregue o relatório e corrija os problemas relevantes
Quando o relatório terminar de ser executado, pode descarregá-lo em formato CSV.
O relatório é uma lista de problemas encontrados nas suas integrações SDK e S2S. Nem todos os problemas são críticos ou relevantes, dependendo das funcionalidades que implementou.
Analise os problemas no relatório e corrija-os de acordo com as sugestões no campo Descrição do erro.
Para problemas do tipo aviso/informação: Verifique o Nome de validação e veja se se trata de um recurso opcional do SDK que você optou por não implementar, como o deferred deep linking (DDL). Se for esse o caso, pode ignorar a mensagem de erro.
Como é que a auditoria do SDK funciona e em que dados é executada?
A auditoria do SDK analisa os dados recebidos das suas aplicações nos últimos 3 dias. Verifica se os dados têm o aspeto esperado, por exemplo:
- Se o aplicativo está relatando sessões de usuário (essa é a funcionalidade mais básica de uma integração SDK/S2S e é o que permite que o Singular rastreie a atribuição)
- Se o aplicativo está relatando eventos e receitas in-app
- Se a receita é relatada usando as melhores práticas
- Se o deferred deep linking está habilitado
Como posso ler o relatório de auditoria do SDK?
O relatório é uma lista de problemas que foram encontrados nas suas integrações SDK e S2S.
Coluna |
Descrição da coluna |
Nome do aplicativo |
O nome do aplicativo conforme configurado no Singular. |
Pacote de aplicativos |
O pacote de aplicativos conforme configurado no Singular, por exemplo, com.example.appname. |
Plataforma |
iOS, Android ou Amazon. |
Versão do aplicativo |
O número da versão do aplicativo, se houver. |
Nome da validação |
A área da integração em que foi encontrado um problema, por exemplo, "ID de utilizador personalizado" ou "Eventos de receita". |
Tipo de problema |
A gravidade do problema:
-
Erro: Este problema impede que a integração funcione e é necessário corrigi-lo antes de colocar a aplicação em funcionamento. Por exemplo, o Singular não está a receber sessões de utilizador da aplicação. Sem sessões de utilizador, não podemos efetuar a atribuição.
-
Aviso: A integração pode funcionar sem isso, mas você deve corrigi-lo se quiser seguir as práticas recomendadas e obter o máximo do rastreador de atribuição Singular. Por exemplo, seu aplicativo não está enviando um ID de usuário personalizado. O ID de usuário personalizado é um recurso opcional, mas altamente recomendado.
-
Informações: Este problema diz respeito à funcionalidade opcional que pode ter optado por não implementar na sua integração. Por exemplo, o deferred deep linking (DDL) não está ativado na sua aplicação. A DDL pode simplesmente não ser relevante para a sua estratégia de marketing.
|
Descrição do erro |
Mais informações sobre o problema e como corrigi-lo. |
|