Endpoint de referencia de API de servidor a servidor (S2S)

Este artículo de referencia enumera los puntos finales de API que ofrece Singular para las integraciones S2S.

Nota: Las integraciones de servidor a servidor sólo están disponibles para clientes Enterprise.

Actualización [Noviembre 2021]: Ahora debe reportar el Referrer de Instalación de Android a través del Endpoint de Notificación de Sesión (no Notificación de Evento). Esto hace que el referrer de instalación esté disponible para Singular inmediatamente cuando el usuario abre la app, y sigue las mejores prácticas de Google. Para obtener más información, consulte Envío de la referencia de instalación de Google Play (Android).

 

Autenticación y códigos de estado

Cualquier llamada a la API S2S tiene que incluir su SDK Key. Para recuperarla, inicie sesión en Singular y vaya a "Developer Tools > SDK Integration > SDK Keys".

El código de estado HTTP devuelto en cualquier llamada a la API S2S es 200 si la llamada se ha realizado correctamente. Cualquier otro código significa que debe reintentar la llamada.

Lista de puntos finales de la API S2S de Singular

Están disponibles los siguientes puntos finales de la API:

Notificación de sesión GET https://s2s.singular.net/api/v1/launch Notificación de una nueva sesión a Singular.
Notificación de eventos GET https://s2s.singular.net/api/v1/evt Notificar un evento de la aplicación a Singular.

Punto final de notificación de sesión

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

Utilice el punto final de notificación de sesión para informar de una sesión a Singular.

Parámetros de sesión requeridos

Parámetro Descripción Plataformas soportadas Ejemplo
a Clave SDK singular. iOS, Android,
PC, Console
your_org_name_sh868sdjv
p Una de las siguientes plataformas:
Android, iOS, PC, Xbox, Playstation, Nintendo, MetaQuest or CTV
iOS, Android,
PC, Console
Android
i Nombre del paquete (Android) o ID del paquete (iOS) de su aplicación. iOS, Android,
PC, Console
com.singular.app
ip La IP del dispositivo. iOS, Android,
PC, Console
172.58.29.235
ve Versión del sistema operativo del dispositivo en el momento de la sesión. iOS, Android,
PC, Console
9.2
install_ref Información de referencia de instalación de Google Android Más información
meta_ref Información de referencia de Meta Install Android Más información
asid ID del conjunto de aplicaciones (para dispositivos Android 12+) Android Más información
ma Marca del hardware del dispositivo, normalmente el nombre de cara al consumidor (por ejemplo, Samsung, LG, Apple). Este parámetro debe utilizarse con el parámetro de modelo. iOS, Android samsung
mo Modelo del hardware del dispositivo (por ejemplo, iPhone 4S, Galaxy SIII). Este parámetro debe utilizarse con el parámetro de marca. iOS, Android SM-G935F
lc La etiqueta local IETF para el dispositivo, utilizando un código de idioma y país de dos letras separado por un guión bajo. iOS, Android en_US
bd Build del dispositivo, URL codificada iOS, Android Build%2F13D15
openuri Si la aplicación se abrió a través de cualquier enlace profundo/enlace universal/enlace de aplicación, el valor codificado de la URL del enlace profundo. iOS, Android myapp%3A%2F%2Fhome%2Fpage%3 Fqueryparam1%3D value1%26queryparam2%3 Dvalue2
idfa Sólo para aplicaciones iOS. ID de publicidaden bruto en mayúsculas con guiones. iOS DFC5A647-9043-4699-B2A5-76F03A97064B
idfv Sólo para aplicaciones iOS. IdentifierForVendor en mayúsculas con guiones. iOS 21DB6612-09B3-4ECC-84AC-B353B0AF1334
aifa Sólo para aplicaciones Android. ID de publicidad sin procesar en minúsculas con guiones. Android 8ecd7512-2864-440c-93f3-a3cabe62525b
andi Sólo para aplicaciones Android. Identificador de Android en minúsculas. Sólo se requiere cuando el identificador de publicidad de Android no está disponible en el dispositivo. Android fc8d449516de0dfb
sdid

PC/Consola: UUID generado por el cliente que representa una instalación única del juego.

PC, Console 40009df0-d618-4d81-9da1-cbb3337b8dec
dnt Pasa 1 si do not track está activado, 0 si do not track está desactivado. iOS, Android 1
app_v Versión de la aplicación iOS, Android 1.2.3
install_source

Nombre del paquete de origen de la instalación en Android, por ejemplo: 'com.android.vending'. Para recuperar este valor utilice InstallSourceInfo.getInitiatingPackageName()

 

La tienda de instalación en PC, los valores soportados/recomendados son: steam, epic, microsoftstore, humblestore, gog, selfdistributed

Android, PC

Android:

com.vending.android (Android)

steam (PC)


install_receipt El recibo recibido de la instalación. Aprende a recuperarlo en iOS Install Receipt iOS MIISqwYJKoZI...cNqts0jvcNvPcK7 yuj0KhJ9nTTQ54kDKfReihzc6aw==
install Bandera de instalación. true' si la sesión fue la primera después de instalar la aplicación. false' en caso contrario. Necesario para las funciones de seguimiento de reinstalación. iOS, Android,
PC, Console
false
install_time La hora de la primera instalación de la aplicación en tiempo UNIX. Para recuperar este valor, utilice el enlace de la plataforma. iOS, Android 1510040127
update_time La hora de la última actualización de la aplicación como hora UNIX. Para recuperar este valor, utilice el enlace de la plataforma. iOS, Android 1510040127
ddl_enabled Bandera de enlace profundo diferido. True" si el servidor espera que se devuelva una URL de enlace profundo diferido. false' en caso contrario. Consulte nuestra sección sobre enlace profundo diferido para más detalles iOS, Android true
singular_link_resolve_required Se utiliza para resolver un enlace corto Singular. Debe enviarse con un valor en "openuri" que sea un enlace corto Singular. Consulte la sección sobre gestión de enlacescortos.

iOS,
Android

true
att_authorization_status *

Disponible a partir de iOS 14. El estado de autorización de App Tracking Transparency.

Los valores admitidos son:

  • 0 - Undetermined IDFA no disponible en iOS 14.5+.
  • 1 - Restricted el usuario ha desactivado la opción de mostrar el mensaje ATT. IDFA no disponible.
  • 2 - Denied el usuario ha visto el aviso ATT y ha denegado la autorización. IDFA no disponible
  • 3 - Authorized el usuario ha visto el aviso de ATT y ha concedido la autorización. IDFA está disponible
iOS 3

*Nota: A partir de iOS 14.5, el prompt App Tracking Transparency (ATT) es necesario para acceder al IDFA. Incluso si no implementa el prompt ATT, requerimos que pase el estado de autorización ATT a Singular (con el valor "0", indicando "indeterminado").

Parámetros de Sesión Opcionales

Parámetro Descripción Plataformas soportadas Ejemplo
custom_user_id User ID iOS, Android,
PC, Console
 123456789abcd
n Nombre legible de la aplicación tal y como se muestra en la interfaz de usuario. iOS, Android,
PC, Console
MyCoolApp
utime Hora de la sesión en tiempo UNIX. iOS, Android,
PC, Console
1483228800
umilisec Tiempo de la sesión en milisegundos tiempo UNIX. iOS, Android,
PC, Console
1483228800000
dntoff Pase 0 si "do not track" está activado o 1 si "do not track" está desactivado. iOS, Android 0
c Tipo de conexión 'wifi' o 'carrier'. iOS, Android wifi
cn Nombre del proveedor de Internet. iOS, Android Comcast
use_ip Extraer el campo IP de la petición HTTP en lugar del campo 'ip'. No utilizar esto con el parámetro IP. iOS, Android,
PC, Console
true
fcm Token de dispositivo de Firebase Cloud Messaging. Necesario para el seguimiento de desinstalación de Android Android bk3RNwTe3H0CI2k_ HHwgIpoDKCIZvvD MExUdFQ3P1
gcm Google Cloud Messaging Device Token. Necesario para el seguimiento de desinstalaciones de Android (heredado) Android bk3RNwTe3H0CI2k_ HHwgIpoDKCIZvvDM ExUdFQ3P1
apns_token Apple Push Notification Service Device Token. Necesario para el seguimiento de desinstalaciones de iOS iOS b0adf7c9730763f88e1a048e28c68a9f806ed032fb522deb...ff5bfba010a9b052
ua Agente de usuario del 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 Se utiliza para atribuir anuncios de búsqueda de Apple para iOS 14.3 y versiones posteriores. Este valor está disponible a través del marco de AdServices. Aprenda a recuperarlo en Implementación de anuncios de búsqueda de Apple a través de AdServices. iOS G9i5hC8lQJeGOfmS+MFycll/02...AAABBEQQBQA=
skan_conversion_value El último valor de conversión de SKAdNetwork en el momento de esta notificación de sesión(más información sobre la implementación de SKAdNetwork). iOS 0 - 63
skan_first_call_timestamp Marca de tiempo Unix de la primera llamada a la API SkAdNetwork subyacente (para obtener más información sobre la implementación de SKAdNetwork, lea aquí). iOS 1483228800
skan_last_call_timestamp Unix timestamp de la última llamada a la API SkAdNetwork subyacente en el momento de esta notificación de sesión (para más información sobre la implementación de SKAdNetwork, lea aquí). iOS 1483228800
global_properties Puede definir hasta 5 propiedades globales. La clave y el valor de cada propiedad pueden tener un máximo de 200 caracteres. Si pasa un nombre o valor de propiedad más largo, se truncará a 200 caracteres. El valor debe ser un objeto URLEncoded JSON. iOS, Android,
PC, Console
%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D
data_sharing_options

Indica el consentimiento del usuario final para compartir información. Si se establece, este valor debe persistir y pasarse en cada solicitud /launch y /evt posterior del usuario.

Pasa "limit_data_sharing":false para indicar que el usuario consintió (optó por) compartir su información.

Pase "limit_data_sharing":true si el usuario se negó.

Opcional

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

Ejemplo de llamada a la API

Python HTTP cURL Java
import requests
import json
  
   SDK_KEY = '[sdk_key desde Herramientas de desarrollo > Integración SDK > Llaves 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()

Punto final de notificación de eventos

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

Utilice este endpoint para notificar cualquier evento que ocurra en su aplicación que no sea la sesión.

Parámetros de evento requeridos

Parámetro Descripción Plataformas soportadas Ejemplo
n

Nombre del evento.

Se recomienda utilizar la convención de nomenclatura de eventos estándar de Singular.

iOS, Android, Web,
PC, Console
sng_add_to_cart
a Clave de Singular SDK. iOS, Android, Web,
PC, Console
a42be1d8119389dd36c7_acbeaf6abcd8
p Una de las siguientes plataformas:
Android, iOS, Web, PC, Xbox, Playstation, Nintendo, MetaQuest or CTV
iOS, Android, Web,
PC, Console
Android
i Package Name (Android) o Bundle ID (iOS) de su aplicación móvil o ProductID de WebSDK. iOS, Android, Web,
PC, Console
com.yourcompany.app
ip La IP del evento. iOS, Android, Web,
PC, Console
172.58.29.235
idfa Sólo para aplicaciones iOS. ID de publicidad sin procesar en mayúsculas con guiones. iOS DFC5A647-9043-4699-B2A5-76F03A97064B
idfv Sólo para aplicaciones iOS. IdentifierForVendor en mayúsculas con guiones. iOS 21DB6612-09B3-4ECC-84AC-B353B0AF1334
aifa Sólo para aplicaciones Android. ID de publicidad sin procesar en minúsculas con guiones. Android 8ecd7512-2864-440c-93f3-a3cabe62525b
asid App Set ID (para dispositivos Android 12+) Más información Android edee92a2-7b2f-45f4-a509-840f170fc6d9
andi Sólo para aplicaciones Android. Identificador de Android en bruto con minúsculas. Sólo se requiere cuando el identificador de publicidad de Android no está disponible en el dispositivo. Android fc8d449516de0dfb
sdid

Web: El ID de dispositivo UUIDv4 proporcionado por Singular WebSDK Más información

PC/Consola: UUID generado por el cliente que representa una instalación única del juego.

Web, PC, Console 40009df0-d618-4d81-9da1-cbb3337b8dec
ve Versión del sistema operativo del dispositivo en el momento del evento. iOS, Android, Web,
PC, Console
9.2
att_authorization_status * El estado de autorización de App Tracking Transparency. Disponible para iOS 14+.

Valores admitidos:

  • 0 - Undetermined IDFA no disponible en iOS 14.5+, el usuario ha desactivado la opción de mostrar el mensaje ATT.
  • 1 - Restricted el usuario ha desactivado la opción de mostrar el mensaje ATT. IDFA no disponible.
  • 2 - Denied el usuario ha visto el aviso ATT y ha denegado la autorización. IDFA no disponible
  • 3 - Authorized el usuario ha visto el aviso de ATT y ha concedido la autorización. IDFA está disponible
iOS 3

*Nota:A partir de iOS 14.5, se requiere el indicador App Tracking Transparency (ATT) para acceder al IDFA del dispositivo. Incluso si no implementa el aviso ATT, necesitamos que pase el estado de autorización ATT a Singular (con el valor "0", que indica "indeterminado").

Parámetros de Evento Opcionales

Parámetro Descripción Plataformas soportadas Ejemplo
custom_user_id User ID  iOS, Android, Web,
PC, Console
123456789abcd
utime Hora del evento en tiempo UNIX. Nota: La hora NO DEBE ser menor que la Hora de Instalación. iOS, Android, Web,
PC, Console
1483228800
umilisec Hora del evento en milisegundos en tiempo UNIX. Nota: La hora NO DEBE ser inferior a la hora de instalación. iOS, Android, Web,
PC, Console
1483228800000
use_ip Extraer el campo IP de la petición HTTP. Si establece esto a true, no proporcione el parámetro ip. iOS, Android, Web,
PC, Console
true
e

Atributos de evento personalizados en formato JSON.

Se recomienda encarecidamente utilizar la convención de nomenclatura de atributos de eventos estándar de 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 Puede definir hasta 5 propiedades globales. La clave y el valor de cada propiedad pueden tener un máximo de 200 caracteres. Si pasa un nombre o valor de propiedad más largo, se truncará a 200 caracteres. El valor debe ser un objeto URLEncoded JSON. iOS, Android, Web,
PC, Console
%7B%22key1%22%3A%22value1%22
%2C%22key2%22%3A%22value2%22%7D
data_sharing_options

Indica el consentimiento del usuario final para compartir información. Si se establece, este valor debe persistir y pasarse en cada solicitud /launch y /evt posterior del usuario.

Pasa "limit_data_sharing":false para indicar que el usuario consintió (optó por) compartir su información.

Pase "limit_data_sharing":true si el usuario se negó.

Opcional

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

skan_conversion_value El último valor de conversión de SKAdNetwork en el momento de esta notificación de evento (Para saber más sobre la implementación de SKAdNetwork, lea aquí) iOS 0 - 63
skan_first_call_timestamp Unix timestamp de la primera llamada a la API SkAdNetwork subyacente (para más información sobre la implementación de SKAdNetwork, lea aquí) iOS 1483228800
skan_last_call_timestamp Unix timestamp de la última llamada a la API SkAdNetwork subyacente en el momento de esta notificación de evento (para más información sobre la implementación de SKAdNetwork, lea aquí) iOS 1483228800

 

Parámetros para eventos de ingresos

Parámetro Descripción Plataformas soportadas Ejemplo
is_revenue_event Si es un evento de ingresos. Puede omitirlo si el nombre del evento es __iap__ o si se proporciona un importe distinto de cero. iOS, Android, Web, PC, Console True
amt El importe en moneda. Debe utilizarse junto con el parámetro cur. iOS, Android, Web, PC, Console 2.51
cur El código de moneda ISO 4217 de tres letras. Debe utilizarse junto con el parámetro amt. iOS, Android, Web, PC, Console EUR
purchase_receipt El recibo recibido de una compra. Consulte las instrucciones a continuación sobre cómo recuperarlo desde 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 La firma utilizada para firmar el recibo de compra Android TyVJfHg8OAoW7W4wuJt... 5agEDMnNXvhfrw==
purchase_product_id El identificador SKU del producto iOS, Android, Web, PC, Console

com.example.product

purchase_transaction_id El identificador de la transacción iOS, Android, Web, PC, Console

iOS: 380000123004321

Android: GPA.1234-1234- 1234-12345 

Ejemplo de llamada a la API

Python HTTP cURL Java
import requests
import json
  
  SDK_KEY = '[sdk_key desde Herramientas de desarrollo > Integración SDK > Llaves 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()