Pré-requisitos de integração do SDK
Etapas preliminares essenciais necessárias antes de qualquer integração do Singular SDK, abrangendo planejamento, registro de aplicativo, configuração de domínio e preparação para testes.
Etapas preliminares necessárias: As etapas a seguir são necessárias para qualquer integração do Singular SDK.
Saiba como planejar a integração do SDK, registrar aplicativos para desenvolvimento, criar domínios para links de rastreamento e preparar fluxos de trabalho de teste durante e após a implementação.
| Público-alvo | Equipes de negócios, equipes de marketing, equipes de desenvolvimento |
| Pré-requisitos | Acesso à conta Singular, ID do pacote de aplicativos, definições de KPI de marketing |
Visão geral da integração
Colaboração multifuncional
A integração bem-sucedida do Singular SDK requer a colaboração entre as equipes de marketing, negócios e desenvolvimento para definir os requisitos, configurar o rastreamento e validar a implementação.
Responsabilidades da equipa:
| Equipe | Responsabilidades |
|---|---|
| Marketing/negócios |
|
| Desenvolvimento |
|
Etapa 1: Planejar a integração do SDK
Antes de iniciar a integração do SDK, as equipas de marketing e comerciais devem responder a questões-chave que permitam à equipa de desenvolvimento implementar as caraterísticas e funcionalidades adequadas do SDK.
Conformidade com a privacidade das crianças
Aplicações dirigidas a crianças
Questão: Esta aplicação é explicitamente dirigida a crianças?
As aplicações dirigidas a crianças devem estar em conformidade com as políticas da Play Store e da App Store que salvaguardam a privacidade das crianças. A Singular oferece SDKs especializados para conformidade.
Solução recomendada: Use os SDKs de aplicativos para crianças da Singular, que ajudam a cumprir as políticas de privacidade ao não capturar identificadores de dispositivos.
Configuração de Deep Linking
Manuseio de links profundos
Questão: O aplicativo manipulará links profundos?
O deep linking permite direcionar os usuários para conteúdo específico dentro do aplicativo a partir de fontes externas, como campanhas de marketing, notificações push ou páginas da Web.
Requisitos de implementação:
- Pré-requisitos: Siga os Pré-requisitos do Singular Linkspara configuração de domínio e plataforma
- Manipulador de links profundos: Implemente o manipulador no código conforme explicado no guia SDK relevante (iOS, Android, React Native, etc.)
- Teste: Valide a funcionalidade do deep link usando o Console de teste e os procedimentos de teste manual
Estratégia de rastreamento de eventos
Planeamento de eventos na aplicação
Questão: A aplicação irá monitorizar os eventos do utilizador?
A Singular recolhe dados de eventos in-app para analisar o desempenho da campanha e medir KPIs. A estratégia de eventos deve estar alinhada com os objectivos de marketing e com a medição do valor do utilizador.
Benefícios do evento padrão
A Singular suporta uma variedade de eventos padrãocomumente usados em todas as verticais e frequentemente suportados por redes de anúncios para relatórios e otimização.
Vantagens:
- Reconhecimento automático: A Singular reconhece eventos padrão automaticamente e adiciona à lista de eventos sem definição manual
- Suporte de parceiros: As redes de anúncios suportam eventos padrão para otimização de campanhas e relatórios
- Alinhamento com o sector: Nomeação consistente entre plataformas e parceiros
- Melhores práticas: Abordagem recomendada sempre que os eventos correspondem a definições padrão
Atributos de eventos padrão
Para cada evento padrão, passe os atributos padrão recomendados para captura completa de dados e compatibilidade com parceiros.
Exemplo: O evento sng_content_view (o utilizador visualiza o produto) deve incluir:
-
sng_attr_content_type- Tipo de conteúdo visualizado -
sng_attr_content_id- Identificador de conteúdo único -
sng_attr_content- Descrição ou nome do conteúdo
Recursos de estratégia de eventos
As equipas de UA/marketing/negócio devem compilar uma lista de eventos com base nos KPIs de marketing utilizando os seguintes recursos:
- Como acompanhar eventos na aplicação- Guia de planeamento e implementação de eventos
- Eventos Singular Standard: Lista completa e eventos recomendados por vertical- Referência completa de eventos padrão
Nomes de eventos específicos da plataforma
Nota do desenvolvedor: a integração do SDK pode exigir formatos de nome de evento/atributo ligeiramente diferentes (todas as letras maiúsculas, sem sublinhados, etc.) com base na plataforma de desenvolvimento.
Listas específicas da plataforma:
Definição de evento personalizado
Se os eventos não corresponderem aos eventos padrão do Singular, defina eventos personalizados com nomes personalizados para requisitos de rastreamento específicos.
Diretrizes para eventos personalizados:
- Limite de caracteres: Máximo de 32 caracteres
- Idioma: Recomendar nomes em inglês para compatibilidade com parceiros de rede de anúncios que recebem eventos da Singular
- Convenção de nomenclatura: Use nomes descritivos e consistentes para maior clareza e manutenção
- Documentação: Manter o catálogo de eventos documentando os nomes e as finalidades dos eventos personalizados
Escopo do rastreamento de eventos
Melhores práticas: Enviar eventos para o Singular somente se necessário para fins relacionados a marketing. Se o evento não for significativo como KPI de desempenho da campanha ou indicador de valor do usuário, esse evento não deve ser rastreado pela Singular.
Critérios de seleção de eventos:
- Relevância de marketing: O evento fornece insights para a otimização da campanha
- Medição de KPI: O evento contribui para os principais indicadores de desempenho
- Valor para o utilizador: O evento indica o envolvimento ou a monetização do utilizador
- Otimização de parceiros: Evento usado por redes de anúncios para segmentação de campanhas
Configuração específica do iOS
Implementação de SKAdNetwork
Pergunta (iOS): O aplicativo implementará SKAdNetwork?
A SKAdNetwork permite a atribuição com preservação da privacidade no iOS sem exigir permissão de rastreamento no nível do usuário. O Singular suporta dois modos de implementação.
Modos de SKAdNetwork:
- Modo gerenciado: O Singular atualiza automaticamente os valores de conversão com base em regras predefinidas
- Modo manual: A sua aplicação actualiza os valores de conversão diretamente utilizando os métodos SDK
Transparência no rastreamento de aplicativos
Pergunta (iOS): O aplicativo solicitará permissão do usuário para compartilhar informações de rastreamento (ATT)?
A Singular recomenda exibir o prompt ATT porque o opt-in do usuário permite o compartilhamento da ID do dispositivo (IDFA), melhorando a precisão da atribuição da instalação.
Requisito de configuração: Se exibir o prompt ATT, configure o SDK para atrasar a inicialização do Singular até que o usuário responda ao prompt. Isso garante que a atribuição capture o status correto da autorização de rastreamento.
Implementação do ATT:
- Tempo do prompt: Exibir o prompt ATT antes de inicializar o SDK Singular
- Configuração do SDK: Utilizar as opções de configuração do SDK para aguardar a resposta da ATT
- Captura de IDFA: Se o utilizador der permissão, o IDFA é recolhido para atribuição determinística
- Atribuição de Fallback: Se o utilizador recusar a autorização, a atribuição utiliza a impressão digital e o IDFV
Passo 2: Registar a aplicação de desenvolvimento
Registre o aplicativo de desenvolvimento/teste na plataforma Singular usando uma ID de pacote separada do aplicativo de produção para manter a separação de dados durante o teste.
Estratégia de ID de pacote
Desenvolvimento vs. Produção
A mesma chave SDK e a mesma chave secreta são usadas para aplicativos de produção e teste. Uma vez que os dados são salvos no Singular, eles não podem ser excluídos.
Abordagem recomendada: Use um identificador de pacote diferente para o aplicativo de teste para manter os dados separados do aplicativo de produção. Altere a ID do pacote para a versão de produção antes de lançar o aplicativo nas lojas.
Exemplo de ID de pacote:
| Ambiente | ID do pacote |
|---|---|
| Produção |
com.myapp
|
| Desenvolvimento/Teste |
com.myapp.dev
|
Etapas do registo da aplicação
Configuração da plataforma
Procedimento de registo
- Navegar para Aplicativos: Na plataforma Singular, vá para Configurações → Aplicativos e clique em Adicionar novo aplicativo
- Introduzir o nome da aplicação: Introduzir o nome da aplicação para a aplicação de desenvolvimento (recomenda-se a utilização do Bundle ID para maior clareza)
- Selecionar Plataforma: Selecione o sistema operacional correspondente à plataforma do aplicativo (iOS ou Android)
- Configurar ID do pacote: selecione a opção ID do pacote e introduza a versão de desenvolvimento do identificador do pacote e, em seguida, guarde a aplicação
-
Apenas iOS - Definições avançadas: Depois de guardar a aplicação, clique na seta junto ao nome da aplicação para ver os detalhes
- Alternar a opção Mostrar definições avançadas
- Adicionar ID da equipa (necessário para ligações universais)
- Adicionar esquema (necessário para ligações diretas)
Actualizações pós-desenvolvimento
Depois de terminar o desenvolvimento e os testes:
- Atualizar a ID do pacote: Alterar a ID do pacote para a versão de produção na configuração da aplicação
- Configuração da aplicação de produção: A equipa de marketing adiciona a aplicação de produção seguindo as instruções das FAQ de configuração da aplicação
Importante: Certifique-se de que o ID do pacote é atualizado para o valor de produção antes de lançar a aplicação na App Store ou na Play Store. IDs de pacote incompatíveis impedem a atribuição e o rastreamento adequados.
Etapa 3: Criar domínio de link
Estabeleça um domínio personalizado para links de rastreamento Singular, permitindo URLs de campanha de marca e funcionalidade de link profundo.
Estrutura do domínio do link
Formato de link singular
Os Singular Links (links de rastreamento Singular) seguem uma estrutura padronizada com subdomínio personalizado:
https://[SUBDOMAIN].sng.link/[PARAMETERS]
Exemplo: Para a aplicação denominada "Jewel Rush", crie o domínio jewelrush.sng.link, permitindo ligações de seguimento com estrutura:
https://jewelrush.sng.link/[PARAMETERS]Estratégia de domínio
Um ou vários domínios
As organizações podem utilizar um único domínio para todos os links ou criar vários domínios para diferentes fins (aplicações, marcas, campanhas, etc.).
Requisito: É necessário pelo menos um domínio antes de usar Links de rastreamento únicos. A equipa de marketing deve participar na seleção do domínio, uma vez que este aparece nas campanhas de marketing e nos materiais dirigidos ao utilizador.
Casos de uso de domínio:
- Domínio único: Um domínio para todos os links de rastreamento em aplicativos e campanhas
- Específico do aplicativo: domínio separado por aplicativo para clareza da marca
- Específico da campanha: Domínios diferentes para diferentes tipos de campanha
- Geográfico: Domínios regionais para campanhas localizadas
Configuração de domínio iOS
Configuração de domínios associados
Ao integrar o Singular SDK em aplicativos iOS, adicione o domínio do link nas Configurações de Domínio Associado do Xcode para suporte a Links Universais.
Formato do domínio associado:
applinks:[DOMAIN].sng.linkExemplo:
applinks:jewelrush.sng.linkRecursos adicionais: Para obter instruções completas de instalação e configuração do domínio, consulte Pré-requisitos do Singular Links.
Etapa 4: Planejar o teste de integração
Valide a funcionalidade de integração SDK/S2S antes de lançar o aplicativo usando as ferramentas de teste e os procedimentos de verificação do Singular.
Estratégia de teste
Fases de teste
Os testes abrangentes ocorrem em duas fases: durante a implementação para validação em tempo real e após a implementação para verificação completa da integração.
Ferramentas de validação em tempo real
Teste os recursos conforme implementados usando ferramentas de validação em tempo real que fornecem feedback imediato.
Consola de testes
Utilize a Consolade Testes para testar manualmente diferentes funcionalidades do SDK em tempo real, à medida que são implementadas.
Benefícios da Consola de Testes:
- Feedback em tempo real: Validação imediata de chamadas SDK e transmissão de dados
- Funcionalidade por funcionalidade: Teste recursos individuais de forma incremental durante o desenvolvimento
- Suporte de depuração: Identificação imediata de problemas de configuração e de dados
- Rastreamento de sessão: Verifique a inicialização da sessão e o rastreamento de eventos
Ferramentas de depuração de terceiros
Abordagem de teste alternativa usando ferramentas de proxy para inspeção e validação de tráfego.
Configuração do Charles Proxy:
- Instalar o Charles Proxyou uma ferramenta de inspeção de rede semelhante
- Habilitar proxy SSL para inspeção de tráfego HTTPS
- Verificar se os dados Singular foram acionados no momento correto com os parâmetros corretos
- Validar chamadas de ponto de extremidade da API e códigos de resposta
Ferramentas de validação abrangentes
Após a conclusão da implementação, utilize ferramentas automatizadas e manuais para a verificação completa da integração.
Relatório de auditoria SDK
Execute o relatório de auditoria do SDKpara identificar automaticamente problemas de integração e receber soluções recomendadas.
Caraterísticas do relatório de auditoria:
- Deteção automática: Identifica funcionalidades SDK em falta ou mal configuradas
- Validação de melhores práticas: Verifica a implementação em relação às recomendações da Singular
- Recomendações acionáveis: Fornece soluções específicas para problemas identificados
- Cobertura abrangente: Verifica todos os recursos e configurações do SDK
Verificação dos registos de exportação
Faça o download de dados no nível do usuário usando a página Export Logspara revisar todos os dados transmitidos com sucesso do aplicativo para o Singular.
Detalhes dos logs de exportação:
- Formato dos dados: Arquivo CSV com dados completos de nível de usuário
- Tempo: Aproximadamente 30 minutos antes dos dados estarem disponíveis
- Validação: Verificar eventos, sessões e dados de atribuição
- Depuração: Identificar eventos em falta ou dados incorrectos
Teste de links profundos
Teste os links profundosseguindo as instruções em Como testar a integração do SDK Singular.
Casos de teste de links profundos:
- Links universais: Testar links universais do iOS e links de aplicativos do Android
- Esquemas personalizados: Verificar o tratamento de esquema de URL personalizado
- Deep Links diferidos: Teste os links clicados antes da instalação do aplicativo
- Parâmetros de campanha: Validar a passagem de parâmetros e a atribuição
Verificação de atribuição
Use a API Attribution Details para consultar os detalhes de atribuição do dispositivo após o teste. Dados de atribuição disponíveis aproximadamente 4-6 minutos após o evento.
Saiba como verificar a atribuição usando o ponto de extremidade Attribution Details.
Etapas de verificação de atribuição:
- Executar teste: instalar o aplicativo e concluir a jornada do usuário de teste
- Aguardar o processamento: Aguarde de 4 a 6 minutos para o processamento da atribuição
- Consultar API: Use a API Attribution Details com o identificador de dispositivo
- Verificar resultados: Confirmar a atribuição à campanha e fonte corretas
Recursos adicionais de teste
Guia de teste completo
Para obter procedimentos de teste abrangentes, práticas recomendadas e solução de problemas, consulte Como testar a integração do SDK Singular.
Lista de verificação de testes:
- O Console de teste valida as chamadas de SDK em tempo real
- O Relatório de Auditoria do SDK confirma a integração completa
- Logs de exportação verificam a transmissão de dados
- Os links diretos funcionam corretamente em todos os cenários
- A atribuição corresponde à fonte de campanha esperada
- Eventos rastreados com nomes e atributos corretos
- Os eventos de receita capturam o valor e a moeda
Próximos passos
Depois de concluir os pré-requisitos, prossiga com a integração do SDK específico da plataforma ou com a implementação do S2S.
Guias de integração de SDK
Recursos adicionais
- Perguntas frequentes sobre configuração de aplicativos- Configuração e instalação de aplicativos de produção
- Pré-requisitos do Singular Links- domínio de link e configuração de deep linking
- Referência de eventos padrão- Lista completa de eventos e atributos padrão
- Teste da integração do SDK- Procedimentos completos de teste e validação