Pré-requisitos para integração do SDK
Etapas preliminares essenciais necessárias antes de qualquer integração do SDK da Singular, cobrindo planejamento, registro de aplicativos, configuração de domínio e preparação para testes.
Etapas preliminares obrigatórias: As etapas a seguir são necessárias para qualquer integração do SDK da Singular.
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 testes 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, Bundle ID do aplicativo, definições de KPIs de marketing |
Visão geral da integração
Colaboração interfuncional
Uma integração bem-sucedida do SDK da Singular exige colaboração entre as equipes de marketing, negócios e desenvolvimento para definir requisitos, configurar o rastreamento e validar a implementação.
Responsabilidades das equipes:
| Equipe | Responsabilidades |
|---|---|
| Marketing/Negócios |
|
| Desenvolvimento |
|
Etapa 1: Planejar a integração do SDK
Antes de iniciar a integração do SDK, as equipes de marketing e negócios devem responder às principais perguntas que permitirão à equipe de desenvolvimento implementar os recursos e funcionalidades adequados do SDK.
Conformidade com privacidade infantil
Aplicativos direcionados a crianças
Pergunta: Este aplicativo é direcionado explicitamente a crianças?
Os aplicativos direcionados a crianças devem estar em conformidade com as políticas da Play Store e da App Store que protegem a privacidade das crianças. A Singular oferece SDKs especializados para conformidade.
Solução recomendada: Use os SDKs da Singular para aplicativos infantis, que ajudam a cumprir as políticas de privacidade ao não capturar identificadores de dispositivos.
Configuração de deep linking
Manipulação de deep links
Pergunta: O aplicativo irá manipular deep links?
O deep linking permite direcionar usuários a 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 Links para configuração de domínio e plataforma.
- Manipulador de deep link: Implemente o manipulador no código conforme explicado no guia do SDK correspondente (iOS, Android, React Native, etc.).
- Testes: Valide a funcionalidade de deep linking usando o Testing Console e procedimentos de teste manual.
Estratégia de rastreamento de eventos
Planejamento de eventos no aplicativo
Pergunta: O aplicativo irá rastrear eventos de usuário?
A Singular coleta dados de eventos no aplicativo para analisar o desempenho de campanhas e medir KPIs. A estratégia de eventos deve estar alinhada com os objetivos de marketing e a medição de valor do usuário.
Benefícios dos eventos padrão
A Singular suporta uma variedade de eventos padrão comumente usados em diferentes 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 os adiciona à lista de eventos sem definição manual.
- Suporte de parceiros: As redes de anúncios suportam eventos padrão para otimização e relatórios de campanhas.
- Alinhamento com o setor: Nomenclatura consistente entre plataformas e parceiros
- Melhores práticas: Abordagem recomendada sempre que os eventos correspondem às 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 (usuário visualiza produto) deve incluir:
-
sng_attr_content_type- Tipo de conteúdo visualizado -
sng_attr_content_id- Identificador único do conteúdo -
sng_attr_content- Descrição ou nome do conteúdo
Recursos de estratégia de eventos
As equipes de UA/marketing/negócios devem compilar a lista de eventos com base nos KPIs de marketing usando os seguintes recursos:
- Como rastrear eventos no aplicativo - Guia de planejamento e implementação de eventos
- Eventos padrão da Singular: lista completa e eventos recomendados por vertical - Referência completa de eventos padrão
Nomes de eventos específicos por plataforma
Nota para desenvolvedores: A integração do SDK pode exigir formatos de nomes de eventos/atributos ligeiramente diferentes (todas as letras maiúsculas, sem sublinhados, etc.) com base na plataforma de desenvolvimento.
Listas por plataforma:
Definição de eventos personalizados
Se os eventos não correspondem aos eventos padrão da Singular, defina eventos personalizados com nomes próprios para requisitos de rastreamento específicos.
Diretrizes para eventos personalizados:
- Limite de caracteres: Máximo de 32 caracteres
- Idioma: Recomenda-se usar nomes em inglês para compatibilidade com parceiros de redes de anúncios que recebem eventos da Singular.
- Convenção de nomenclatura: Use nomenclatura descritiva e consistente para clareza e manutenção.
- Documentação: Mantenha um catálogo de eventos documentando os nomes e propósitos dos eventos personalizados.
Escopo do rastreamento de eventos
Melhor prática: Envie eventos à Singular somente se necessário para fins relacionados ao marketing. Se um evento não for significativo como KPI de desempenho de 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 para marketing: O evento fornece insights para otimização de campanhas.
- Medição de KPIs: O evento contribui para os indicadores-chave de desempenho.
- Valor do usuário: O evento indica engajamento ou monetização do usuário.
- Otimização de parceiros: O evento é usado por redes de anúncios para segmentação de campanhas.
Configuração específica do iOS
Implementação do SKAdNetwork
Pergunta (iOS): O aplicativo irá implementar o SKAdNetwork?
O SKAdNetwork permite atribuição com preservação de privacidade no iOS sem exigir permissão de rastreamento em nível de usuário. A Singular suporta dois modos de implementação.
Modos do SKAdNetwork:
- Modo gerenciado: A Singular atualiza automaticamente os valores de conversão com base em regras predefinidas.
- Modo manual: Seu aplicativo atualiza os valores de conversão diretamente usando métodos do SDK.
App Tracking Transparency (ATT)
Pergunta (iOS): O aplicativo irá solicitar permissão do usuário para compartilhar informações de rastreamento (ATT)?
A Singular recomenda exibir o prompt de ATT porque o opt-in do usuário permite o compartilhamento do ID do dispositivo (IDFA), melhorando a precisão da atribuição de instalações.
Requisito de configuração: Se exibir o prompt de ATT, configure o SDK para atrasar a inicialização da Singular até que o usuário responda ao prompt. Isso garante que a atribuição capture o status correto de autorização de rastreamento.
Implementação do ATT:
- Momento do prompt: Exiba o prompt de ATT antes de inicializar o SDK da Singular.
- Configuração do SDK: Use as opções de configuração do SDK para aguardar a resposta do ATT.
- Captura do IDFA: Se o usuário conceder permissão, o IDFA é coletado para atribuição determinística.
- Atribuição alternativa: Se o usuário negar a permissão, a atribuição usa fingerprinting e IDFV.
Etapa 2: Registrar o aplicativo de desenvolvimento
Registre o aplicativo de desenvolvimento/teste na plataforma Singular usando um Bundle ID separado do aplicativo de produção para manter a separação de dados durante os testes.
Estratégia de Bundle ID
Desenvolvimento vs. Produção
O mesmo SDK Key e Secret Key são usados tanto para os aplicativos de produção quanto de teste. Uma vez que os dados são salvos na Singular, eles não podem ser excluídos.
Abordagem recomendada: Use um Bundle Identifier diferente para o aplicativo de teste para manter os dados separados do aplicativo de produção. Altere o Bundle ID para a versão de produção antes de lançar o aplicativo nas lojas.
Exemplo de Bundle ID:
| Ambiente | Bundle ID |
|---|---|
| Produção | com.myapp |
| Desenvolvimento/Teste | com.myapp.dev |
Etapas de registro do aplicativo
Configuração da plataforma
Procedimento de registro
- Navegar até Apps: Na plataforma Singular, vá para Settings → Apps e clique em Add New App.
- Inserir o nome do aplicativo: Insira o nome do aplicativo de desenvolvimento (recomenda-se usar o Bundle ID para maior clareza).
- Selecionar a plataforma: Selecione o SO correspondente à plataforma do aplicativo (iOS ou Android).
- Configurar o Bundle ID: Selecione a opção Bundle ID, insira a versão de desenvolvimento do Bundle Identifier e salve o aplicativo.
-
Somente iOS - Configurações avançadas: Após salvar o aplicativo, clique na seta ao lado do nome do aplicativo para ver os detalhes.
- Ative a opção Show Advanced Settings.
- Adicione o Team ID (necessário para Universal Links).
- Adicione o Scheme (necessário para deep linking).
Atualizações pós-desenvolvimento
Após concluir o desenvolvimento e os testes:
- Atualizar o Bundle ID: Altere o Bundle ID para a versão de produção na configuração do aplicativo.
- Configuração do aplicativo de produção: A equipe de marketing adiciona o aplicativo de produção seguindo as instruções do FAQ de configuração de aplicativo.
Importante: Certifique-se de que o Bundle ID seja atualizado para o valor de produção antes de lançar o aplicativo na App Store ou Play Store. Bundle IDs incompatíveis impedem a atribuição e o rastreamento adequados.
Etapa 3: Criar o domínio do link
Estabeleça um domínio personalizado para os links de rastreamento da Singular, possibilitando URLs de campanha com marca própria e funcionalidade de deep linking.
Estrutura do domínio do link
Formato dos Singular Links
Os Singular Links (links de rastreamento da Singular) seguem uma estrutura padronizada com subdomínio personalizado:
https://[SUBDOMAIN].sng.link/[PARAMETERS]Exemplo: Para um aplicativo chamado "Jewel Rush", crie o domínio jewelrush.sng.link permitindo links de rastreamento com a seguinte estrutura:
https://jewelrush.sng.link/[PARAMETERS]Estratégia de domínio
Domínio único vs. múltiplos domínios
As organizações podem usar um domínio único para todos os links ou criar múltiplos domínios para diferentes finalidades (aplicativos, marcas, campanhas, etc.).
Requisito: É necessário pelo menos um domínio antes de usar os Singular Tracking Links. A equipe de marketing deve participar da seleção do domínio, pois ele aparecerá nas campanhas de marketing e materiais voltados ao usuário.
Casos de uso do domínio:
- Domínio único: Um domínio para todos os links de rastreamento em todos os aplicativos e campanhas
- Específico por aplicativo: Domínio separado por aplicativo para clareza de marca
- Específico por campanha: Domínios diferentes para tipos de campanha diferentes
- Geográfico: Domínios regionais para campanhas localizadas
Configuração de domínio no iOS
Configuração de domínios associados
Ao integrar o SDK da Singular em aplicativos iOS, adicione o domínio do link nas configurações de domínio associado do Xcode para suporte a Universal Links.
Formato do domínio associado:
applinks:[DOMAIN].sng.linkExemplo:
applinks:jewelrush.sng.linkRecursos adicionais: Para instruções completas de configuração do domínio, consulte os pré-requisitos do Singular Links.
Etapa 4: Planejar os testes de integração
Valide a funcionalidade de integração SDK/S2S antes de lançar o aplicativo usando as ferramentas de teste e procedimentos de verificação da Singular.
Estratégia de testes
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 à medida que são implementados usando ferramentas de validação em tempo real que fornecem feedback imediato.
Testing Console
Use o Testing Console para testar manualmente diferentes recursos do SDK em tempo real à medida que são implementados.
Benefícios do Testing Console:
- Feedback em tempo real: Validação imediata das chamadas do SDK e transmissão de dados
- Recurso por recurso: Teste recursos individuais de forma incremental durante o desenvolvimento
- Suporte a depuração: Identifique problemas de configuração e dados imediatamente
- Rastreamento de sessão: Verifique a inicialização de sessão e o rastreamento de eventos
Ferramentas de depuração de terceiros
Abordagem alternativa de teste usando ferramentas proxy para inspeção e validação de tráfego.
Configuração do Charles Proxy:
- Instale o Charles Proxy ou uma ferramenta de inspeção de rede similar.
- Ative o proxy SSL para inspeção de tráfego HTTPS.
- Verifique se os dados da Singular são acionados no momento correto com os parâmetros corretos.
- Valide as chamadas de endpoint da API e os códigos de resposta.
Ferramentas de validação abrangente
Após concluir a implementação, use ferramentas automatizadas e manuais para verificação completa da integração.
Relatório de auditoria do SDK
Execute o relatório de auditoria do SDK para identificar automaticamente problemas de integração e receber soluções recomendadas.
Recursos do relatório de auditoria:
- Detecção automática: Identifica recursos do SDK ausentes ou mal configurados.
- 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 os problemas identificados.
- Cobertura abrangente: Verifica todos os recursos e configurações do SDK.
Verificação com Export Logs
Baixe dados em nível de usuário usando a página Export Logs para revisar todos os dados transmitidos com sucesso do aplicativo para a Singular.
Detalhes do Export Logs:
- Formato de dados: Arquivo CSV com dados completos em nível de usuário
- Prazo: Aproximadamente 30 minutos antes dos dados ficarem disponíveis
- Validação: Verifique os dados de eventos, sessões e atribuição.
- Depuração: Identifique eventos ausentes ou dados incorretos.
Testes de deep linking
Teste os deep links seguindo as instruções em "Como testar sua integração do SDK da Singular".
Casos de teste para deep links:
- Universal Links: Teste iOS Universal Links e Android App Links.
- Esquemas personalizados: Verifique o tratamento de esquemas de URL personalizados.
- Deferred deep links: Teste links clicados antes da instalação do aplicativo.
- Parâmetros de campanha: Valide a passagem de parâmetros e a atribuição.
Verificação de atribuição
Use a API de detalhes de atribuição para consultar os detalhes de atribuição do dispositivo após os testes. Os dados de atribuição ficam disponíveis aproximadamente 4 a 6 minutos após o evento.
Saiba como verificar a atribuição usando o endpoint de detalhes de atribuição.
Etapas de verificação de atribuição:
- Executar o teste: Instale o aplicativo e conclua a jornada do usuário de teste.
- Aguardar o processamento: Aguarde 4 a 6 minutos para o processamento da atribuição.
- Consultar a API: Use a API de detalhes de atribuição com o identificador do dispositivo.
- Verificar os resultados: Confirme a atribuição à campanha e à fonte corretas.
Recursos adicionais de testes
Guia completo de testes
Para procedimentos de teste abrangentes, melhores práticas e solução de problemas, consulte Como testar sua integração do SDK da Singular.
Lista de verificação de testes:
- O Testing Console valida as chamadas do SDK em tempo real.
- O relatório de auditoria do SDK confirma a integração completa.
- O Export Logs verifica a transmissão de dados.
- Os deep links funcionam corretamente em todos os cenários.
- A atribuição corresponde à fonte de campanha esperada.
- Os eventos são rastreados com os nomes e atributos corretos.
- Os eventos de receita capturam o valor e a moeda.
Próximas etapas
Após concluir os pré-requisitos, prossiga com a integração do SDK específico da plataforma ou a implementação S2S.
Guias de integração do SDK
Recursos adicionais
- FAQ de configuração de aplicativo - Configuração do aplicativo de produção
- Pré-requisitos do Singular Links - Configuração do domínio do link e deep linking
- Referência de eventos padrão - Lista completa de eventos padrão e atributos
- Teste de integração do SDK - Procedimentos de teste e validação completos