Referência da API de Rastreamento de Receita de Anúncios

Rastreie a receita de monetização de anúncios em nível de impressão para análise de atribuição e otimização de campanhas usando a API REST da Singular por meio de integração server-to-server como alternativa à implementação por SDK.

Visão geral

Caso de uso Server-to-Server

A API de Receita de Anúncios permite o rastreamento de monetização de anúncios em nível de impressão, no qual os apps encaminham dados de receita das plataformas de mediação para o seu backend, que transmite aos servidores da Singular para análise e relatórios de receita de anúncios.

Recursos suportados:

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

Arquitetura de fluxo de dados

O rastreamento de receita de anúncios server-to-server segue um processo de transmissão de dados em quatro etapas.

1. Coleta no cliente: O app coleta dados de receita em nível de impressão do SDK da plataforma de mediação
2. Transmissão para o servidor: O app encaminha os dados de receita de anúncios para o seu servidor backend
3. Consulta ao device graph: O servidor recupera ou atualiza os detalhes do dispositivo no device graph da Singular
4. Chamada à Event API: O servidor envia o evento __ADMON_USER_LEVEL_REVENUE__ para o endpoint da API REST da Singular

Requisitos críticos

Seleção do endpoint da API

A Singular oferece duas versões do endpoint EVENT otimizadas para diferentes arquiteturas de integração.

Event Endpoint V1

Casos de uso do 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:

• Puramente server-side: Integrações server-side sem implementação do SDK da Singular
• Híbrido (não-SDID): Integrações híbridas em que o SDK da Singular não usa o Singular Device ID (SDID)

URL do endpoint:

GET https://s2s.singular.net/api/v1/evt

Event Endpoint V2

Casos de uso do V2

Use o Event Endpoint V2 para integrações híbridas em que o SDK da Singular rastreia as sessões usando o SDID e o servidor envia eventos usando o mesmo SDID.

Recomendado para:

• Híbrido (baseado em SDID): O SDK da Singular rastreia sessões com SDID e os eventos server-side usam o mesmo SDID
• Identificadores simplificados: Implementações que evitam identificadores de dispositivo específicos da plataforma (IDFA, AIFA, etc.)

URL do endpoint:

GET https://s2s.singular.net/api/v2/evt

Identificadores de dispositivo necessários

Os requisitos de identificador de dispositivo variam conforme a versão do endpoint e a plataforma. Revise os requisitos específicos da plataforma abaixo.

Identificadores do endpoint 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 do app.

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Identificadores do endpoint 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âmetros obrigatórios

Todas as requisições EVENT devem incluir estes parâmetros obrigatórios além dos identificadores de dispositivo.

Autenticação da API

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Parâmetros de dispositivo

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Parâmetros de aplicativo

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Parâmetros de evento

__ADMON_USER_LEVEL_REVENUE__

{
  "ad_platform": "AdMob",
  "ad_mediation_platform": "admob.AdMobAdapter",
  "ad_unit_id": "ca-app-pub-6325336052/44923540"
}

%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

Parâmetros opcionais

Os parâmetros opcionais aprimoram o rastreamento de receita de anúncios com contexto adicional e funcionalidades extras.

Parâmetros de rede

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Privacidade de dados

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Suporte cross-device

Estes são parâmetros S2S compartilhados definidos uma única vez em Fundamentos de S2S .

Exemplos de requisição

O código de amostra demonstra a integração do endpoint EVENT de Receita de Anúncios em várias linguagens de programação.

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

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"

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

// 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 endpoint EVENT retorna códigos de status HTTP e respostas em JSON que indicam o sucesso ou a falha da requisição.

Documentação completa de erros: Códigos de Resposta e Tratamento de Erros de S2S

Testes e validação

Verifique a integração de receita de anúncios S2S antes da implantação em produção usando o Console de SDK da Singular para validação de dados em tempo real.

Procedimento de teste

Validação de ponta a ponta

1. Registrar dispositivo de teste: Obtenha o ID de publicidade do dispositivo e adicione ao Console de SDK da Singular
2. Habilitar log do Console: Adicione o identificador do dispositivo no Console de SDK para capturar dados de teste
3. Usar o App ID de desenvolvimento: Substitua o identificador do app pela versão de desenvolvimento (por exemplo, com.singular.app.dev ) para separar os dados de teste dos de produção
4. Compilar e iniciar: Compile ou abra o app a partir do estado encerrado
5. Validar dados do cliente: Confirme que o app envia todos os pontos de dados obrigatórios da Singular para o seu servidor
6. Verificar a SESSION: Confirme que o seu servidor envia a requisição SESSION para https://s2s.singular.net/api/v1/launch com todos os parâmetros obrigatórios
7. Verificar o Console de SDK (Session): Em poucos segundos, o evento SESSION deve aparecer no Console de SDK

Teste de evento de receita de anúncios

1. Acionar impressão de anúncio: Gere uma impressão de anúncio no app para disparar o callback da plataforma de mediação
2. Validar dados de mediação: Confirme que os dados de impressão foram enviados ao seu servidor com todos os atributos obrigatórios da plataforma de mediação
3. Verificar a requisição do servidor: Confirme que o seu servidor envia a requisição EVENT para https://s2s.singular.net/api/v1/evt com todos os parâmetros obrigatórios
4. Verificar o Console de SDK (Event): Em poucos segundos, o evento __ADMON_USER_LEVEL_REVENUE__ deve aparecer no Console de SDK
5. Repetir os testes: Valide que todas as impressões de anúncio foram enviadas com os valores esperados e os valores de receita corretos

Recursos adicionais

Documentação de testes

Guia completo de testes: Guia de Testes de Integração S2S