Endpoint de referência de API servidor a servidor (S2S)

Este artigo de referência lista os pontos de extremidade da API oferecidos pela Singular para integrações S2S.

Observação: as integrações de servidor para servidor estão disponíveis apenas para clientes Enterprise.

Atualização [novembro de 2021]: Agora você deve relatar o referenciador de instalação do Android por meio do ponto de extremidade de notificação de sessão (e não da notificação de evento). Isso torna o referenciador de instalação disponível para a Singular imediatamente quando o usuário abre o aplicativo e segue as práticas recomendadas do Google. Para obter mais informações, consulte Envio do referenciador de instalação do Google Play (Android).

 

Códigos de autenticação e status

Qualquer chamada para a API S2S deve incluir sua chave SDK. Para recuperá-la, faça login no Singular e vá para "Developer Tools > SDK Integration > SDK Keys".

O código de status HTTP retornado em qualquer chamada para a API S2S é 200 se a chamada for bem-sucedida. Qualquer outro código significa que você deve tentar novamente a chamada.

Lista de pontos de extremidade da API S2S da Singular

Os seguintes pontos de extremidade da API estão disponíveis:

Notificação de sessão GET https://s2s.singular.net/api/v1/launch Relata uma nova sessão para a Singular.
Notificação de evento GET https://s2s.singular.net/api/v1/evt Relata um evento in-app para a Singular.

Ponto de extremidade de notificação de sessão

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

Use o endpoint de notificação de sessão para relatar uma sessão à Singular.

Parâmetros necessários da sessão

Parâmetro Descrição da sessão Plataformas compatíveis Exemplo
a Chave do SDK Singular. iOS, Android,
PC, Console
your_org_name_sh868sdjv
p Uma das seguintes plataformas:
Android, iOS, PC, Xbox, Playstation, Nintendo, MetaQuest or CTV
iOS, Android,
PC, Console
Android
i Nome do pacote (Android) ou ID do pacote (iOS) do seu aplicativo. iOS, Android,
PC, Console
com.singular.app
ip O IP do dispositivo. iOS, Android,
PC, Console
172.58.29.235
ve Versão do sistema operacional do dispositivo no momento da sessão. iOS, Android,
PC, Console
9.2
install_ref Informações do referenciador de instalação do Google Android Saiba mais
meta_ref Informações do referenciador da instalação do Meta Android Saiba mais
ma Marca do hardware do dispositivo, normalmente o nome voltado para o consumidor (por exemplo, Samsung, LG, Apple). Esse parâmetro deve ser usado com o parâmetro de modelo. iOS, Android samsung
mo Modelo do hardware do dispositivo (por exemplo, iPhone 4S, Galaxy SIII). Esse parâmetro deve ser usado com o parâmetro make. iOS, Android SM-G935F
lc A tag local da IETF para o dispositivo, usando o idioma de duas letras e o código do país separados por um sublinhado. iOS, Android en_US
bd Construção do dispositivo, codificada por URL iOS, Android Build%2F13D15
openuri Se o aplicativo for aberto por meio de qualquer link profundo/link universal/link de aplicativo, o valor codificado da URL do link profundo iOS, Android myapp%3A%2F%2Fhome%2Fpage%3 Fqueryparam1%3D value1%26queryparam2%3 Dvalue2
idfa Somente para aplicativos iOS. ID de publicidade bruta em letras maiúsculas com traços. iOS DFC5A647-9043-4699-B2A5-76F03A97064B
idfv Somente para aplicativos iOS. IdentifierForVendor bruto em maiúsculas com traços. iOS 21DB6612-09B3-4ECC-84AC-B353B0AF1334
aifa ID de publicidade bruta do Google em letras minúsculas com traços. Android (Google Play) 8ecd7512-2864-440c-93f3-a3cabe62525b
asid A ID do conjunto de aplicativos (para dispositivos Android 12+). Isso deve ser enviado se a ID de publicidade do Google (aifa) não estiver disponível. Saiba mais sobre o assunto Android (Google Play) edee92a2-7b2f-45f4-a509-840f170fc6d9
amid O ID de publicidade da Amazon com traços. Disponível em dispositivos da Amazon. Android (Amazon) df07c7dc-cea7-4a89-b328-810ff5acb15d
oaid O Open Advertising ID com traços, geralmente usado em dispositivos domésticos da China. Disponível com o SDK MSA integrado ou com o SDK OAID da Huawei Android 01234567-89abc-defe-dcba-987654321012
andi

Somente para aplicativos Android que não sejam do Google Play. ID android bruto em letras minúsculas.

Envie isso somente se não houver outros identificadores de dispositivo disponíveis.

Android fc8d449516de0dfb
sdid

PC/Console: Um UUIDv4 gerado no lado do cliente que representa uma instalação de aplicativo exclusiva.

PC, Console 40009df0-d618-4d81-9da1-cbb3337b8dec
dnt Passe 1 se a opção "não rastrear" estiver ativada, 0 se a opção "não rastrear" estiver desativada. iOS, Android 1
app_v Versão do aplicativo iOS, Android 1.2.3
install_source

Nome do pacote de origem da instalação no Android, por exemplo: 'com.android.vending'. Para recuperar esse valor, use InstallSourceInfo.getInitiatingPackageName()

 

A loja de instalação no PC, os valores suportados/recomendados são: steam, epic, microsoftstore, humblestore, gog, selfdistributed

Android, PC

Android:

com.vending.android (Android)

steam (PC)


install_receipt O recibo recebido da instalação. Saiba como recuperá-lo em Recibo de instalação do iOS iOS MIISqwYJKoZI...cNqts0jvcNvPcK7 yuj0KhJ9nTTQ54kDKfReihzc6aw==
install Sinalizador de instalação. 'true' se a sessão foi a primeira após a instalação do aplicativo. Caso contrário, "false". Necessário para recursos de rastreamento de reinstalação. iOS, Android,
PC, Console
false
install_time A hora da primeira instalação do aplicativo como hora UNIX. Para recuperar esse valor, use o link na plataforma. iOS, Android 1510040127
update_time A hora da última atualização do aplicativo como hora UNIX. Para recuperar esse valor, use o link na plataforma. iOS, Android 1510040127
ddl_enabled Sinalizador de deep link diferido. 'true' se o servidor espera que um URL de deep link diferido seja retornado. Caso contrário, "false". Consulte nossa seção sobre deferred deep linking para obter mais detalhes iOS, Android true
singular_link_resolve_required Usado para resolver um link curto Singular. Deve ser enviado com um valor no "openuri" que seja um link curto Singular. Consulte Manuseio de links curtos.

iOS,
Android

true
att_authorization_status *

Disponível no iOS 14 e superior. O status de autorização da Transparência do rastreamento de aplicativos.

Os valores compatíveis são:

  • 0 - Undetermined IDFA indisponível no iOS 14.5+
  • 1 - Restricted IDFA indisponível, o usuário desativou a opção de mostrar o prompt ATT. IDFA indisponível.
  • 2 - Denied IDFA unavailable (indisponível), o usuário viu o prompt ATT e negou a autorização. IDFA unavailable (indisponível)
  • 3 - Authorized O usuário viu o prompt da ATT e concedeu a autorização. IDFA está disponível
iOS 3

*Observação: a partir do iOS 14.5, o prompt do App Tracking Transparency (ATT) é necessário para acessar o IDFA. Mesmo que você não implemente o prompt ATT, exigimos que você passe o status de autorização ATT para a Singular (com o valor "0", indicando "indeterminado").

Parâmetros opcionais da sessão

Parâmetro Descrição Plataformas suportadas Nome do aplicativo Exemplo
custom_user_id User ID iOS, Android,
PC, Console
 123456789abcd
n Nome do aplicativo legível por humanos, conforme exibido na interface do usuário. iOS, Android,
PC, Console
MyCoolApp
utime Hora da sessão em tempo UNIX. iOS, Android,
PC, Console
1483228800
umilisec Tempo da sessão em milissegundos no horário do UNIX. iOS, Android,
PC, Console
1483228800000
dntoff Passe 0 se "não rastrear" estiver ativado ou 1 se "não rastrear" estiver desativado. iOS, Android 0
c Tipo de conexão 'wifi' ou 'carrier'. iOS, Android wifi
cn Nome da operadora do provedor de Internet. iOS, Android Comcast
use_ip Extraia o campo IP da solicitação HTTP em vez do campo "ip". Não use isso com o parâmetro IP iOS, Android,
PC, Console
true
fcm Token de dispositivo do Firebase Cloud Messaging. Necessário para o rastreamento de desinstalação do Android Android bk3RNwTe3H0CI2k_ HHwgIpoDKCIZvvD MExUdFQ3P1
gcm Token de dispositivo de mensagens na nuvem do Google. Necessário para o rastreamento de desinstalação do Android (legado) Android bk3RNwTe3H0CI2k_ HHwgIpoDKCIZvvDM ExUdFQ3P1
apns_token Token de dispositivo do serviço de notificação por push da Apple. Necessário para o rastreamento de desinstalação do iOS iOS b0adf7c9730763f88e1a048e28c68a9f806ed032fb522deb...ff5bfba010a9b052
ua Agente do usuário do dispositivo iOS, Android,
PC, Console
Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148
attribution_token Usado para atribuir o Apple Search Ads para iOS 14.3 e superior. Esse valor está disponível por meio da estrutura do AdServices. Saiba como recuperá-lo em Implementação do Apple Search Ads via AdServices iOS G9i5hC8lQJeGOfmS+MFycll/02...AAABBEQQBQA=
skan_conversion_value O valor de conversão mais recente da SKAdNetwork no momento dessa notificação de sessão(saiba mais sobre a implementação da SKAdNetwork). iOS 0 - 63
skan_first_call_timestamp Registro de data e hora Unix da primeira chamada à API SkAdNetwork subjacente (para saber mais sobre a implementação da SKAdNetwork, leia aqui) iOS 1483228800
skan_last_call_timestamp Registro de data e hora Unix da última chamada à API SkAdNetwork subjacente no momento dessa notificação de sessão (para saber mais sobre a implementação da SKAdNetwork, leia aqui) iOS 1483228800
global_properties Você pode definir até 5 propriedades globais. Cada chave e valor de propriedade pode ter até 200 caracteres. Se você passar um nome ou valor de propriedade mais longo, ele será truncado em 200 caracteres. O valor deve ser um objeto JSON codificado por URLE. iOS, Android,
PC, Console
%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D
data_sharing_options

Indicar o consentimento do usuário final para compartilhar informações. Se definido, esse valor deverá ser mantido e transmitido em todas as solicitações /launch e /evt subsequentes para o usuário.

Passe "limit_data_sharing":false para indicar que o usuário consentiu (optou por participar) em compartilhar suas informações.

Passe "limit_data_sharing":true se o usuário recusou.

Opcional

%7B%22limit_data_sharing%22%3Atrue%7D

Exemplo de chamada de API

Python HTTP cURL Java
import requests
import json
  
   SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
   LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
   params = {
       'a': SDK_KEY,
       'p': 'Android',
       'i': 'com.singular.app',
       'ip': '10.1.2.3',
       've': '9.2',
       'ma': 'samsung',
       'mo': 'SM-G935F',
       'lc': 'en_US',
       'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
       'andi': 'fc8d449516de0dfb',
       'utime': 1483228800,
       'dnt': 0,
       'install':'true',
       'n': 'MyCoolApp',
       'c': 'wifi',
       'cn': 'Comcast',
       'bd': 'Build/13D15',
       'fcm':'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1',
       'app_v':'1.2.3',
       'openuri':'myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1',
       'ddl_enabled':'false',
       'install_source': 'com.android.vending',
       'install_time': 1510040127,
       'update_time': 1510090877,
'custom_user_id': '123456789abcd',
'global_properties': json.dumps({"key1":"value1","key2":"value2"}) } result = requests.get(LAUNCH_URL, params=params) print result.json()

Ponto de extremidade de notificação de evento

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

Use esse endpoint para relatar qualquer evento que ocorra em seu aplicativo que não seja a sessão.

Parâmetros obrigatórios do evento

Parâmetro Descrição Plataformas suportadas Exemplo
n

Nome do evento.

Recomenda-se usar a convenção de nomenclatura de eventos padrão da Singular.

iOS, Android, Web,
PC, Console
sng_add_to_cart
a Chave do Singular SDK. iOS, Android, Web,
PC, Console
a42be1d8119389dd36c7_acbeaf6abcd8
p Uma das seguintes plataformas:
Android, iOS, Web, PC, Xbox, Playstation, Nintendo, MetaQuest or CTV
iOS, Android, Web,
PC, Console
Android
i Nome do pacote (Android) ou ID do pacote (iOS) do seu aplicativo móvel ou ProductID do WebSDK. iOS, Android, Web,
PC, Console
com.yourcompany.app
ip O IP do evento. iOS, Android, Web,
PC, Console
172.58.29.235
idfa Somente para aplicativos iOS. ID de publicidade bruta em letras maiúsculas com traços. iOS DFC5A647-9043-4699-B2A5-76F03A97064B
idfv Somente para aplicativos iOS. IdentifierForVendor bruto em maiúsculas com traços. iOS 21DB6612-09B3-4ECC-84AC-B353B0AF1334
aifa ID de publicidade bruta do Google em letras minúsculas com traços. Android (Google Play) 8ecd7512-2864-440c-93f3-a3cabe62525b
asid A ID do conjunto de aplicativos (para dispositivos Android 12+). Isso deve ser enviado se a ID de publicidade do Google (aifa) não estiver disponível. Saiba mais sobre o assunto Android (Google Play) edee92a2-7b2f-45f4-a509-840f170fc6d9
amid O ID de publicidade da Amazon com traços. Disponível em dispositivos da Amazon. Android (Amazon) df07c7dc-cea7-4a89-b328-810ff5acb15d
oaid O Open Advertising ID com traços, geralmente usado em dispositivos domésticos da China. Disponível com o SDK MSA integrado ou com o SDK OAID da Huawei Android 01234567-89abc-defe-dcba-987654321012
andi

Somente para aplicativos Android que não sejam do Google Play. ID android bruto em letras minúsculas.

Envie isso somente se não houver outros identificadores de dispositivo disponíveis.

Android fc8d449516de0dfb
sdid

Web: A ID do dispositivo UUIDv4 fornecida pelo Singular WebSDK Saiba mais

PC/Console: Um UUIDv4 gerado no lado do cliente que representa uma instalação de aplicativo exclusiva.

Web, PC, Console 40009df0-d618-4d81-9da1-cbb3337b8dec
ve Versão do sistema operacional do dispositivo no momento do evento. iOS, Android, Web,
PC, Console
9.2
att_authorization_status * O status de autorização do App Tracking Transparency. Disponível para iOS 14+.

Valores compatíveis:

  • 0 - Undetermined O prompt ATT ainda não foi exibido. IDFA indisponível no iOS 14.5+
  • 1 - Restricted O usuário desativou a opção de mostrar o prompt ATT. IDFA indisponível.
  • 2 - Denied IDFA indisponível, o usuário viu o prompt da ATT e negou a autorização. IDFA indisponível
  • 3 - Authorized O usuário viu o prompt da ATT e concedeu a autorização. O IDFA está disponível
iOS 3

*Observação:a partir do iOS 14.5, o prompt do App Tracking Transparency (ATT) é necessário para acessar o IDFA do dispositivo. Mesmo que você não implemente o prompt ATT, exigimos que você passe o status de autorização ATT para a Singular (com o valor "0", indicando "indeterminado").

Parâmetros opcionais do evento

Parâmetro Descrição do evento Plataformas suportadas Exemplo
custom_user_id User ID  iOS, Android, Web,
PC, Console
123456789abcd
utime Hora do evento em horário UNIX. Observação: o tempo NÃO DEVE ser menor que o tempo de instalação. iOS, Android, Web,
PC, Console
1483228800
umilisec Tempo do evento em milissegundos no horário do UNIX. Observação: O tempo NÃO DEVE ser menor que o tempo de instalação. iOS, Android, Web,
PC, Console
1483228800000
use_ip Extrair o campo IP da solicitação HTTP. Se você definir isso como true, não forneça o parâmetro ip. iOS, Android, Web,
PC, Console
true
e

Atributos de eventos personalizados no formato JSON.

É altamente recomendável usar a convenção de nomenclatura de atributos de eventos padrão da Singular.

iOS, Android, Web,
PC, Console
%7B%22sng_attr_content_id%22%3A5581%2C
sng_attr_content%22%3A%22XBox%22%2C%22
sng_attr_content_type%22%3A%22electronics%22%7D
global_properties Você pode definir até 5 propriedades globais. Cada chave e valor de propriedade pode ter até 200 caracteres. Se você passar um nome ou valor de propriedade mais longo, ele será truncado para 200 caracteres. O valor deve ser um objeto JSON codificado por URLE. iOS, Android, Web,
PC, Console
%7B%22key1%22%3A%22value1%22
%2C%22key2%22%3A%22value2%22%7D
data_sharing_options

Indicar o consentimento do usuário final para compartilhar informações. Se definido, esse valor deverá ser mantido e transmitido em todas as solicitações /launch e /evt subsequentes para o usuário.

Passe "limit_data_sharing":false para indicar que o usuário consentiu (optou por participar) em compartilhar suas informações.

Passe "limit_data_sharing":true se o usuário recusou.

Opcional

%7B%22limit_data_sharing%22%3Atrue%7D

skan_conversion_value O valor de conversão mais recente da SKAdNetwork no momento da notificação desse evento (para saber mais sobre a implementação da SKAdNetwork, leia aqui) iOS 0 - 63
skan_first_call_timestamp Registro de data e hora Unix da primeira chamada à API SkAdNetwork subjacente (para saber mais sobre a implementação de SKAdNetwork, leia aqui) iOS 1483228800
skan_last_call_timestamp Registro de data e hora Unix da última chamada à API SkAdNetwork subjacente no momento dessa notificação de evento (para saber mais sobre a implementação da SKAdNetwork, leia aqui) iOS 1483228800

 

Parâmetros para eventos de receita

Parâmetro Descrição Plataformas suportadas Exemplo
is_revenue_event Se é um evento de receita. Você pode omitir isso se o nome do evento for __iap__ ou se for fornecido um valor diferente de zero. iOS, Android, Web, PC, Console True
amt O valor da moeda. Deve ser usado em conjunto com o parâmetro cur. iOS, Android, Web, PC, Console 2.51
cur O código de moeda de três letras ISO 4217. Deve ser usado em conjunto com o parâmetro amt. iOS, Android, Web, PC, Console EUR
purchase_receipt O recibo recebido de uma compra. Consulte as instruções abaixo sobre como recuperá-lo no Android, iOS iOS, Android

iOS:
MIISqwYJKoZI...cNqts0jvcNvPcK7y
uj0KhJ9nTTQ54kDKfReihzc6aw==

Android:
{"orderId":"GPA.1234",
"packageName":"com.example",
"productId":"com.example.product",
"purchaseTime":1417113074914,
"purchaseState":0,
"purchaseToken":"hakfcimbk... pM"} 

receipt_signature A assinatura usada para assinar o recibo de compra Android TyVJfHg8OAoW7W4wuJt... 5agEDMnNXvhfrw==
purchase_product_id O identificador de SKU do produto iOS, Android, Web, PC, Console

com.example.product

purchase_transaction_id O identificador da transação iOS, Android, Web, PC, Console

iOS: 380000123004321

Android: GPA.1234-1234- 1234-12345 

Exemplo de chamada de API

Python HTTP cURL Java
import requests
import json
  
  SDK_KEY = '[sdk_key de Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK].'
  EVENT_URL = 'https://s2s.singular.net/api/v1/evt'
  
  params = {
   'n': 'levelup',
   'e': json.dumps({"level": "10"}),
   'a': SDK_KEY,
   'p': 'Android',
   'i': 'com.yourcompany.app',
   'ip': '10.1.2.3',
   'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
   'andi': 'fc8d449516de0dfb',
   'utime': 1483228800,
   'custom_user_id': '123456789abcd',
'global_properties': json.dumps({"key1":"value1","key2":"value2"}) } result = requests.get(EVENT_URL, params=params) print result.json()