Referência da API do ponto de extremidade EVENT - servidor a servidor

Documento

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.

  1. Recolha de clientes: A aplicação recolhe dados de eventos e identificadores de dispositivos
  2. Transmissão do servidor: A aplicação reencaminha os dados do evento para o seu servidor backend
  3. Consulta do gráfico do dispositivo: O servidor recupera ou actualiza os detalhes do dispositivo a partir do gráfico de dispositivos Singular
  4. Chamada à API de eventos: O servidor envia o evento para o endpoint da API REST do Singular

Event Data Flow Diagram


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:


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

  • Omitir o parâmetro se o IDFA não estiver disponível (ATT negado pelo utilizador)
  • Nunca passar NULL ou uma cadeia de caracteres vazia
  • Recuperar IDFA

Exemplo:DFC5A647-9043-4699-B2A5-76F03A97064B

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:21DB6612-09B3-4ECC-84AC-B353B0AF1334

aifa Android
(Google Play)

O Google Advertising ID (GAID)permite o acompanhamento de publicidade redefinível pelo utilizador.

  • Obrigatório em dispositivos Google Play
  • Omitir em dispositivos que não sejam do Google Play
  • Nunca passar NULL ou uma cadeia de caracteres vazia
  • Recuperar AIFA

Exemplo:8ecd7512-2864-440c-93f3-a3cabe62525b

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:edee92a2-7b2f-45f4-a509-840f170fc6d9

amid Android
(Amazon)

ID de publicidade da Amazonpara dispositivos Amazon Fire sem Google Play Services.

Exemplo:df07c7dc-cea7-4a89-b328-810ff5acb15d

oaid Android
(OEMs chineses)

Identificador de publicidade aberta (OAID) para dispositivos fabricados na China sem o Google Play Services.

  • Necessário para dispositivos Huawei, Xiaomi, OPPO, Vivo sem Google Play
  • Recuperar OAID

Exemplo:01234567-89abc-defe-dcba-987654321012

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: fc8d449516de0dfb

sdid Web, PC, Consola, CTV

ID de dispositivo único para plataformas sem identificadores de publicidade nativa.

  • Web: Obtido do Singular Web SDK
  • PC/Console: UUIDv4 gerado pelo cliente que representa a instalação única da aplicação
  • Recuperar SDID

Exemplo:40009df0-d618-4d81-9da1-cbb3337b8dec

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:da534a95-1b1b-47d4-94b6-07955ec85177


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.

  • iOS/Android: Requer habilitação de conta para uso do SDID - o método de retorno de chamada do SDK fornece o SDID após a inicialização
  • Simplificação do identificador: Elimina a necessidade de parâmetros AIFA, ASID, IDFA, IDFV
  • Web: Obtido do Singular Web SDK
  • PC/Console/CTV: UUIDv4 gerado pelo cliente que representa a instalação única da aplicação
  • Recuperar SDID

Exemplo:40009df0-d618-4d81-9da1-cbb3337b8dec


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: sdkKey_afdadsf7asf56


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: Android

ip

Endereço IP público IPv4 do dispositivo. IPv6 suportado, mas IPv4 recomendado para compatibilidade de atribuição.

Exemplo: 172.58.29.235

ve

Versão do sistema operativo do dispositivo no momento do evento.

Exemplo: versão do sistema operativo do dispositivo no momento do evento: 9.2


Parâmetros da aplicação

Parâmetro Descrição
i

Identificador da aplicação (sensível a maiúsculas e minúsculas).

  • Android: Nome do pacote (por exemplo, com.singular.app)
  • iOS: ID do pacote (por exemplo, com.singular.app)
  • Web: ID do produto
  • PC/Console/CTV: O seu identificador designado

Exemplo: com.singular.app

att_authorization_status
iOS

Código de estado do App Tracking Transparency (ATT) (iOS 14.5+).

Valores de estado:

  • 0 - Indeterminado (aviso não mostrado)
  • 1 - Restrito (rastreio ao nível do dispositivo desativado)
  • 2 - Negado (autorização negada pelo utilizador)
  • 3 - Autorizado (autorização concedida ao utilizador)

Sempre necessário: Mesmo que a ATT não esteja implementada, passe 0 (indeterminado).

Exemplo: 3


Parâmetros de eventos

Parâmetro Descrição
n

Nome do evento que está a ser controlado.

Exemplo: sng_add_to_cart


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: 1483228800

umilisec int

Carimbo de data/hora Unix de 13 dígitos com milissegundos.

Exemplo: 13 dígitos 1483228800000

ma
iOS, Android
string

Marca do dispositivo (nome do fabricante). Deve ser utilizado com mo(modelo).

Recuperar marca do dispositivo

Exemplos: Samsung, LG, Apple

mo
iOS, Android
string

Modelo do dispositivo. Deve ser utilizado com ma (make).

Recuperar modelo do dispositivo

Exemplos: iPhone 4S, Galaxy SIII

lc
iOS, 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: en_US

bd
iOS, Android
string

Identificador de construção do dispositivo, codificado por URL.

Recuperar compilação do dispositivo

Exemplo: Build%2F13D15


Atributos de evento

Parâmetro Descrição
e

Cadeia de caracteres JSON codificada por URL que especifica atributos de eventos personalizados.

Estrutura JSON:

{
  "sng_attr_content_id": 5581,
  "sng_attr_content": "XBox",
  "sng_attr_content_type": "electronics"
}

Exemplo codificado por URL:

%7B%22sng_attr_content_id%22%3A5581%2C%22sng_attr_content%22%3A%22XBox%22%2C%22sng_attr_content_type%22%3A%22electronics%22%7D
global_properties

Objeto JSON codificado por URL que contém pares chave-valor personalizados aplicados globalmente ao evento.

Limites:

  • Máximo de 5 pares de valores-chave
  • Máximo de 200 caracteres por chave e valor

JSON:{"key1":"value1","key2":"value2"}

Codificado por URL:%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D


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 ip.

Limitações:

  • Impede a geolocalização baseada em IP pela Singular
  • Fornecer código de país de duas letras através do parâmetro country
  • Mutuamente exclusivo com o parâmetro ip
  • Deve fornecer ip ou use_ip

Exemplo: true

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 use_ip=true

Exemplo: US


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):

{"limit_data_sharing":false}

O utilizador recusou (Optou por não participar):

{"limit_data_sharing":true}

Exemplo codificado por URL:%7B%22limit_data_sharing%22%3Atrue%7D


Suporte para vários dispositivos

Parâmetro Descrição
custom_user_id

O seu ID de utilizador interno para rastreio entre dispositivos.

Exemplo: 123456789abcd


SKAdNetwork Support

Parâmetro Descrição
skan_conversion_value
iOS

Valor de conversão SKAdNetwork mais recente no momento do evento.

Saiba mais: Implementação de SKAdNetwork

Exemplo: 7

skan_first_call_timestamp
iOS

Carimbo de data/hora Unix da primeira chamada à API SKAdNetwork.

Exemplo: 1483228800

skan_last_call_timestamp
iOS

Carimbo de data/hora Unix da chamada mais recente à API SKAdNetwork na hora do evento.

Exemplo: 1483228800


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.

  • Pode ser omitido se o nome do evento for __iap__ou amt diferente de zero fornecido

Exemplo: true

amt double

Montante em moeda da transação.

  • Utilizar em conjunto com o parâmetro cur

Exemplo: 2.51

cur string

Código de moeda ISO 4217de três letras maiúsculas.

  • Utilizar em conjunto com o parâmetro amt

Exemplo: USD


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_receipt
iOS, Android

Recibo recebido da transação de compra.

Exemplo (iOS):

MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==

Exemplo (Android, codificado por URL):

%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22...
receipt_signature
Android

Assinatura usada para assinar o recibo de compra (apenas Android).

Exemplo:

TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==
purchase_product_id

Identificador de SKU do produto.

Exemplo: com.example.product

purchase_transaction_id

Identificador de transação.

Exemplo (iOS): 380000123004321

Exemplo (Android):GPA.1234-1234-1234-12345


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.

PYTHONCURLHTTPJAVA

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())

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

  1. Registar dispositivo de teste: Obter a ID de publicidade do dispositivo e adicionar ao Singular SDK Console
  2. Habilitar o registro no Console: Adicionar identificador de dispositivo no Console do SDK para capturar dados de teste
  3. 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
  4. Criar e iniciar: Criar ou abrir a aplicação a partir do estado terminado
  5. Validar dados do cliente: Confirmar se o aplicativo envia todos os pontos de dados Singular necessários para o servidor
  6. Verificar sessão: Confirme se o seu servidor envia o pedido SESSION para https://s2s.singular.net/api/v1/launch com todos os parâmetros necessários
  7. Verificar a consola SDK (sessão): Em segundos, o evento SESSION deve aparecer no Console do SDK

SDK Console Session Event


Teste de eventos

  1. Acionar evento: Proceder ao acionamento de um evento na aplicação
  2. Validar dados do evento: Confirmar o evento enviado ao seu servidor com todos os pontos de dados Singular necessários
  3. 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
  4. Verificar a consola SDK (evento): Em segundos, o EVENT deve aparecer no Console do SDK
  5. Repetir testes: Validar todos os eventos enviados com os valores esperados

SDK Console Event

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