Referência da API do endpoint EVENT
Rastreie eventos e receitas in-app para análise de atribuição e otimização de campanhas usando a API REST da Singular por meio da integração servidor a servidor como uma alternativa à implementação do SDK.
Visão geral
Caso de uso de servidor para servidor
A API EVENT permite o rastreamento de eventos in-app onde os aplicativos encaminham dados de interação do usuário para o seu backend, que transmite para os servidores da Singular para atribuição de eventos e relatórios de análise de receita.
Capacidades suportadas:
- Atribuição de eventos: Conectar ações do usuário a campanhas de marketing
- Rastreamento de receita: Medir e atribuir compras e transações in-app
- Eventos personalizados: Acompanhe qualquer interação do utilizador, desde registos a conclusões de níveis
- Propriedades do evento: Anexe dados contextuais a eventos para uma análise mais profunda
Arquitetura do fluxo de dados
O rastreamento de eventos de servidor para servidor segue um processo de transmissão de dados em quatro etapas.
- Recolha de clientes: A aplicação recolhe dados de eventos e identificadores de dispositivos
- Transmissão do servidor: A aplicação reencaminha os dados do evento para o seu servidor backend
- Consulta do gráfico do dispositivo: O servidor recupera ou actualiza os detalhes do dispositivo a partir do gráfico de dispositivos Singular
- Chamada à API de eventos: O servidor envia o evento para o endpoint da API REST do Singular
Requisitos críticos
Pré-requisitos:
- Sessão antes dos eventos: A SESSÃO deve ser estabelecida antes de qualquer rastreamento de evento
- Ordem Sequencial: Uma ordem de sessão inválida resulta em inconsistências de dados e erros de atribuição
Restrições de integração:
- Processamento em tempo real: Pedidos processados individualmente - sem suporte de lote
- Eventos cronológicos: Os eventos devem ser enviados na ordem em que ocorreram
- Sem Deduplicação: O Singular não deduplica dados - implemente a deduplicação do lado do servidor para evitar duplicatas
- Permanência de dados: Os dados ao nível do dispositivo não podem ser eliminados após a ingestão - validar antes de enviar
Diretrizes para rastreamento de eventos
Implemente o rastreamento de eventos seguindo as práticas recomendadas da Singular para convenções de nomenclatura e estrutura de dados.
Definição de eventos
Definição de eventos
Antes de implementar a integração S2S, defina a lista completa de eventos que sua organização deseja rastrear para análise de desempenho da campanha.
Guia de planejamento de eventos: Definição de eventos no aplicativo
Impacto da nomenclatura de eventos: Os nomes de eventos passados para o Singular determinam diretamente como os eventos aparecem em relatórios, exportações e postbacks.
Nomeação padrão de eventos
Práticas recomendadas:
- Eventos padrão: Use a convenção de nomenclatura de eventos padrão da Singularpara mapeamento de integração de parceiros simplificado
- Idioma inglês: Passe nomes de eventos em inglês para compatibilidade com parceiros de terceiros e soluções de análise
- Atributos Padrão: Use nomes de atributos de eventos padrãopara propriedades de eventos
Limitações de caracteres
Restrições de comprimento:
- Nomes de eventos: Máximo de 32 caracteres ASCII (32 bytes quando convertidos para UTF-8 para não-ASCII)
- Atributos de eventos: Máximo de 500 caracteres ASCII por chave e valor de atributo
Seleção do ponto de extremidade da API
A Singular fornece duas versões de endpoint EVENT optimizadas para diferentes arquitecturas de integração.
Seleção de Endpoint: Escolha o endpoint com base em sua arquitetura de integração e estratégia de identificação de dispositivos. O caso de uso determina o endpoint correto.
Ponto de extremidade de evento V1
Casos de uso da V1
Use o Event Endpoint V1 para integrações que dependem de identificadores de dispositivo específicos da plataforma (IDFA, IDFV, AIFA, ASID, etc.).
Recomendado para:
- Puro lado do servidor: Integrações do lado do servidor sem implementação do SDK Singular
- Híbrido (não SDID): Integrações híbridas em que o Singular SDK não usa o SDID (Singular Device ID)
URL do ponto de extremidade:
GET https://s2s.singular.net/api/v1/evt
Ponto de extremidade de evento V2
Casos de uso do V2
Use o Event Endpoint V2 para integrações híbridas em que o Singular SDK rastreia sessões usando o SDID e o servidor envia eventos usando o mesmo SDID.
Recomendado para:
- Híbrido (baseado em SDID): O Singular SDK rastreia sessões com SDID e os eventos do lado do servidor usam o mesmo SDID
- Identificadores simplificados: Implementações que evitam identificadores de dispositivo específicos da plataforma (IDFA, AIFA, etc.)
URL do ponto final:
GET https://s2s.singular.net/api/v2/evt
Ativação de conta: O ponto de extremidade V2 requer configuração de conta Singular para uso de SDID. Contacte o seu Engenheiro de Soluções ou CSM para obter informações sobre a ativação.
Identificadores de dispositivo necessários
Os requisitos do identificador de dispositivo variam de acordo com a versão e a plataforma do terminal.
Identificadores de Ponto de Extremidade V1
Identificadores específicos da plataforma
O Event Endpoint V1 requer identificadores de publicidade específicos da plataforma com base no sistema operativo do dispositivo e no método de distribuição da aplicação.
| Parâmetro | Plataforma | Descrição |
|---|---|---|
idfa
|
iOS |
O Identificador para Anunciantes (IDFA)permite o rastreio de anúncios e a atribuição de campanhas. Requisito ATT: o iOS 14.5+ requer a opção do utilizador através da Transparência do Seguimento de Aplicações
Exemplo: |
idfv
|
iOS |
O Identificador para Fornecedores (IDFV)mantém-se consistente em todas as aplicações do mesmo fornecedor. Sempre necessário: Deve ser incluído independentemente do estado do ATT ou da disponibilidade do IDFA
Exemplo: |
aifa
|
Android (Google Play) |
O Google Advertising ID (GAID)permite o acompanhamento de publicidade redefinível pelo utilizador.
Exemplo: |
asid
|
Android (Google Play) |
A ID do conjunto de aplicações Androidpermite o rastreio de aplicações cruzadas com consciência da privacidade para o mesmo programador. Sempre necessário: Deve ser incluído nos dispositivos Google Play, independentemente da disponibilidade do GAID
Exemplo: |
amid
|
Android (Amazon) |
ID de publicidade da Amazonpara dispositivos Amazon Fire sem Google Play Services.
Exemplo: |
oaid
|
Android (OEMs chineses) |
Identificador de publicidade aberta (OAID) para dispositivos fabricados na China sem o Google Play Services.
Exemplo: |
andi
|
Android (Não-Google Play) |
O Android ID é um identificador de 64 bits gerado pelo dispositivo. Utilização restrita: Proibido em dispositivos Google Play. Utilizar apenas se não existirem outros identificadores disponíveis e se a aplicação não for distribuída através do Google Play.
Exemplo: |
sdid
|
Web, PC, Consola, CTV |
ID de dispositivo único para plataformas sem identificadores de publicidade nativa.
Exemplo: |
sing
|
Apenas para empresas |
Identificador definido pelo cliente para casos de utilização especiais em que os identificadores padrão não estão disponíveis. Restrito: Apenas para clientes empresariais - deve ser ativado pelo Singular Solution Engineer por aplicação.
Exemplo: |
Identificadores de ponto de extremidade V2
Requisito somente de SDID
O Event Endpoint V2 requer apenas o Singular Device ID (SDID) para todas as plataformas, simplificando a identificação do dispositivo.
| Parâmetro | Descrição |
|---|---|
sdid
|
Plataformas: iOS, Android, Web, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV Singular Device ID obtido do Singular SDK ou gerado no lado do cliente para PC/Console/CTV.
Exemplo: |
Parâmetros obrigatórios
Todos os pedidos EVENT devem incluir estes parâmetros obrigatórios, para além dos identificadores de dispositivos.
Formato dos parâmetros: Todos os parâmetros têm de ser transmitidos como parâmetros de consulta de URL utilizando o método GET. Não enviar parâmetros no corpo do pedido JSON.
Autenticação da API
| Parâmetro | Tipo de parâmetro | Descrição |
|---|---|---|
a
|
string
|
Chave SDK única para autenticação da API. Recuperar de: Singular UI → Menu principal → Ferramentas do desenvolvedor Importante: Não utilizar Reporting API Key - os pedidos serão rejeitados.
Exemplo: |
Parâmetros do dispositivo
| Parâmetro | Descrição |
|---|---|
p
|
Plataforma da aplicação (sensível a maiúsculas e minúsculas). Valores permitidos: Android, iOS, Web, PC, Xbox, Playstation, Nintendo, MetaQuest, CTV
Exemplo: |
ip
|
Endereço IP público IPv4 do dispositivo. IPv6 suportado, mas IPv4 recomendado para compatibilidade de atribuição.
Exemplo: |
ve
|
Versão do sistema operativo do dispositivo no momento do evento.
Exemplo: versão do sistema operativo do dispositivo no momento do evento: |
Parâmetros da aplicação
| Parâmetro | Descrição |
|---|---|
i
|
Identificador da aplicação (sensível a maiúsculas e minúsculas).
Exemplo: |
att_authorization_statusiOS |
Código de estado do App Tracking Transparency (ATT) (iOS 14.5+). Valores de estado:
Sempre necessário: Mesmo que a ATT não esteja implementada, passe
Exemplo: |
Parâmetros de eventos
| Parâmetro | Descrição |
|---|---|
n
|
Nome do evento que está a ser controlado.
Exemplo: |
Parâmetros opcionais
Os parâmetros opcionais melhoram o seguimento de eventos com contexto e funcionalidade adicionais.
Parâmetros de carimbo de data/hora
| Parâmetro | Tipo de carimbo | Descrição |
|---|---|---|
utime
|
int
|
Carimbo de data/hora Unix de 10 dígitos do evento.
Exemplo: |
umilisec
|
int
|
Carimbo de data/hora Unix de 13 dígitos com milissegundos.
Exemplo: 13 dígitos |
maiOS, Android |
string
|
Marca do dispositivo (nome do fabricante). Deve ser utilizado com Recuperar marca do dispositivo
Exemplos: |
moiOS, Android |
string
|
Modelo do dispositivo. Deve ser utilizado com Recuperar modelo do dispositivo
Exemplos: |
lciOS, Android |
string
|
Etiqueta de localidade IETF - código de duas letras do idioma e do país separado por sublinhado. Recuperar a localidade do dispositivo
Exemplo: |
bdiOS, Android |
string
|
Identificador de construção do dispositivo, codificado por URL. Recuperar compilação do dispositivo
Exemplo: |
Atributos de evento
| Parâmetro | Descrição |
|---|---|
e
|
Cadeia de caracteres JSON codificada por URL que especifica atributos de eventos personalizados. Estrutura JSON:
Exemplo codificado por URL:
|
global_properties
|
Objeto JSON codificado por URL que contém pares chave-valor personalizados aplicados globalmente ao evento. Limites:
JSON:
Codificado por URL: |
Parâmetros de rede
| Parâmetro | Descrição |
|---|---|
use_ip
|
Instrui o Singular a extrair o endereço IP do pedido HTTP em vez do parâmetro Limitações:
Exemplo: |
country
|
Código de país de duas letras ISO 3166-1 alfa-2.
Obrigatório quando: Endereço IP não disponível ou
Exemplo: |
Privacidade dos dados
| Parâmetro | Descrição |
|---|---|
data_sharing_options
|
Consentimento do utilizador final codificado por URL JSON para a partilha de dados. Deve persistir e ser transmitido em todos os pedidos EVENT subsequentes. Consentimento do utilizador (Opt-In):
O utilizador recusou (Optou por não participar):
Exemplo codificado por URL: |
Suporte para vários dispositivos
| Parâmetro | Descrição |
|---|---|
custom_user_id
|
O seu ID de utilizador interno para rastreio entre dispositivos.
Exemplo: |
SKAdNetwork Support
| Parâmetro | Descrição |
|---|---|
skan_conversion_valueiOS |
Valor de conversão SKAdNetwork mais recente no momento do evento. Saiba mais: Implementação de SKAdNetwork
Exemplo: |
skan_first_call_timestampiOS |
Carimbo de data/hora Unix da primeira chamada à API SKAdNetwork.
Exemplo: |
skan_last_call_timestampiOS |
Carimbo de data/hora Unix da chamada mais recente à API SKAdNetwork na hora do evento.
Exemplo: |
Rastreamento de receita
Acompanhe as compras in-app e os eventos de receita com validação e tratamento de moeda adequados.
Parâmetros de receita necessários
Rastreamento básico de receita
Parâmetros mínimos necessários para o rastreamento de eventos de receita ao realizar sua própria validação de receita.
Melhores práticas: Valide os eventos de receita com as App Stores no lado do servidor antes de enviar a solicitação de evento para a Singular. Se estiver realizando sua própria validação, apenas esses parâmetros são necessários.
| Parâmetro | Tipo de parâmetro | Descrição |
|---|---|---|
is_revenue_event
|
string
|
Especifica se o evento é um evento de receita.
Exemplo: |
amt
|
double
|
Montante em moeda da transação.
Exemplo: |
cur
|
string
|
Código de moeda ISO 4217de três letras maiúsculas.
Exemplo: |
Parâmetros de validação de receita
Receita validada pelo Singular
Parâmetros opcionais para que o Singular execute a validação de receita do lado do servidor com as App Stores.
Requisitos de validação:
- Obrigatório se depender do Singular para validação de receita com as App Stores
- Confirmar a sintaxe correta dos valores do recibo de compra e da assinatura
-
A formatação incorrecta faz com que o Singular bloqueie a receita e gere o evento
__iapinvalid__
| Parâmetro | Descrição |
|---|---|
purchase_receiptiOS, Android |
Recibo recebido da transação de compra. Exemplo (iOS):
Exemplo (Android, codificado por URL):
|
receipt_signatureAndroid |
Assinatura usada para assinar o recibo de compra (apenas Android). Exemplo:
|
purchase_product_id
|
Identificador de SKU do produto.
Exemplo: |
purchase_transaction_id
|
Identificador de transação.
Exemplo (iOS):
Exemplo (Android): |
Exemplos de pedidos
O código de exemplo demonstra a integração do ponto de extremidade EVENT em várias linguagens de programação.
Exemplo de isenção de responsabilidade: As amostras de código podem não incluir todos os parâmetros necessários. Valide a lista completa de parâmetros antes da implementação na produção. Utilizar i (identificador de aplicação) único para desenvolvimento/testes.
Exemplo Python
import requests
params = {
'a': 'sdk_key_here',
'p': 'Android',
'i': 'com.singular.app',
'ip': '10.1.2.3',
've': '9.2',
'ma': 'samsung',
'mo': 'SM-G935F',
'lc': 'en_US',
'bd': 'Build/13D15',
'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
'n': 'sng_add_to_cart'
}
response = requests.get('https://s2s.singular.net/api/v1/evt', params=params)
print(response.json())
Exemplo cURL
curl -G "https://s2s.singular.net/api/v1/evt" \
--data-urlencode "a=sdk_key_here" \
--data-urlencode "p=Android" \
--data-urlencode "i=com.singular.app" \
--data-urlencode "ip=10.1.2.3" \
--data-urlencode "ve=9.2" \
--data-urlencode "ma=samsung" \
--data-urlencode "mo=SM-G935F" \
--data-urlencode "lc=en_US" \
--data-urlencode "bd=Build/13D15" \
--data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
--data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
--data-urlencode "n=sng_add_to_cart"
Exemplo HTTP
GET /api/v1/evt
?a=sdk_key_here
&p=Android
&i=com.singular.app
&ip=10.1.2.3
&ve=9.2
&ma=samsung
&mo=SM-G935F
&lc=en_US
&bd=Build%2F13D15
&aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
&asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
&n=sng_add_to_cart HTTP/1.1
Host: s2s.singular.net
Accept: application/json
Exemplo Java
// URL de base String baseUrl = "https://s2s.singular.net/api/v1/evt"; // Parâmetros Map<String, String> params = new HashMap<>(); params.put("a", "sdk_key_here"); params.put("p", "Android"); params.put("i", "com.singular.app"); params.put("ip", "10.1.2.3"); params.put("ve", "9.2"); params.put("ma", "samsung"); params.put("mo", "SM-G935F"); params.put("lc", "en_US"); params.put("bd", "Build/13D15");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "sng_add_to_cart"); // Construir URL com parâmetros codificados StringBuilder urlBuilder = new StringBuilder(baseUrl); urlBuilder.append('?'); for (Map.Entry<String, String> entry : params.entrySet()) { if (urlBuilder.length() baseUrl.length() + 1) { urlBuilder.append('&'); } urlBuilder.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8)) .append('=') .append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8)); } // Criar ligação URL url = new URL(urlBuilder.toString()); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); conn.setRequestMethod("GET"); conn.setRequestProperty("Accept", "application/json"); // Obter resposta int responseCode = conn.getResponseCode(); BufferedReader in = new BufferedReader( new InputStreamReader(conn.getInputStream()) ); String inputLine; StringBuilder response = new StringBuilder(); while ((inputLine = in.readLine()) != null) { response.append(inputLine); } in.close(); // Verificar o estado System.out.println("HTTP Status Code: " + responseCode); System.out.println("Response: " + response.toString()); // Desconectar conn.disconnect();
Códigos de resposta e erros
O ponto de extremidade EVENT devolve códigos de estado HTTP e respostas JSON que indicam o sucesso ou a falha do pedido.
Documentação completa sobre erros: Códigos de resposta e tratamento de erros do S2S
Teste e validação
Verifique a integração do evento S2S antes da implantação na produção usando o Singular SDK Console para validação de dados em tempo real.
Procedimento de teste
Validação de ponta a ponta
- Registar dispositivo de teste: Obter a ID de publicidade do dispositivo e adicionar ao Singular SDK Console
- Habilitar o registro no Console: Adicionar identificador de dispositivo no Console do SDK para capturar dados de teste
-
Usar ID do aplicativo de desenvolvimento: Substituir o identificador do aplicativo pela versão de desenvolvimento (por exemplo,
com.singular.app.dev) para separar os dados de teste dos de produção - Criar e iniciar: Criar ou abrir a aplicação a partir do estado terminado
- Validar dados do cliente: Confirmar se o aplicativo envia todos os pontos de dados Singular necessários para o servidor
-
Verificar sessão: Confirme se o seu servidor envia o pedido SESSION para
https://s2s.singular.net/api/v1/launchcom todos os parâmetros necessários - Verificar a consola SDK (sessão): Em segundos, o evento SESSION deve aparecer no Console do SDK
Teste de eventos
- Acionar evento: Proceder ao acionamento de um evento na aplicação
- Validar dados do evento: Confirmar o evento enviado ao seu servidor com todos os pontos de dados Singular necessários
-
Verificar solicitação do servidor: Confirme se o seu servidor envia o pedido EVENT para
https://s2s.singular.net/api/v1/evtcom todos os parâmetros necessários - Verificar a consola SDK (evento): Em segundos, o EVENT deve aparecer no Console do SDK
- Repetir testes: Validar todos os eventos enviados com os valores esperados
Verificações críticas:
- Confirmar que o evento SESSION ocorre na abertura/no primeiro plano da aplicação ANTES de o EVENT ser recebido
- Confirmar que os pontos de dados necessários do EVENT correspondem aos pontos de dados da SESSION
Indicador de sucesso: Se os eventos aparecerem no Console do SDK, o teste de integração de eventos de ponta a ponta foi concluído com sucesso!
Recursos adicionais
Documentação de teste
Guia de teste abrangente: Guia de teste de integração S2S