Referência da API do endpoint EVENT
Rastreie eventos in-app e receita para análise de atribuição e otimização de campanhas usando a API REST da Singular por meio de integração servidor a servidor, como alternativa à implementação do SDK.
Visão geral
Caso de uso servidor a servidor
O endpoint EVENT rastreia eventos in-app e receita para análise de atribuição e otimização de campanhas. É novo em servidor a servidor? Consulte o guia de fundamentos de S2S para conhecer os conceitos principais e a configuração comum.
Recursos compatíveis:
- Atribuição de eventos: Conecte as ações dos usuários às campanhas de marketing
- Rastreamento de receita: Meça e atribua compras in-app e transações
- Eventos personalizados: Rastreie qualquer interação do usuário, de cadastros a conclusões de fase
- Propriedades de eventos: Anexe dados contextuais aos eventos para uma análise mais aprofundada
Caso de uso híbrido: Em uma integração híbrida, o SDK da Singular é obrigatório e gerencia o rastreamento de sessões, portanto o endpoint SESSION não é usado. Seu servidor envia eventos ao endpoint EVENT V2 usando o Singular Device ID (SDID) fornecido pelo SDK.
Requisitos críticos
Pré-requisitos:
- Sessão antes dos eventos: A SESSION deve ser estabelecida antes de qualquer rastreamento de evento
- Ordem sequencial: Uma ordem de sessão inválida gera inconsistências nos dados e erros de atribuição
Diretrizes de rastreamento de eventos
Implemente o rastreamento de eventos seguindo as melhores práticas da Singular para convenções de nomenclatura e estrutura de dados.
Definição de eventos
Definir eventos
Antes de implementar a integração S2S, defina a lista completa de eventos que sua organização deseja rastrear para a análise de desempenho das campanhas.
Guia de planejamento de eventos: Definindo eventos in-app
Impacto da nomenclatura de eventos: Os nomes de eventos enviados à Singular determinam diretamente como os eventos aparecem em relatórios, exportações e postbacks.
Nomenclatura padrão de eventos
Melhores práticas:
- Eventos padrão: Use a convenção de nomenclatura de eventos padrão da Singular para agilizar o mapeamento nas integrações com parceiros
- Idioma inglês: Envie os nomes dos eventos em inglês para garantir compatibilidade com parceiros terceiros e soluções de análise
- Atributos padrão: Use os nomes de atributos de eventos padrão para as 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 no caso de caracteres não ASCII)
- Atributos de eventos: Máximo de 500 caracteres ASCII por chave e valor de atributo
Escolha do endpoint
O endpoint EVENT tem duas versões. Use os acordeões abaixo para ver a URL do endpoint e o identificador de dispositivo obrigatório de cada uma. Todos os demais parâmetros são compartilhados e documentados uma única vez em Parâmetros obrigatórios e Parâmetros opcionais abaixo.
V2 obrigatório a partir de 15 de julho de 2026. Contas criadas em 15 de julho de 2026 ou depois devem usar o Event Endpoint V2 (baseado em SDID); o V1 não está disponível para contas novas. Clientes existentes já integrados ao V1 não são afetados. Entre em contato com seu Customer Success Manager da Singular se quiser migrar para o V2.
Use o V2 para integrações híbridas em que o SDK da Singular rastreia as sessões com o Singular Device ID (SDID) e seu servidor envia os eventos usando esse mesmo SDID. O V2 dispensa identificadores de dispositivo específicos de cada plataforma.
POST https://s2s.singular.net/api/v2/evtIdentificador obrigatório:
| Parâmetro | Detalhes |
|---|---|
sdid
|
Plataformas:
iOS, Android, Web, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV
|
Use o V1 para integrações puramente do lado do servidor, ou para integrações híbridas em que o SDK da Singular não usa o SDID e que dependem de identificadores de dispositivo específicos de cada plataforma (IDFA, IDFV, AIFA, ASID etc.).
POST https://s2s.singular.net/api/v1/evtIdentificadores obrigatórios (pelo menos um):
| Parâmetro | Detalhes |
|---|---|
idfa
|
Plataforma:
iOS
|
idfv
|
Plataforma:
iOS
|
aifa
|
Plataforma:
Android
|
asid
|
Plataforma:
Android
|
amid
|
Plataforma:
Android
|
oaid
|
Plataforma:
Android
|
andi
|
Plataforma:
Android
Uso restrito: Proibido em dispositivos da Google Play; use AIFA e ASID no lugar. Envie somente se nenhum outro identificador estiver disponível e o app não for distribuído pela Google Play.
Exemplo:
|
Parâmetros obrigatórios
Todas as requisições EVENT devem incluir estes parâmetros obrigatórios além dos identificadores de dispositivo.
Formato dos parâmetros:
Todos os parâmetros devem ser enviados como dados
application/x-www-form-urlencoded
no corpo da requisição usando o método POST. As requisições devem incluir o cabeçalho
Content-Type: application/x-www-form-urlencoded
. Não envie os parâmetros em um corpo de requisição JSON.
Autenticação da API
| Parâmetro | Detalhes |
|---|---|
a
|
Tipo:
String
Importante: Não use a Reporting API Key. As requisições serão rejeitadas.
Exemplo:
|
Parâmetros do dispositivo
| Parâmetro | Detalhes |
|---|---|
p
|
Tipo:
String
|
ip
|
Tipo:
String
|
ve
|
Tipo:
String
|
ma
|
Plataforma:
iOS, Android
|
mo
|
Plataforma:
iOS, Android
|
lc
|
Plataforma:
iOS, Android
|
bd
|
Plataforma:
iOS, Android
|
Parâmetros da aplicação
| Parâmetro | Detalhes |
|---|---|
i
|
Tipo:
String
|
app_v
|
Tipo:
String
|
att_authorization_status
|
Plataforma:
iOS
Sempre obrigatório:
Mesmo que o ATT não seja implementado, envie
Exemplo:
|
Parâmetros do evento
| Parâmetro | Detalhes |
|---|---|
n
|
Tipo:
String
|
Parâmetros opcionais
Os parâmetros opcionais enriquecem o rastreamento de eventos com contexto e funcionalidades adicionais.
Parâmetros de timestamp
| Parâmetro | Detalhes |
|---|---|
utime
|
Tipo:
Integer
|
umilisec
|
Tipo:
Integer
|
Atributos de eventos
Suporte à Conversion API de parceiros:
Para encaminhar esses eventos a parceiros de redes de anúncios por meio das integrações da Conversion API da Singular, inclua os atributos de evento opcionais padrão (dados primários com hash, como
eventId
e
ehash
). Consulte
Atributos de evento padrão para integrações da Conversion API
.
| Parâmetro | Detalhes |
|---|---|
e
|
Tipo:
JSON
|
global_properties
|
Tipo:
JSON
|
Parâmetros de rede
| Parâmetro | Detalhes |
|---|---|
use_ip
|
Tipo:
Boolean
Limitações:
Exemplo:
|
country
|
Tipo:
String
|
ua
|
Tipo:
String
|
c
|
Plataforma:
iOS, Android
|
cn
|
Plataforma:
iOS, Android
|
Privacidade de dados
| Parâmetro | Detalhes |
|---|---|
data_sharing_options
|
Tipo:
JSON
|
dnt
|
Plataforma:
iOS, Android
|
dntoff
|
Plataforma:
iOS, Android
|
Suporte entre dispositivos
| Parâmetro | Detalhes |
|---|---|
custom_user_id
|
Tipo:
String
Sem PII: Não envie informações de identificação pessoal. Use um identificador interno com hash ou anonimizado de outra forma, e não endereços de e-mail, números de telefone ou nomes em texto puro.
Exemplo:
|
Suporte a SKAdNetwork
| Parâmetro | Detalhes |
|---|---|
skan_conversion_value
|
Plataforma:
iOS
|
skan_first_call_timestamp
|
Plataforma:
iOS
|
skan_last_call_timestamp
|
Plataforma:
iOS
|
Rastreamento de receita
Rastreie compras in-app e eventos de receita com a validação e o tratamento de moeda adequados.
Parâmetros de receita obrigatórios
Rastreamento básico de receita
Parâmetros mínimos necessários para o rastreamento de eventos de receita quando você faz sua própria validação de receita.
Melhor prática: Valide os eventos de receita junto às App Stores no lado do seu servidor antes de enviar a requisição do evento à Singular. Se fizer a própria validação, apenas estes parâmetros são necessários.
| Parâmetro | Detalhes |
|---|---|
is_revenue_event
|
Tipo:
Boolean
|
amt
|
Tipo:
Number
|
cur
|
Tipo:
String
|
Observação:
Enviar o parâmetro
amt
faz com que o evento seja processado como evento de receita, independentemente do valor de
is_revenue_event
, incluindo
is_revenue_event=false
. Se você não quiser que um evento seja tratado como de receita, omita o parâmetro
amt
. Para marcar um evento de receita sem valor, envie
is_revenue_event=true
.
Parâmetros de validação de receita
Receita validada pela Singular
Parâmetros opcionais para que a Singular faça a validação de receita no lado do servidor junto às App Stores.
Requisitos de validação:
- Obrigatórios se você depender da Singular para a validação de receita junto às App Stores
- Confirme a sintaxe correta dos valores do recibo de compra e da assinatura
-
A formatação incorreta faz com que a Singular bloqueie a receita e gere um evento
__iapinvalid__
| Parâmetro | Detalhes |
|---|---|
purchase_receipt
|
Plataforma:
iOS, Android
|
receipt_signature
|
Plataforma:
Android
|
purchase_product_id
|
Tipo:
String
|
purchase_transaction_id
|
Tipo:
String
|
Rastreamento de receita de anúncios
Rastreie a receita de monetização de anúncios em nível de impressão vinda de plataformas de mediação (por exemplo, AdMob, AppLovin MAX ou ironSource) enviando um EVENT padrão com um nome de evento fixo e atributos de monetização de anúncios. A receita de anúncios usa o mesmo endpoint EVENT documentado acima.
Dados da plataforma de mediação: Colete os atributos de receita de anúncios necessários diretamente do SDK da sua plataforma de mediação. Consulte o Guia do SDK de receita de anúncios para conhecer os atributos que cada plataforma de mediação fornece.
Receita de monetização de anúncios
Além dos parâmetros obrigatórios padrão (autenticação, dispositivo e aplicação), os eventos de receita de anúncios exigem o seguinte.
| Parâmetro | Detalhes |
|---|---|
n
|
Tipo:
String
|
is_admon_revenue
|
Tipo:
Boolean
|
is_revenue_event
|
Tipo:
Boolean
|
amt
|
Tipo:
Number
|
cur
|
Tipo:
String
|
e
|
Tipo:
JSON
Atributos opcionais:
Estrutura JSON: Exemplo codificado em URL: Observação: Omita os atributos sem valor. |
Exemplos de requisição
O código de exemplo demonstra a integração do endpoint EVENT em várias linguagens de programação.
Aviso sobre os exemplos:
Os exemplos de código podem não incluir todos os parâmetros obrigatórios. Valide a lista completa de parâmetros antes da implementação em produção. Use um
i
(identificador do app) exclusivo para desenvolvimento e testes.
Exemplo em Python
import requests
url = 'https://s2s.singular.net/api/v1/evt'
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
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.post(url, data=params, headers=headers)
print(response.json())Exemplo com cURL
curl -X POST "https://s2s.singular.net/api/v1/evt" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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
POST /api/v1/evt HTTP/1.1
Host: s2s.singular.net
Content-Type: application/x-www-form-urlencoded
Accept: application/json
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_cartExemplo em Java
// Endpoint
String endpoint = "https://s2s.singular.net/api/v1/evt";
// Parameters
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");
// Build form-urlencoded body
StringBuilder form = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
if (form.length() > 0) form.append('&');
form.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
.append('=')
.append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
byte[] body = form.toString().getBytes(StandardCharsets.UTF_8);
// Create connection
URL url = new URL(endpoint);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setRequestProperty("Accept", "application/json");
// Write body
try (OutputStream os = conn.getOutputStream()) {
os.write(body);
}
// Get response
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();
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
conn.disconnect();Códigos de resposta e erros
O endpoint EVENT retorna códigos de status HTTP e respostas JSON indicando o sucesso ou a falha da requisição.
Documentação completa de erros: Códigos de resposta S2S e tratamento de erros
Testes e validação
Verifique a integração de eventos S2S antes da implantação em produção usando o SDK Console da Singular para validação de dados em tempo real.
Procedimento de teste
Validação de ponta a ponta
- Registre o dispositivo de teste: Obtenha o ID de publicidade do dispositivo e adicione-o ao SDK Console da Singular
- Ative o log no console: Adicione o identificador do dispositivo no SDK Console para capturar os dados de teste
-
Use um App ID de desenvolvimento:
Substitua o identificador do app pela versão de desenvolvimento (ex.:
com.singular.app.dev) para separar os dados de teste dos de produção - Compile e inicie: Compile ou abra o app a partir do estado encerrado
- Valide os dados do cliente: Confirme que o app envia ao seu servidor todos os dados exigidos pela Singular
-
Verifique a sessão:
Confirme que seu servidor envia a requisição SESSION para
https://s2s.singular.net/api/v1/launchcom todos os parâmetros obrigatórios - Verifique o SDK Console (sessão): Em segundos, o evento SESSION deve aparecer no SDK Console
Teste de eventos
- Acione um evento: Prossiga acionando um evento no app
- Valide os dados do evento: Confirme que o evento foi enviado ao seu servidor com todos os dados exigidos pela Singular
-
Verifique a requisição do servidor:
Confirme que seu servidor envia a requisição EVENT para o seu endpoint (V2
https://s2s.singular.net/api/v2/evtou V1https://s2s.singular.net/api/v1/evt) com todos os parâmetros obrigatórios. - Verifique o SDK Console (evento): Em segundos, o EVENT deve aparecer no SDK Console
- Repita os testes: Valide que todos os eventos são enviados com os valores esperados
Verificações críticas:
- Confirme que o evento SESSION ocorre na abertura do app ou ao trazê-lo para primeiro plano ANTES de o EVENT ser recebido
- Confirme que os dados obrigatórios do EVENT correspondem aos dados da SESSION
Indicador de sucesso: Se os eventos aparecerem no SDK Console, você concluiu com sucesso o teste de integração de eventos de ponta a ponta.
Recursos adicionais
Documentação de testes
Guia completo de testes: Guia de testes de integração S2S