Referência da API de rastreamento de receita de anúncios
Caso de uso de servidor para servidor
A Singular permite o rastreamento da receita de anúncios por meio da API EVENT. Ao encaminhar os detalhes da receita no nível de impressão da(s) sua(s) plataforma(s) de mediação para o seu servidor usando manipuladores de eventos pagos, a Singular processa esses dados para uma integração perfeita em relatórios, logs de exportação e postbacks. A plataforma também suporta conversão automática de moeda alinhada com as configurações preferidas da sua organização.
A API REST do Singular permite a integração direta de servidor para servidor como uma alternativa ao SDK. Enquanto o SDK recolhe automaticamente os dados do dispositivo e da aplicação, a abordagem S2S requer que:
- Recolher os pontos de dados necessários da API EVENT da sua aplicação
- Recolha os pontos de dados relevantes da plataforma de mediação
- Encaminhe estes dados para o seu servidor
- Enviar o evento'__ADMON_USER_LEVEL_REVENUE__' para a Singular via API REST
Pontos principais
- Flexibilidade: Controlo total sobre a recolha e transmissão de dados
- Paridade de recursos: Suporta todas as funcionalidades do SDK quando os dados adequados são fornecidos
- Caminho de integração: Cliente → Seu Servidor → API Singular
- Processamento em tempo real: Um pedido de cada vez, sem processamento em lote
- Fluxo de dados sequencial: Os eventos devem ser processados por ordem cronológica
- Deduplicação de dados: O Singular não deduplica os dados recebidos. Recomenda-se enviar uma (1) solicitação bem-sucedida e salvar os logs para o caso de uma solicitação ser reproduzida novamente.
- Validação de dados: Os dados no nível do dispositivo são permanentes e não podem ser excluídos após a ingestão. Implemente uma validação completa dos dados antes de enviá-los à Singular para garantir a precisão.
Pré-requisitos
- Uma sessão deve ser estabelecida antes que qualquer rastreamento de evento seja recebido
- Uma ordem de sessão inválida resultará em inconsistências de dados
- Colete atributos de dados da Plataforma de Mediação diretamente do SDK de Mediação. Para obter detalhes de implementação e pontos de dados necessários, consulte nosso Guia do SDK e a documentação de Mediação específica da plataforma.
Introdução
A documentação do ponto final EVENT fornece:
- Parâmetros obrigatórios
- Parâmetros opcionais
- Exemplos de pedidos
- Códigos de resposta e erros
- Teste de eventos
Esta abordagem do lado do servidor dá-lhe mais controlo sobre a sua integração, mantendo todas as capacidades do SDK.
Ponto de extremidade da API de eventos
Método HTTP e ponto final de evento
GET https://s2s.singular.net/api/v1/evtParâmetros necessários
A tabela abaixo lista os parâmetros necessários para enviar eventos de receita de monetização de anúncios por meio da API de eventos. Esses parâmetros devem ser incluídos como parâmetros de consulta.
GET /api/v1/evt?param1=value1¶m2=value2- Todos os parâmetros necessários devem ser incluídos nas solicitações da API de eventos
- Os parâmetros devem seguir o formato e os tipos de dados especificados
| Parâmetros necessários | |
|---|---|
| Chave da API | |
| Parâmetro | Descrição |
|
O parâmetro a especifica a chave do SDK Singular. Recupere a Chave SDK na IU do Singular, em Ferramentas de Desenvolvedor no Menu Principal. Nota: Não use a chave da API de relatório, pois isso resultará em dados rejeitados. Exemplo de valor: |
| Identificador de dispositivo Parâmetros | |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro idfa especifica o Identificador para Anunciantes (IDFA), que ajuda os anunciantes a rastrear e atribuir acções do utilizador (por exemplo, cliques em anúncios, instalações de aplicações) a campanhas específicas, permitindo uma segmentação precisa dos anúncios e a otimização das campanhas. A partir do iOS 14.5, os utilizadores devem aderir através da estrutura App Tracking Transparency (ATT) para que as aplicações possam aceder ao IDFA. Se os utilizadores não optarem por aderir ao IDFA, este não estará disponível, o que resulta na limitação das capacidades de rastreio.
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro idfv especifica o Identificador para Fornecedores (IDFV), um identificador único atribuído pela Apple a um dispositivo, que é específico de um determinado fornecedor ou programador. Permanece consistente em todas as aplicações do mesmo fornecedor num determinado dispositivo, permitindo ao fornecedor seguir o comportamento e as interações do utilizador no seu ecossistema de aplicações sem identificar o utilizador pessoalmente.
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro aifa especifica o Google Advertising Identifier (GAID), também conhecido como AIFA no singular ou Android Advertising ID (AAID). Este identificador é um identificador único, redefinível pelo utilizador, atribuído a dispositivos Android. Ajuda os anunciantes e os programadores de aplicações a rastrear e atribuir acções do utilizador (por exemplo, cliques em anúncios, instalações de aplicações) em aplicações a campanhas específicas, permitindo uma segmentação precisa dos anúncios e a otimização das campanhas, mantendo a privacidade do utilizador.
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro asid especifica o ID do conjunto de aplicações do Android. O ASID fornece uma forma de os programadores acompanharem os utilizadores nas suas próprias aplicações de uma forma consciente da privacidade. É particularmente útil para análises e prevenção de fraudes, mas não pode ser utilizado para fins publicitários, como anúncios personalizados ou medições.
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro amid especifica que a ID de publicidade é um identificador exclusivo e redefinível pelo utilizador que ajuda a proteger a privacidade do utilizador. Se recolher informações sobre o comportamento de um utilizador para apresentar anúncios baseados em interesses ou para gerar análises, tem de utilizar a ID de publicidade; não pode ser utilizado qualquer outro identificador ou método de rastreio. Os utilizadores podem redefinir a ID de publicidade ou optar por não utilizar anúncios baseados em interesses.
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro oaid especifica o Open Advertising Identifier (OAID). O OAID é um identificador único e anónimo utilizado para fins publicitários em dispositivos Android, especialmente os fabricados na China. Foi introduzido pela Mobile Security Alliance (MSA) como alternativa ao GAID (Advertising ID) da Google para dispositivos em que o Google Play Services não está disponível ou não é suportado, como no mercado chinês. O OAID é utilizado principalmente para atribuição de publicidade e seguimento de utilizadores em ambientes onde o Google Play Services é restrito, permitindo aos anunciantes e programadores seguir o comportamento dos utilizadores mantendo o anonimato. O OAID está disponível na maioria dos dispositivos Android fabricados na China, incluindo os de marcas como a Huawei, a Xiaomi e outras. Pode ser acedido através do MSA SDK ou dos Huawei Mobile Services (HMS).
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro andi especifica o ID do Android, que é um identificador único de 64 bits gerado pelo sistema operativo Android quando um dispositivo é configurado pela primeira vez. Foi concebido para ser persistente ao longo da vida útil do dispositivo, mas pode ser reposto em determinadas condições, como uma reposição de fábrica. O ID Android é único para cada dispositivo e, a partir do Android 8.0 (Oreo), tem um âmbito por aplicação e por utilizador. Isto significa que diferentes aplicações no mesmo dispositivo receberão diferentes IDs Android, a menos que partilhem a mesma chave de assinatura. A ID Android mantém-se constante, a menos que o dispositivo seja reiniciado de fábrica ou se uma aplicação for desinstalada e reinstalada após uma atualização OTA (over-the-air).
Exemplo de valor: |
| Parâmetros do dispositivo | |
| Parâmetro | Descrição |
|
O parâmetro p especifica a plataforma da aplicação. A lista seguinte contém os valores de parâmetros sensíveis a maiúsculas e minúsculas permitidos:
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro ip especifica o endereço IP público (IPV4) do dispositivo. O IPV6 não é suportado. Exemplo Valor: |
| Parâmetro | Descrição |
|
O parâmetro ve indica a versão do sistema operativo do dispositivo no momento do evento. Exemplo de valor: |
| Parâmetros da aplicação | |
| Parâmetro | Descrição |
|
O parâmetro i especifica o identificador da aplicação. Este é um valor sensível a maiúsculas e minúsculas :
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro att_authorization_status especifica o código de estado App Tracking Transparency (ATT). A partir do iOS 14.5, a solicitação App Tracking Transparency (ATT) é necessária para acessar o identificador IDFA. Nota: Mesmo que não implemente a solicitação ATT, exigimos que passe o estado de autorização ATT com o valor'0', indicando "indeterminado". Os valores suportados são:
Exemplos: |
| Parâmetros de eventos | |
| Parâmetro | Descrição do evento |
|
O parâmetro n indica o nome do acontecimento que está a ser controlado.
|
| Parâmetro | Descrição |
|
O parâmetro e especifica atributos de eventos personalizados no formato JSON. O único atributo obrigatório é o "ad_platform". Todos os outros atributos são opcionais. Os atributos possíveis são:
Nota: Os atributos sem valores devem ser omitidos. Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro is_admon_revenue especifica se o evento é um evento de receita de monetização de anúncios e deve ser usado para métricas de receita de anúncios.
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro is_revenue_event especifica se o evento é um evento de receita e deve ser usado para métricas de receita.
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro amt indica o valor da moeda.
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro cur indica o código de três letras maiúsculas da moeda ISO 4217.
Exemplo de valor: |
Corpo do pedido
Não forneça um corpo do pedido quando chamar este método. O pedido deve ser enviado utilizando o método GET com parâmetros de consulta.
Exemplos de pedidos
Os seguintes exemplos de código podem não representar todos os parâmetros suportados. Ao implementar o pedido, certifique-se de que inclui todos os parâmetros necessários, conforme listado acima, e valide se os valores corretos estão a ser passados antes de enviar dados de uma instância de produção. Aconselha-se a utilização de um identificador de aplicação único para desenvolvimento e teste.
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())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"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 application-level status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
// Disconnect
conn.disconnect();Parâmetros opcionais
A tabela seguinte lista os parâmetros opcionais que este ponto final suporta. Todos os parâmetros listados são parâmetros de consulta.
| Parâmetros opcionais | |
|---|---|
| Parâmetros de dispositivo e rede | |
| Parâmetro | Descrição |
|
O parâmetro use_ip diz ao Singular para extrair o endereço IP da solicitação HTTP em vez do parâmetro 'ip'. Passe'true' para usar esse recurso.
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro country (país ) deve conter o código de duas letras ISO 3166-1 alfa-2 do país do utilizador no momento da execução do evento. Este parâmetro só é necessário quando:
Exemplo de valor: |
| Privacidade dos dados | |
| Parâmetro | Descrição |
|
O parâmetro data_sharing_options especifica o consentimento do utilizador final para partilhar informações. Se definido, este valor deve ser mantido e transmitido em todos os pedidos subsequentes de "SESSION" e "EVENT" para o utilizador.
O valor tem de ser uma cadeia de caracteres JSON codificada por URL. Exemplo de valor: |
| Suporte para vários dispositivos | |
| Parâmetro | Descrição |
|
O parâmetro custom_user_id especifica o seu ID de utilizador interno. Exemplo de valor: |
Teste de eventos
Depois de fazer a integração servidor a servidor, é essencial verificar se o Singular recebe dados antes de entrar em operação com uma instância de produção. Consulte o nosso guia de testes para obter mais detalhes. Em um nível alto, as seguintes etapas devem ser seguidas:
- Obtenha a ID de publicidade do seu dispositivo de teste e adicione a ID no Singular SDK Console.
- Abra o Singular SDK Console e adicione o identificador do dispositivo para iniciar a captura de dados.
- Substitua o identificador do aplicativo por um identificador de aplicativo de desenvolvimento(com.singular.app.dev) para manter os dados e eventos de teste separados dos dados de produção.
- Criar ou abrir a aplicação a partir de um estado terminado
- Valide se a abertura da aplicação é enviada para o seu servidor com todos os pontos de dados Singular necessários
- Valide se o seu servidor dispara a Notificação de Sessão para o ponto de extremidade Singular'launch' com todos os pontos de dados necessários.
- Após alguns segundos, o evento de sessão deve ser exibido no Console do SDK do Singular.
- Prossiga com o acionamento de um evento no aplicativo.
- Valide se o Event é enviado para o seu servidor com todos os pontos de dados Singular necessários
- Valide que seu servidor dispara a Notificação de Evento para o endpoint Singular'evt' com todos os pontos de dados necessários.
- Após alguns segundos, o evento deve ser exibido no console do Singular SDK.
- Repita o teste para validar se todos os eventos são enviados como esperado e com os valores esperados.
Verificações importantes
- Confirme que o evento de sessão ocorre na abertura da aplicação ou em primeiro plano e antes de o evento ser recebido.
- Confirme que os pontos de dados necessários do evento correspondem aos pontos de dados da sessão.
- Confirmar que os detalhes corretos da Plataforma de Mediação são passados nos Argumentos do Evento
- Confirmar o valor e a moeda corretos da receita
Se vir os seus Eventos na Consola SDK, concluiu um teste de ponta a ponta do tratamento de Eventos!