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.

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.

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 eliminar/remover um dispositivo da consola?

Eliminar um dispositivo

Para eliminar um dispositivo da Lista de seguimento, clique no ícone Editar e, na prateleira que aparece, clique em Eliminar dispositivo. Isso limpará todos os logs de eventos da página, e o Singular excluirá os dados internos sobre a atribuição do dispositivo.

Veja também: 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?

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.

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

Instalar o ADB: Certifique-se de ter o ADB instalado. Ele está incluído nas ferramentas da plataforma Android SDK, que podem ser baixadas do site do desenvolvedor do Android.
Habilitar as Opções do desenvolvedor: No seu dispositivo Android, active as Opções de Programador e a depuração USB.
Aceda a Definições > Acerca do telefone e toque no número de compilação sete vezes para ativar as Opções de programador.
Aceda a Definições > Opções de programador e active a depuração USB.
Ligar o dispositivo: Ligue o seu dispositivo Android ao computador através de USB. Certifique-se de que é reconhecido pelo ADB, executando:
No terminal do seu computador, execute:
```
adb devices
```
Este comando deve listar o seu dispositivo.

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:

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.

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?

Screen_Shot_2021-11-11_at_18.28.27.png

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.

Como testar a integração do seu SDK Singular