Documento

Referência da API de rastreamento de receita de anúncios

Acompanhe a receita de monetização de anúncios no nível de impressão 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 de receita de anúncios permite o rastreamento da monetização de anúncios no nível da impressão, onde os aplicativos encaminham os dados de receita das plataformas de mediação para o seu back-end, que transmite para os servidores da Singular para análise e relatórios de receita de anúncios.

Recursos suportados:

Receita de monetização de anúncios: Rastrear a receita no nível de impressão das plataformas de mediação
Atribuição de plataforma: Conectar a receita de anúncios às campanhas de aquisição de usuários
Integração de mediação: Suporte para todas as principais plataformas de mediação de anúncios
Conversão de moeda: Conversão automática de moeda alinhada com as definições da organização

Arquitetura do fluxo de dados

O rastreamento de receita de anúncios de servidor para servidor segue um processo de transmissão de dados em quatro etapas.

Recolha do cliente: A aplicação recolhe dados de receitas ao nível da impressão a partir do SDK da plataforma de mediação
Transmissão do servidor: A aplicação encaminha os dados de receitas de anúncios 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 __ADMON_USER_LEVEL_REVENUE__ 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 receita de anúncios
Ordem sequencial: Uma ordem de sessão inválida resulta em inconsistências de dados e erros de atribuição
Dados da plataforma de mediação: Recolher os atributos necessários diretamente do SDK de mediação - consulte o Guia do SDKpara obter detalhes de implementaçã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 no nível do dispositivo não podem ser excluídos após a ingestão - validar antes de enviar

Seleção do ponto final da API

A Singular fornece duas versões de endpoints EVENT otimizadas para diferentes arquiteturas de integração.

Seleção de Endpoint: Escolha o endpoint com base em sua arquitetura de integração e estratégia de identificador de dispositivo. 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 do 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 operacional do dispositivo e no método de distribuição de aplicativos.

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 Recuperar IDFV 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 de privacidade para o mesmo programador. Sempre necessário: Deve ser incluído nos dispositivos Google Play, independentemente da disponibilidade do GAID Recuperar ASID Exemplo: `edee92a2-7b2f-45f4-a509-840f170fc6d9`
`amid`	Android (Amazon)	ID de publicidade da Amazonpara dispositivos Amazon Fire sem Google Play Services. Necessário para dispositivos Amazon Recuperar AMID 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 a aplicação não for distribuída através do Google Play. Recuperar ANDI Exemplo: `fc8d449516de0dfb`

Identificadores de ponto de extremidade V2

Requisito apenas 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 do parâmetro

sdid

Plataformas: iOS, Android

Singular Device ID obtida do Singular SDK ou gerada no lado do cliente.

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

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)

Exemplo: com.singular.app

att_authorization_status
iOS

Código de status 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 do evento

Parâmetro	Descrição
`n`	Nome do evento que está a ser monitorizado. Nome do evento obrigatório para receita de anúncios: `__ADMON_USER_LEVEL_REVENUE__` O nome do evento tem de ser TUDO EM MAIÚSCULAS com sublinhados Máximo de 32 caracteres ASCII
`e`	Cadeia de caracteres JSON codificada por URL que especifica atributos de evento personalizados da plataforma de mediação. Atributos obrigatórios: `ad_platform` - (OBRIGATÓRIO) Nome da rede de anúncios Atributos opcionais: `ad_mediation_platform` `ad_type` `ad_group_type` `ad_impression_id` `ad_placement_name` `ad_unit_id` `ad_unit_name` `ad_group_id` `ad_group_name` `ad_group_priority` `ad_placement_id` Estrutura JSON: `{ "ad_platform": "AdMob", "ad_mediation_platform": "admob.AdMobAdapter", "ad_unit_id": "ca-app-pub-6325336052/44923540" }` Exemplo codificado por URL: `%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%5C%2F44923540%22%7D` Nota: omitir atributos sem valores.
`is_admon_revenue`	Especifica se o evento é um evento de receita de monetização de anúncios para métricas de receita de anúncios. Passar `true` para este evento Exemplo: `true`
`is_revenue_event`	Especifica se o evento é um evento de receita para Métricas de receita. Passar `true` para este evento Exemplo: `true`
`amt`	Valor monetário da receita de impressões. Utilizar em conjunto com o parâmetro `cur` Exemplo: `0.00782`
`cur`	Código de moeda ISO 4217de três letras maiúsculas. Utilizar em conjunto com o parâmetro `amt` Exemplo: `USD`

Parâmetros opcionais

Os parâmetros opcionais melhoram o controlo das receitas dos anúncios com contexto e funcionalidade adicionais.

Parâmetros de rede

Parâmetro Descrição

use_ip

Instrui a 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

Exemplos de pedidos

O código de amostra demonstra a integração do ponto de extremidade Ad Revenue 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. Utilize 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',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': '__ADMON_USER_LEVEL_REVENUE__',
    'e': '{"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}',
    'is_admon_revenue': 'true',
    'is_revenue_event': 'true',
    'amt': 0.00782,
    'cur': 'USD'
}

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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=__ADMON_USER_LEVEL_REVENUE__" \
  --data-urlencode 'e={"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}' \
  --data-urlencode "is_admon_revenue=true" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=0.00782" \
  --data-urlencode "cur=USD"

Exemplo HTTP

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=__ADMON_USER_LEVEL_REVENUE__
    &e=%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%2F44923540%22%7D
    &is_admon_revenue=true
    &is_revenue_event=true
    &amt=0.00782
    &cur=USD HTTP/1.1
Host: s2s.singular.net
Accept: application/json

Exemplo Java

// Base URL
String baseUrl = "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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "__ADMON_USER_LEVEL_REVENUE__");
params.put("e", "{\"ad_platform\":\"AdMob\",\"ad_mediation_platform\":\"admob.AdMobAdapter\",\"ad_unit_id\":\"ca-app-pub-6325336052/44923540\"}");
params.put("is_admon_revenue", "true");
params.put("is_revenue_event", "true");
params.put("amt", "0.00782");
params.put("cur", "USD");

// Build URL with encoded parameters
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));
}

// Create connection
URL url = new URL(urlBuilder.toString());
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

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

// Check status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

Códigos de resposta e erros

O ponto de extremidade EVENT devolve códigos de estado HTTP e respostas JSON indicando o sucesso ou a falha do pedido.

Documentação completa sobre erros: Códigos de resposta S2S e tratamento de erros

Teste e validação

Verifique a integração da receita de anúncios 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/launch com todos os parâmetros necessários
Verificar a consola SDK (sessão): Em segundos, o evento SESSION deve aparecer no Console do SDK

SDK Console Session Event

Teste de eventos de receita de anúncios

Acionar impressão de anúncio: Gere uma impressão de anúncio no aplicativo para disparar o retorno de chamada da plataforma de mediação
Validar dados de mediação: Confirmar os dados de impressão enviados para o servidor com todos os atributos necessários da plataforma de mediação
Verificar pedido do servidor: Confirme se o seu servidor envia o pedido EVENT para https://s2s.singular.net/api/v1/evt com todos os parâmetros necessários
Verificar a consola SDK (evento): Dentro de segundos, o evento __ADMON_USER_LEVEL_REVENUE__ deve aparecer na Consola SDK
Repetir os testes: Validar todas as impressões de anúncios enviadas com os valores esperados e os montantes de receita corretos

SDK Console Ad Revenue Event

Verificações críticas:

Confirmar que o evento SESSION ocorre quando a aplicação é aberta/em primeiro plano ANTES de o EVENT ser recebido
Confirmar que os pontos de dados necessários do EVENTO correspondem aos pontos de dados da SESSÃO
Confirmar os detalhes corretos da Plataforma de Mediação passados nos Argumentos do Evento
Confirmar o valor e a moeda corretos da receita

Indicador de sucesso: Se os eventos de receita de anúncios aparecerem no Console do SDK, o teste de integração de receita de anúncios 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

Server-to-Server - Referência da API de rastreio de receitas de anúncios

Referência da API de rastreamento de receita de anúncios

Visão geral

Caso de uso de servidor para servidor

Arquitetura do fluxo de dados

Requisitos críticos

Seleção do ponto final da API

Ponto de extremidade de evento V1

Casos de uso da V1

Ponto de extremidade de evento V2

Casos de uso do V2

Identificadores de dispositivo necessários

Identificadores de Ponto de Extremidade V1

Identificadores específicos da plataforma

Identificadores de ponto de extremidade V2

Requisito apenas de SDID

Parâmetros obrigatórios

Autenticação da API

Parâmetros do dispositivo

Parâmetros da aplicação

Parâmetros do evento

Parâmetros opcionais

Parâmetros de rede

Privacidade dos dados

Suporte para vários dispositivos

Exemplos de pedidos

Exemplo Python

Exemplo cURL

Exemplo HTTP

Exemplo Java

Códigos de resposta e erros

Teste e validação

Procedimento de teste

Validação de ponta a ponta

Teste de eventos de receita de anúncios

Recursos adicionais

Documentação de teste