Guía de integración de servidor a servidor (S2S)

Seguir
Avatar
Jonathan Chen
Updated

Nota: Las integraciones de servidor a servidor sólo están disponibles previa solicitud. Hable con su gestor de atención al cliente de Singular o con el servicio de asistencia de Singular.

 

Como alternativa al SDK de Singular, que debe integrarse en sus aplicaciones, Singular también proporciona una API REST que puede utilizarse para crear una integración completa que se ejecute desde su propio servidor.

Esta guía explica cómo crear una integración S2S básica con Singular e implementar varias funciones opcionales.

Para obtener una lista completa de los puntos finales de la API S2S, sus parámetros y ejemplos de llamadas, consulte la Referencia de puntos finales S2S.

Integración básica

La integración más básica con Singular consiste en avisar a Singular cuando hay una nueva sesión, es decir, cuando se abre la aplicación.

Para notificar a Singular sobre una sesión de usuario, llame al punto final de notificación de sesión.

Las notificaciones de sesión permiten a Singular hacer varias cosas:

  • Si es la primera sesión para la aplicación en el dispositivo específico, Singular reconoce una nueva instalación y activa el proceso de atribución de instalación.
  • Si la sesión se califica como una sesión de reenganche, Singular activa el proceso de atribución de reenganche (más información en las preguntas frecuentes sobre reenganche).
  • De lo contrario, Singular la marca como una sesión, que se utiliza para realizar un seguimiento de la actividad del usuario y la retención.

El endpoint de Notificación de Sesión tiene algunos parámetros requeridos. Para obtener ayuda sobre cómo obtener todos los datos necesarios para notificar una sesión, consulte Referencia:Recuperación del recibo de instalación de iOS y Referencia : Recuperación de identificadores de dispositivo y datos de sesión.

Sugerencia: Cuando recopile los datos para informar de una sesión, asegúrese de esperar a que las funciones asíncronas devuelvan y gestionen varios casos límite. Se trata de un problema habitual que puede provocar la falta de datos y la atribución parcial.

Recopilación y envío del App Set ID (necesario para Android 12+)

El App Set ID o ASID es un nuevo identificador de privacidad que se utiliza en los dispositivos Android 12+. El App Set ID es compartido por todas las aplicaciones de un dispositivo que hayan sido publicadas en la tienda Google Play por el mismo desarrollador.

Añada el App Set ID como parámetro a la llamada de sesión y a cada llamada de evento, de forma similar a como enviaría el GAID.

Para recopilar el App Set ID, utilice el siguiente código en su aplicación:

Context context = getApplicationContext();
  AppSetIdClient client = AppSet.getClient(context);
  Task<AppSetIdInfo> task = client.getAppSetIdInfo();
  
  task.addOnSuccessListener(new OnSuccessListener<AppSetIdInfo>() {
      @Override
      public void onSuccess(AppSetIdInfo info) {
          // Determine el alcance actual del ID de Appset de Android.
          int scope = info.getScope();
  
          // Lea el valor de ID del Appset de Android, que utiliza el formato UUID versión 4.
          String id = info.getId();
      }
  });

Importante: Envío de la referencia de instalación de Google Play (Android)

El referente de instalación contiene información sobre quién envió a un usuario a Google Play Store. Cuando el referente de instalación está disponible para Singular, proporciona la forma más precisa de atribuir instalaciones. Recupere este valor y páselo a Singular en la primera llamada de notificación de sesión. Es necesario para algunas funciones importantes de Singular, como recibir datos de Facebook en nuestras exportaciones a nivel de usuario, compartirlos con destinos de datos y enviar postbacks.

Google Play recopila información de referencia cuando un usuario llega a la tienda. Si el usuario instala más tarde la aplicación a la que fue dirigido, Google Play pone la información a disposición de la aplicación. Para obtener más información, consulte la documentación para desarrolladores de Google.

Para compartir la referencia de instalación con Singular:

  1. Cuando la aplicación se abre por primera vez, recupere la referencia de instalación utilizando la API de referencia de instalación de Play.

  2. Informe de una sesión a Singular utilizando el punto final de Notificación de Sesión incluyendo el parámetro install_ref. Este parámetro está codificado en JSON y tiene los siguientes atributos:

    Atributo Descripción
    referrer El valor de referencia recuperado de la API de referencia de instalación de Play. Este es un objeto JSON, así que asegúrese de codificarlo como una cadena.
    referrer_source Especificar "service".
    clickTimestampSeconds La marca de tiempo del clic recibida de la API de referencia de instalación de Play (por ejemplo, "1550420123").
    installBeginTimestampSeconds
    		 La hora a la que comenzó la instalación, tal como se recibió de la API Play Install Referrer.
    current_device_time El tiempo en el dispositivo actual, en milisegundos (por ejemplo, "1550420454906").

A continuación se muestra un ejemplo de código para notificar el evento de referencia de instalación:

Python HTTP
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'
  
  referrer_values = {
        "referrer": "tracking_id%3D123456789&utm_source%3Dmdotm%26utm_medium%3Dbanner%26utm_campaign%3Dcampaign",
        "referrer_source" : "service",
        "clickTimestampSeconds" : 1550420123,
        "installBeginTimestampSeconds" : 1550420123,
        "current_device_time" : 1550420454906
      }

referrer_values = json.dumps(referrer_values, separators=(',',':'))
  
   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',
      'install_ref' : referrer_values
   }
  
   result = requests.get(LAUNCH_URL, params=params)
   print result.json()

Opcional: Envío del ID de usuario

Cuando notifica a Singular una nueva sesión, puede añadir el ID de usuario. Puede ser un nombre de usuario, una dirección de correo electrónico, una cadena generada aleatoriamente o cualquier identificador que su aplicación utilice como ID de usuario. Singular utilizará el ID de usuario en las exportaciones de datos a nivel de usuario, así como en las devoluciones internas de BI (si configura alguna).

Para enviar el ID de usuario, añada el parámetro "custom_user_id" cuando llame al punto final de notificación de sesión.

Por ejemplo

Python HTTP cURL
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': 'player_id_1234'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

Gestión adicional de la atribución

Atribución para campañas de anuncios de búsqueda de Apple (iOS)

Apple Search Ads se considera una red de autoatribución (SAN). A partir de iOS 14.3, la integración de Apple Search Ads se admite a través de dos frameworks de iOS:

  • Para iOS 14.2 e inferiores, Apple Search Ads es compatible a través del framework iAd.
  • Para iOS 14.3 y posteriores, Apple Search Ads es compatible a través del framework AdServices.

Como AdServices es todavía un nuevo servicio de Apple, Singular utilizará ambos servicios, pero dará prioridad a AdServices sobre las señales de iAd para la atribución y la generación de informes.

Para más información, consulte nuestra documentación sobre la integración de Apple Search Ads.

Implementación de los anuncios de búsqueda de Apple a través de iAd (iOS 14.2 y versiones inferiores)

1. Recuperación de los datos de atribución:

Para recuperar los datos de atribución, utilice la API de iAd de Apple Search Ads. Al llamar a requestAttributionDetails(_:):se devuelve un objeto JSON que contiene los datos de atribución.

Por ejemplo

Objective-C
#import <iAd/iAd.h>
  
    Class ADClientClass = NSClassFromString(@"ADClient");
  
    if (ADClientClass) {
        id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];
        
        if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
            [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
                if (attributionDetails && attributionDetails.count > 0) {
                    // Envíe los detalles de atribución de iAd desde su aplicación a su servidor.
                }
            }];
        }
    }
Advertencia: A menudo, los usuarios que hacen clic en un anuncio de Search Ads descargan y abren la aplicación inmediatamente. Si hay alguna latencia en las comunicaciones, es posible que un MMP como Singular no pueda recibir y procesar el clic en el anuncio a tiempo antes de que se abra la aplicación y llame a la Search Ads Attribution API. Para evitarlo, Apple recomienda
  1. Establecer un retraso de unos segundos antes de recuperar los datos de atribución.
  2. Implementar una lógica de reintento si la respuesta es False o un código de error (0, 2, 3). Volver a llamar a la API de atribución de Apple 2 segundos después.

2. Envío de los datos de atribución a Singular:

Para compartir los datos de atribución con Singular, utilice el punto final de notificación de eventos para informar de un evento con el nombre de evento reservado __iAd_Attribution__. Pase el objeto JSON que recuperó en el paso anterior como valor del parámetro e , como en el ejemplo siguiente.

Python HTTP
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'
  
  # !!! REPLACE WITH COLLECTED VALUE FROM APP !!!
  apple_attribution_data = {
    u'Version3.1': {
        u'iad-adgroup-id': u'1234567',
        u'iad-adgroup-name': u'Ad Group Name',
        u'iad-attribution': u'true',
        u'iad-campaign-id': u'1234567',
        u'iad-campaign-name': u'Search Campaign',
        u'iad-click-date': u'2016-05-21T12:19:31Z',
        u'iad-conversion-date': u'2016-05-21T12:19:41Z',
        u'iad-keyword': u'ballon',
        u'iad-lineitem-id': u'1234567',
        u'iad-lineitem-name': u'Line Item Name',
        u'iad-org-name': u'Cool Company',
        u'iad-purchase-date': u'2016-05-21T12:19:41Z'
    }
  }
  
  params = {
    'n': '__iAd_Attribution__',
    'e': json.dumps(apple_attribution_data),
    'a': SDK_KEY,
    'p': 'iOS',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'mo': 'iPhone9%2C4',
    'lc': 'en_US',
    'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
    'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
    'utime': 1483228800
  }
  
  result = requests.get(EVENT_URL, params=params)
  print result.json()

Notas:

  • En iOS 13+, debe enviar el evento __iAd_Attribution__ inmediatamente después de la primera sesión tras la instalación o reinstalación. De lo contrario, los datos de Apple Search Ads no se tendrán en cuenta para la atribución.
  • En iOS 14+, las respuestas de atribución de Apple Search Ads solo están disponibles en determinadas condiciones y no están disponibles si el estado de AppTrackingTransparency es ATTrackingManager.AuthorizationStatus.denied.

Implementación de los anuncios de búsqueda de Apple a través de AdServices (iOS 14.3 y versiones posteriores)

1. Recuperación del token de atribución:

Recupere el token de atribución mediante attributionToken() en cuanto la aplicación se inicialice por primera vez tras una instalación o reinstalación.

Por ejemplo

Objective-C
#import <AdServices/AdServices.h> 

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
    NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
    if (!error && attributionToken) {
        // Envía el AdServices AttributionToken desde tu aplicación a tu servidor.
    }
}

Notas:

  • El código de atribución se genera en el dispositivo.
  • Una vez generado, el token se almacena en caché durante 5 minutos en el dispositivo. Transcurridos 5 minutos, se genera un nuevo token si se llama a attributionToken().
  • El token generado es válido durante 24 horas.

2. Envíe el código de atribución a Singular:

Codifique la URL del token y envíelo a Singular a través del endpoint de notificación de sesión, adjuntando el parámetro &attribution_token=. Este token debe enviarse en la primera sesión después de cada instalación y reinstalación para que Singular pueda realizar un seguimiento de las descargas y redescargas de Apple Search Ads.

Meta Install Referrer Attribution (Android)

" Meta Referrer" es una solución de medición específica de Android introducida por Facebook para permitir a los anunciantes acceder a datos de atribución granulares a nivel de usuario para las instalaciones de aplicaciones de Android (consulta las políticas de datos de Facebook). Consiste en implementar las tecnologías "Google Play Install Referrer" (ver "Pasar Google Install Referrer") y "Meta Install Referrer" para la medición de instalaciones de aplicaciones. Más información sobre Meta Referrer en las preguntas frecuentes sobre el tema.

Para compartir la información de Meta Install Referrer con Singnular:

  1. Cuando la aplicación se abre por primera vez, recupere el Meta Install Referrer de acuerdo con la documentación de Meta.

  2. Reporta una sesión a Singular usando el endpoint Session Notification incluyendo el parámetro meta_ref. Este parámetro está codificado en JSON y tiene los siguientes atributos:

    Atributo Descripción
    is_ct El "is_ct" recibido del Meta Install Referrer. (por ejemplo, 0 o 1)
    install_referrer El "install_referrer" recibido del Meta Install Referrer
    actual_timestamp El "actual_timestamp" recibido del Meta Install Referrer (por ejemplo, 1693978124).

Seguimiento de eventos

Singular puede recopilar datos sobre eventos dentro de la aplicación para ayudar a analizar el rendimiento de sus campañas de marketing. Los eventos pueden incluir cualquier interacción del usuario, desde inicios de sesión y registros hasta subidas de nivel en una aplicación de juegos.

Antes de implementar una integración SDK/S2S con Singular, debe tener una lista de los eventos que su organización desea seguir (consulte Definición de eventos dentro de la aplicación).

Para notificar a Singular cuando se produce un evento en su aplicación, llame al punto final de notificación de eventos. El nombre del evento que incluya en la llamada es la forma en que se identificará el evento en los informes, exportaciones y devoluciones de Singular.

Notas:

  • Singular recomienda pasar el evento utilizando la convención de nomenclatura de eventos y atributos estándar de Singular. El uso de eventos estándar agiliza la asignación y la compatibilidad con los eventos estándar de sus socios en las integraciones.
  • Recomendamos encarecidamente pasar los nombres de eventos y otros atributos en inglés para que sean compatibles con cualquier socio de terceros y soluciones de análisis que desee utilizar.
  • Los nombres de eventos están limitados a 32 caracteres ASCII. Para caracteres no ASCII, el límite es de 32 bytes una vez convertidos a UTF-8.
  • Los atributos y valores de los eventos están limitados a 500 caracteres ASCII.

Seguimiento de ingresos

Singular puede recopilar datos sobre los ingresos obtenidos a través de la aplicación para ayudar a analizar el rendimiento y el ROI de sus campañas.Singular pondrá los datos a su disposición en informes, exportación de registros y postbacks.

Para realizar un seguimiento de los eventos de ingresos, utilice el mismo punto final de notificación de eventos que utiliza para todos los eventos, pero añada la siguiente información:

  • is_revenue_event=true: Esto marca el evento como un evento de ingresos. Puede omitir este parámetro si el nombre del evento es __iap__ o el importe es mayor que cero.
  • Recibo de compra: se trata de un objeto devuelto por el proceso In-App Purchase (IAP) de Android o iOS. Recomendamos encarecidamente pasarlo a Singular para dar a Singular todos los detalles sobre la transacción y enriquecer sus informes de Singular con datos.
  • Firma de la compra (sólo Android): Recomendamos encarecidamente pasar este dato a Singular para validar la transacción y luchar contra el fraude dentro de la aplicación.
  • Importe del ingreso (por ejemplo, "amt=1,99").
  • Divisa (utilice el código de divisa ISO 4217, por ejemplo, "cur=USD").

Recuperación del recibo de compra

Después de que se produzca un evento de ingresos, he aquí cómo obtener el recibo de compra para poder enviarlo a Singular:

  • En Android: Google Play proporciona una API para recuperar el recibo de compra ("In-App Purchase Data") y la firma de compra ("In-App Data Signature"). Utiliza el método getBuyIntent().
  • En iOS: Utiliza la API In-App Purchases de Apple como se muestra en el siguiente ejemplo (para obtener más información, consulta API In-App Purchases de Apple).
Objective-C
// SKPaymentTransactionObserver
    + (void)paymentQueue:(id)queue updatedTransactions:(NSArray *)skTransactions {
       NSString *transactionReceipt = nil;
  
       if ([skTransaction respondsToSelector:@selector(transactionReceipt)]) {
          NSData *transactionReceiptRaw = [skTransaction performSelector:@selector(transactionReceipt)];
          if (transactionReceiptRaw) {
             transactionReceipt = [ApUtils base64Encode:transactionReceiptRaw];
          }
       }
    }

Ejemplo de evento de ingresos personalizado

Python HTTP cURL
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 = {
  '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',
'bd': 'Build/13D15',
  'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
  'utime': 1483228800,
  'n': 'RevenueEventName',
'amt': '2.50',
  'cur': 'USD',
'is_revenue_event': 'true',
'purchase_receipt': {'orderId"':'GPA.1234',
                     'packageName':'com.example',
                     'productId':'com.example.product',
                     'purchaseTime':1417113074914,
                     'purchaseState':0,
                     'purchaseToken':'hakfcimbk... pM'},
'receipt_signature': 'TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==',
'purchase_product_id': 'com.example.product',
'purchase_transaction_id': 'GPA.1234-1234-1234-12345'
  }
  
  result = requests.get(EVENT_URL, params=params)
  print result.json()

Soporte de enlaces profundos

Los enlaces profundos son enlaces que llevan a contenidos específicos dentro de una aplicación. Cuando un usuario hace clic en un enlace profundo en un dispositivo que tiene instalada la aplicación, ésta se abre y muestra un producto o experiencia específicos.

Los enlaces de seguimiento singulares pueden incluir enlaces profundos, así como enlaces profundos diferidos (consulte nuestras Preguntas frecuentes sobre enlaces profundos y las Preguntas frecuentes sobre enlaces singulares para obtener más información).

Requisitos previos para la vinculación profunda

Para iOS:

Para Android:

  • Configure los enlaces profundos de Android según la documentación del SDK.
  • Implemente un gestor de enlaces en el código de la aplicación (consulteel gestor en la documentación del SDK).

Soporte de enlaces profundos

Siempre que su aplicación se abra a través de un enlace profundo, añada la URL cuando informe de la sesión a Singular utilizando el parámetro openuri. Esto es necesario al utilizar Singular Links.

Activación de enlaces profundos diferidos

Cuando la aplicación se abre por primera vez desde la instalación, active el flujo de enlaces profundos diferidos añadiendo los siguientes parámetros cuando informe de la sesión a Singular:

  • install=true
  • ddl_enabled=true

Singular comprueba si la aplicación se instaló a través de un enlace de seguimiento que incluía un enlace profundo diferido. En caso afirmativo, la llamada devuelve los siguientes valores:

  • deferred_deeplink - la dirección del enlace profundo. Esto es lo que debe analizar para mostrar a los usuarios el producto o la experiencia correctos.
  • deferred_passthrough - cualquier parámetro passthrough añadido al enlace profundo.

Ejemplo de llamada de notificación de sesión con soporte de enlace profundo diferido

Python
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': 'iOS',
          'i': '162738612',
          'ip': '10.1.2.3',
          've': '9.2',
          'mo': 'iPhone9%2C4',
          'lc': 'en_US',
          'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
          'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
          'utime': 1483228800,
          'dnt': 0,
          'n': 'MyCoolApp',
          'c': 'wifi',
          'cn': 'Comcast',
          'bd': 'Build/13D15',
          'openuri':'https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue',
          'install':'true',
          'ddl_enabled':'true'
      }
  
      result = requests.get(LAUNCH_URL, params=params)
      print result.json()

Ejemplo de respuesta

{
    "deferred_deeplink":"myapp://deferred-deeplink",
    "status":"ok",
    "deferred_passthrough":"passthroughvalue"
  }

Gestión de enlaces cortos singulares

Cuando la aplicación se abre desde un enlace corto Singular, el siguiente parámetro debe enviarse en la solicitud de lanzamiento para notificar al punto final Singular que la url enviada en openuri debe resolverse en el enlace largo Singular.

  • singular_link_resolve_required=true

Singular devuelve el enlace largo y el desarrollador de aplicaciones puede analizar el enlace profundo y los parámetros passthrough en el gestor de enlaces.

Ejemplo de llamada de notificación de sesión con resolución de enlace corto

Python
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': 'iOS',
          'i': '162738612',
          'ip': '10.1.2.3',
          've': '9.2',
          'mo': 'iPhone9%2C4',
          'lc': 'en_US',
          'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
          'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
          'utime': 1483228800,
          'dnt': 0,
          'n': 'MyCoolApp',
          'c': 'wifi',
          'cn': 'Comcast',
          'bd': 'Build/13D15',
          'openuri':'https://myapp.sng.link/A59c0/nha7/q5a2',
          'singular_link_resolve_required':'true',
      }
  
      result = requests.get(LAUNCH_URL, params=params)
      print result.json()

Ejemplo de respuesta

{
    "status":"ok",
    "resolved_singular_link":"https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
  }

Soporte de parámetros dinámicos passthrough

Los enlaces de seguimiento de Singular pueden incluir parámetros passthrough dinámicos (más información). Si su organización ha configurado parámetros passthrough dinámicos para un enlace, la URL del enlace profundo incluye el parámetro _p seguido de un valor JSON codificado en la URL o una cadena no estructurada que puede utilizar para mostrar al usuario el contenido o la experiencia adecuados.

Opciones avanzadas

La integración Singular S2S admite las siguientes funciones avanzadas. Se implementan utilizando los mismos puntos finales de API descritos anteriormente, pero con parámetros y requisitos especiales.

Seguimiento de desinstalaciones

Singular puede rastrear las desinstalaciones utilizando las Notificaciones Push Silenciosas del dispositivo. Para activarlo, deberá enviar el token push del dispositivo al servidor de Singular junto con cada notificación de sesión.

Seguimiento de desinstalaciones en Android

Para habilitar el seguimiento de desinstalaciones en Android, primero recupere el token FCM de la aplicación llamando a FirebaseInstanceId.getInstance().getToken(). Este método devuelve null si aún no se ha generado el token. Para más información, consulte la documentación de Google Firebase.

A continuación, pase el token de dispositivo en el parámetro fcm cuando informe de la sesión a Singular, como en el siguiente ejemplo:

Python HTTP cURL
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,
    'n': 'MyCoolApp',
    'c': 'wifi',
    'cn': 'Comcast',
    'bd': 'Build/13D15',
    'fcm': 'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

Seguimiento de desinstalaciones en iOS

Singular puede realizar un seguimiento de las desinstalaciones en iOS utilizando las notificaciones push de Apple. Si su aplicación aún no es compatible con las notificaciones push, consulte la guía de Apple. Una vez que su aplicación sea compatible con las notificaciones push, pase el token de dispositivo devuelto por APNS cuando informe de la sesión a Singular.

Notas:

  • Asumimos que ya tienes una implementación de notificaciones push de la que estás recuperando un token de dispositivo.
  • El token APNS suele ser un dato binario en su forma nativa. Páselo a Singular tal y como lo recibió de APNS. Si tu aplicación está alterando el tipo de datos del token para otro propósito, asegúrate de pasarlo como una cadena codificada hexadecimal, por ejemplo: encodedb0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052
Python HTTP cURL
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': 'iOS',
    'i': '162738612',
    'ip': '10.1.2.3',
    've': '9.2',
    'mo': 'iPhone9%2C4',
    'lc': 'en_US',
    'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
    'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
    'utime': 1483228800,
    'dnt': 0,
    'n': 'MyCoolApp',
    'c': 'wifi',
    'cn': 'Comcast',
    'bd': 'Build/13D15',
    'apns_token': 'b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052'
  }
  
  result = requests.get(LAUNCH_URL, params=params)
  print result.json()

Cumplimiento de las leyes de privacidad de datos

Singular proporciona una funcionalidad de protección de la privacidad para ayudarle a cooperar con cualquier socio que pueda estar cumpliendo con las leyes de privacidad del consumidor, como GDPR y CCPA. Estos socios quieren ser notificados si el usuario final ha dado su consentimiento para compartir su información privada.

Si ha implementado una forma de solicitar a los usuarios su consentimiento para compartir su información, utilice los parámetros data_sharing_options para notificar a Singular la elección del usuario:

  • Pase "limit_data_sharing ":false para indicar que el usuario consintió (optó) en compartir su información.
  • Pase "limit_data_sharing": true si el usuario se negó.

Singular utiliza " limit_data_sharing" en "User Privacy Postbacks", así como para pasar esta información a socios que la requieren para cumplir con la normativa pertinente. Consulte "Privacidad del usuario y limitación del uso compartido de datos" para obtener más información.

Nota:

  • El uso del método es opcional, pero puede haber información de atribución que el socio compartirá con Singular solo si se notifica específicamente que el usuario ha optado por ello.
  • Recuerde codificar la URL del objeto JSON si lo pasa en una solicitud GET.
Campo Tipo Descripción Uso
limit_data_sharing boolean

Pase este valor opcional en cada solicitud de lanzamiento o evento para indicar las preferencias del usuario final.

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

Referencia: Recuperación del recibo de instalación de iOS

Como puede ver en la referencia del punto final de notificación de sesión, al notificar una sesión para una aplicación de iOS, debe pasar el recibo de instalación en el parámetro install_receipt.

Para recuperar este valor, añada el siguiente código a su aplicación:

Objective-C
+ (NSString*)installReceipt {
      // install receipts are iOS 7.0+
      if (NSFoundationVersionNumber < NSFoundationVersionNumber_iOS_7_0) {
          return nil;
      }
      
      NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
      
      if (receiptURL) {
          NSData *receipt = [NSData dataWithContentsOfURL:receiptURL];
          
          if (receipt) {
              return [receipt base64EncodedStringWithOptions:0];
          }
      }
      
      return nil;
  }

Referencia: Recuperación de identificadores de dispositivo y datos de sesión

Esta sección detalla cómo puede recuperar ciertos valores requeridos en la API REST. Estos valores son estándar en la industria, y Apple y Google también tienen documentación sobre ellos. Hemos proporcionado algunas implementaciones de referencia para su comodidad.

Recuperación del ID de publicidad de Google/Límite de seguimiento de anuncios (identificadores de Android)

Se requiere Google Play Services SDK para obtener el ID de publicidad en tu aplicación. Añade la siguiente etiqueta como elemento hijo de tu aplicación en AndroidManifest.xml:

XML
<meta-data android:name="com.google.android.gms.version"
             android:value="@integer/google_play_services_version" />

Si la compilación de tu aplicación está orientada a Android 12/API nivel 31 o superior, añade permisos para acceder al identificador de publicidad de Google:

XML
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Código de ejemplo para obtener los parámetros de ID de publicidad de Google/Limit Ad Tracking:

Java
import com.google.android.gms.ads.identifier.AdvertisingIdClient;
import com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
import com.google.android.gms.common.GooglePlayServicesAvailabilityException;
import com.google.android.gms.common.GooglePlayServicesNotAvailableException;
import java.io.IOException;
  
  // No llame a esta función desde el hilo principal. De lo contrario, se generará una excepción IllegalStateException.
  public void getIdAndLAT() {
      Info adInfo = null;
      try {
          adInfo = AdvertisingIdClient.getAdvertisingIdInfo(mContext);
      } catch (IOException e) {
          // Error irrecuperable al conectarse a los servicios de Google Play (por ejemplo, la versión anterior del servicio no admite la obtención de AdvertisingId).
      } catch (GooglePlayServicesAvailabilityException e) {
          // Encontré un error recuperable al conectarse a los servicios de Google Play. 
      } catch (GooglePlayServicesNotAvailableException e) {
          // Los servicios de Google Play no están disponibles en su totalidad.
      }
  
    final String GAID = adInfo.getId();
      final boolean limitAdTracking = adInfo.isLimitAdTrackingEnabled();
  }

Recuperación de la configuración regional, el dispositivo y la compilación para Android

Java
  // Locale - lc= query parameter
  String locale = Locale.getDefault();
  
  // Model - mo= query parameter
  String device = Build.MODEL;
  
  // Build - bd= query parameter
  String build = "Build/" + Build.ID;

Recuperación del estado de autorización de App Tracking Transparency (iOS)

A partir de iOS 14.5, se requiere App Tracking Transparency para recuperar el IDFA del dispositivo. Si muestra el aviso de App Tracking Transparency, asegúrese de implementar el aviso y el controlador antes de intentar recuperar el IDFA.

Abajo hay un ejemplo de como implementar el prompt ATT (opcional) y como recuperar la estatua de autorización ATT (requerida):

Objective-C 
#import <AppTrackingTransparency/ATTrackingManager.h>
  
// OPCIONAL si decide mostrar el mensaje ATT. Mostrar mensaje y manejar el valor. Sólo aparecerá una vez incluso si se llama varias veces.
  [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status){
      // your authorization handler here
  }];
      
// OBLIGATORIO Leer el estado actual de la autorización ATT.
  ATTrackingManagerAuthorizationStatus status = [ATTrackingManager trackingAuthorizationStatus];

Recuperación del IDFA/Límite de seguimiento de anuncios (identificadores de iOS)

A partir de iOS 14.5, se requiere App Tracking Transparency para recuperar el IDFA. Si decide mostrar el aviso de App Tracking Transparency, asegúrese de implementar el aviso y el controlador antes de intentar recuperar el IDFA.

Si usted no planea mostrar la Transparencia de Seguimiento de la Aplicación, el IDFA aún puede ser recuperado (el valor será ceros). El IDFV debe recuperarse y enviarse en cualquier caso, ya que Singular recurre a él si el IDFA no está disponible o es todo ceros.

El indicador limit-ad-track (isAdvertisingTrackingEnabled) es necesario para iOS 13 e inferiores y se utiliza para indicar si un usuario ha optado por no permitir el seguimiento de anuncios. Para iOS 14+, el indicador está obsoleto y es un valor estático si se recupera. Singular y sus socios se basarán en el nuevo valor de estado de autorización ATT para el tratamiento de los datos de los flujos de privacidad.

A continuación se muestra un ejemplo de recuperación del IDFA, IDFV y el estado de seguimiento de límite de anuncios:

Objective-C Swift
// Importe la clase AdSupport en la parte superior de su archivo
@import AdSupport;

Código de ejemplo para obtener los parámetros IDFA/Limit Ad Tracking:

Objective-C Swift
NSString* IDFA = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
NSString* IDFV = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
  
  BOOL isAdvertisingTrackingEnabled = [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled];

Recuperación de la configuración regional, el dispositivo y la compilación para iOS

Objective-C Swift
  // Locale - lc= query parameter
  NSString *locale = [[NSLocale currentLocale] localeIdentifier];
  
  // Model - mo= query paramter
  #import <sys/sysctl.h>
  NSString *device() {
      size_t bufferSize = 64;
      NSMutableData * buffer = [[NSMutableData alloc] initWithLength:bufferSize];
      int status = sysctlbyname("hw.machine", buffer.mutableBytes, &bufferSize, NULL, 0);
      if (status != 0) {
          return nil; 
      }
      return [[NSString alloc] initWithData:buffer encoding:NSUTF8StringEncoding];
  }
  
  // Build - bd= query parameter
  NSString * build () { 
      size_t bufferSize = 64;
      NSMutableData *buffer = [[NSMutableData alloc] initWithLength:bufferSize];
      int status = sysctlbyname("kern.osversion",buffer.mutableBytes, &bufferSize, NULL, 0);
      if (status != 0) {
          return nil;
      }
      return [[NSString alloc] initWithData:buffer encoding:NSUTF8StringEncoding];
  }