Referência da API do Endpoint EVENT

Acompanhe eventos in-app e receita para análise de atribuição e otimização de campanhas usando a REST API da Singular por meio de integração server-to-server como alternativa à implementação de SDK.

Visão geral

Caso de uso Server-to-Server

A EVENT API permite o acompanhamento de eventos in-app, em que os apps encaminham dados de interação do usuário para o seu backend, que os transmite aos servidores da Singular para atribuição de eventos e relatórios de análise de receita.

Recursos compatíveis:

• Atribuição de eventos: Conecte ações do usuário a campanhas de marketing
• Acompanhamento de receita: Meça e atribua compras in-app e transações
• Eventos personalizados: Acompanhe qualquer interação do usuário, de registros a conclusões de fases
• Propriedades de eventos: Anexe dados contextuais aos eventos para uma análise mais aprofundada

Arquitetura do fluxo de dados

O acompanhamento de eventos server-to-server segue um processo de transmissão de dados em quatro etapas.

1. Coleta no cliente: O app coleta dados de eventos e identificadores de dispositivo
2. Transmissão ao servidor: O app encaminha os dados de eventos ao seu servidor backend
3. Consulta ao device graph: O servidor recupera ou atualiza detalhes do dispositivo a partir do device graph da Singular
4. Chamada à Event API: O servidor envia o evento ao endpoint da REST API da Singular

Requisitos críticos

Diretrizes de acompanhamento de eventos

Implemente o acompanhamento de eventos seguindo as práticas recomendadas da Singular para convenções de nomenclatura e estrutura de dados.

Definição de eventos

Definindo eventos

Antes de implementar a integração S2S, defina a lista completa de eventos que a sua organização deseja acompanhar para análise de desempenho de campanhas.

Guia de planejamento de eventos: Definindo eventos in-app

Impacto da nomenclatura de eventos: Os nomes de eventos passados à Singular determinam diretamente como os eventos aparecem em relatórios, exportações e postbacks.

Nomenclatura padrão de eventos

Limitações de caracteres

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 de plataforma (IDFA, IDFV, AIFA, ASID, etc.).

Recomendado para:

• Puramente server-side: Integrações server-side sem implementação do Singular SDK
• Híbrida (não-SDID): Integrações híbridas em que o Singular SDK 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 Singular SDK acompanha sessões usando o SDID e o servidor envia eventos usando o mesmo SDID.

Recomendado para:

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

URL do endpoint:

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

Variante Web (p=Web)

As integrações web usam esse mesmo endpoint EVENT com p=Web . Não há chamada de SESSION web: o primeiro __PAGE_VISIT__ evento com conversion_event=true estabelece o touchpoint de atribuição no lugar de um launch.

Parâmetros específicos de web

Estes parâmetros se aplicam quando p=Web . Os parâmetros compartilhados ( a , i , ip , sdid , custom_user_id ) estão definidos em Fundamentos de S2S .

Web click IDs: passe os click IDs de parceiros ( ScCid , ttclid , gclid / gbraid / wbraid , dclid , fbclid , rdt_uuid ) dentro do parâmetro de evento e .

Identificadores de dispositivo obrigatórios

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

Identificadores do endpoint V1

Identificadores específicos de plataforma

O Event Endpoint V1 requer identificadores de publicidade específicos de 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 somente de SDID

O Event Endpoint V2 requer apenas o Singular Device ID (SDID) para todas as plataformas, simplificando a identificação de dispositivos.

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

Parâmetros opcionais

Os parâmetros opcionais aprimoram o acompanhamento de eventos com contexto e funcionalidade adicionais.

Parâmetros de timestamp

Atributos de evento

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

%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

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 a Cross-Device

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

Suporte a SKAdNetwork

Acompanhamento de receita

Acompanhe compras in-app e eventos de receita com validação adequada e tratamento de moeda.

Parâmetros de receita obrigatórios

Acompanhamento básico de receita

Parâmetros mínimos obrigatórios para o acompanhamento de eventos de receita quando você realiza a sua própria validação de receita.

Parâmetros de validação de receita

Receita validada pela Singular

Parâmetros opcionais para que a Singular realize a validação de receita no servidor com as App Stores.

MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==

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

TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==

Exemplos de requisição

O código de exemplo demonstra a integração do endpoint EVENT 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',
    '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())

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

GET /api/v1/evt
    ?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_cart 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("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 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 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 Singular SDK Console para validação de dados em tempo real.

Procedimento de teste

Validação de ponta a ponta

1. Registrar dispositivo de teste: Obtenha o advertising ID do dispositivo e adicione-o ao Singular SDK Console
2. Habilitar log do Console: Adicione o identificador de dispositivo no SDK Console para capturar os dados de teste
3. Usar App ID de desenvolvimento: Sobrescreva o identificador de app com a 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 ao seu servidor
6. Verificar 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 SDK Console (SESSION): Em segundos, o evento SESSION deve aparecer no SDK Console

Teste de eventos

1. Disparar evento: Prossiga para disparar um evento no app
2. Validar dados do evento: Confirme que o evento foi enviado ao seu servidor com todos os pontos de dados obrigatórios da Singular
3. Verificar 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 SDK Console (EVENT): Em segundos, o EVENT deve aparecer no SDK Console
5. Repetir os testes: Valide que todos os eventos foram enviados com os valores esperados

Recursos adicionais

Documentação de testes

Guia completo de testes: Guia de testes de integração S2S