Referência da API do ponto de extremidade EVENT
Caso de utilização de servidor para servidor
A API EVENT permite o rastreamento de eventos em seus aplicativos. Quando seu aplicativo encaminha dados específicos do dispositivo para seu servidor, que então os transmite para os servidores da Singular, a plataforma processa essas informações para: Atribuição de eventos e métricas de receita de aplicativos. Esses dados processados preenchem automaticamente seus relatórios, logs de exportação e postbacks configurados, fornecendo análises abrangentes para suas campanhas de marketing.
A API REST da Singular permite a integração direta de servidor para servidor como alternativa ao SDK. Enquanto o SDK recolhe automaticamente os dados do dispositivo e da aplicação, a abordagem S2S requer que o utilizador:
- Recolher os pontos de dados necessários da sua aplicação
- Encaminhar estes dados para o seu servidor
- Atualizar/obter detalhes do dispositivo a partir do gráfico do dispositivo
- Encaminhar o evento para a Singular via API REST
Pontos-chave
- 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
Primeiros passos
A documentação do endpoint 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.
Relatórios de eventos
O Singular pode recolher dados sobre eventos in-app para ajudar a analisar o desempenho das suas campanhas de marketing. Os eventos podem incluir qualquer interação do utilizador, desde logins e registos até à subida de nível numa aplicação de jogos.
Antes de implementar uma integração SDK/S2S com Singular, você deve ter uma lista dos eventos que sua organização deseja rastrear (consulte Definindo eventos no aplicativo).
O nome do evento que você inclui na chamada é como o evento será identificado nos relatórios, exportações e postbacks do Singular.
Observações:
- A Singular recomenda passar eventos usando a convenção padrão de nomenclatura de eventos e atributos da Singular. O uso de eventos padrão simplifica o mapeamento e a compatibilidade com os eventos padrão de seus parceiros em integrações.
- É altamente recomendável passar nomes de eventos e outros atributos em inglês para compatibilidade com quaisquer parceiros de terceiros e soluções de análise que você possa querer usar.
Importante:
- Os nomes de eventos são limitados a 32 caracteres ASCII. Para caracteres não-ASCII, o limite é de 32 bytes depois de convertidos para UTF-8.
- Os atributos e valores do evento estão limitados a 500 caracteres ASCII.
Ponto de extremidade da API de eventos
Método HTTP e ponto final do evento
GET https://s2s.singular.net/api/v1/evtParâmetros necessários
A tabela seguinte lista os parâmetros necessários que este ponto final suporta. Todos os parâmetros listados são parâmetros de consulta.
GET /api/v1/evt?param1=value1¶m2=value2- Todos os parâmetros necessários têm de ser incluídos nos pedidos da API EVENT
- 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 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: |
| Parâmetros do identificador do dispositivo | |
| 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 têm de 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âmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro sdid especifica o ID de Dispositivo Singular.
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro sing é restrito a clientes Enterprise e especifica um identificador definido pelo cliente. Apenas utilizado em utilizações especiais em que todos os outros identificadores não estão disponíveis. Este identificador deve ser ativado pelo Engenheiro de Soluções Singular numa base App-by-App. 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 de 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âmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro ma especifica a marca do hardware do dispositivo, normalmente o nome virado para o consumidor. Este parâmetro deve ser utilizado com o parâmetro model. Como obter a marca do dispositivo Exemplos: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro mo especifica o modelo do hardware do dispositivo. Este parâmetro deve ser utilizado com o parâmetro make. Como obter o modelo do dispositivo Exemplos: |
| Parâmetro | Descrição |
Plataformas suportadas:
|
O parâmetro lc especifica a etiqueta de localidade IETF para o dispositivo, utilizando o código de duas letras do idioma e do país, separados por um sublinhado. Como recuperar a localidade do dispositivo Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro bd especifica a construção do dispositivo, codificada por URL. Como recuperar a compilação do dispositivo Exemplo de valor: |
| Parâmetros da aplicação | |
| Parâmetro | Descrição |
|
O parâmetro i indica o identificador da aplicação. Este é o Nome do Pacote para Android ou o ID do Pacote para iOS ou da sua aplicação. valores de parâmetro sensíveis 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, o prompt App Tracking Transparency (ATT) é necessário para aceder ao 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 |
|
O parâmetro n indica o nome do acontecimento que está a ser controlado.
Exemplo de valor: |
Corpo do pedido
Não forneça um corpo de solicitação ao 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 parâmetro único `i` (identificador da aplicação) 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',
'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
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"HTTP
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
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("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 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 carimbo de data/hora | |
| Parâmetro | Descrição |
|
O parâmetro utime especifica a hora do evento em hora UNIX de 10 dígitos.
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro umilisec especifica a hora do evento em milissegundos e 13 dígitos da hora UNIX.
Exemplo de valor: |
| Parâmetros do dispositivo e da rede | |
| Parâmetro | Descrição |
|
O parâmetro global_properties aceita um objeto JSON codificado por URL que contém até 5 pares de valores chave. Cada chave e valor pode ter um comprimento máximo de 200 caracteres. O objeto JSON tem de ser:
Exemplo de valor: |
| 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: |
| Parâmetros do evento | |
| Parâmetro | Descrição |
|
O parâmetro e especifica atributos de evento personalizados no formato JSON.
Exemplo de valor: |
| Parâmetros de receita | |
| Parâmetro | Descrição |
|
O parâmetro is_revenue_event especifica se o evento é um evento de receita.
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro amt indica o montante em 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: |
| Parâmetro | Descrição |
Plataformas suportadas:
|
O parâmetro purchase_receipt especifica o recibo recebido de uma compra. Consulte as instruções abaixo sobre como o obter no Android e no iOS
Exemplo (iOS): Exemplo (Android): |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro receipt_signature especifica a assinatura utilizada para assinar o recibo de compra
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro purchase_product_id indica o identificador SKU do produto
Exemplo de valor: |
| Parâmetro | Descrição |
|
O parâmetro purchase_transaction_id especifica o identificador da transação
Exemplo (iOS): Exemplo (Android): |
| Privacidade dos dados | |
| Parâmetro | Descrição |
|
O parâmetro data_sharing_options especifica o consentimento do utilizador final para partilhar informações. Se for 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: |
| Suporte iOS SkAdNetwork | |
| Parâmetro | Descrição |
Plataformas suportadas:
|
O parâmetro skan_conversion_value especifica o valor de conversão mais recente da SKAdNetwork no momento da notificação deste evento(saiba mais sobre a implementação da SKAdNetwork).
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro skan_first_call_timestamp especifica o carimbo de data/hora Unix da primeira chamada à API SkAdNetwork subjacente(saiba mais sobre a implementação da SKAdNetwork).
Exemplo de valor: |
| Parâmetro | Descrição do parâmetro |
Plataformas suportadas:
|
O parâmetro skan_last_call_timestamp especifica o carimbo de data/hora Unix da última chamada à API SkAdNetwork subjacente no momento da notificação deste evento(saiba mais sobre a implementação da SKAdNetwork).
Exemplo de valor: |
Teste de eventos
Depois de fazer a integração servidor a servidor, é essencial verificar se o Singular recebe os dados antes de colocar em funcionamento 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.
- 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 se os pontos de dados necessários do evento correspondem aos pontos de dados da sessão.
Se vir os seus eventos na consola SDK, concluiu um teste de ponta a ponta do tratamento de eventos!