Singular

Singular es una plataforma de Mobile Measurement Partner (MMP) que recopila y presenta datos de campañas de marketing.

Adapty envía los eventos de suscripción que selecciones a Singular. En el dashboard de Singular, podrás ver cuántos ingresos genera cada campaña y evaluar la efectividad de tu publicidad.

Configurar la integración

Conectar Adapty con Singular

Para configurar la integración con Singular, ve a Integrations > Singular en tu Adapty Dashboard, activa el toggle y rellena los campos.

Las siguientes credenciales están disponibles:

Singular SDK Key: Obligatorio. La clave SDK de producción para tu app de Singular.
Singular SDK Key (Sandbox): Opcional. La clave SDK para tu app de Singular en sandbox. Si no se configura, los eventos de sandbox no se enviarán a Singular.

Ambas claves se encuentran en el dashboard de Singular en Developer tools -> SDK Keys -> SDK Key (no SDK Secret):

Configurar eventos y etiquetas

A continuación de las credenciales, hay tres grupos de eventos que puedes enviar a Singular desde Adapty. Para ver la lista completa de eventos de Adapty, consulta Eventos.

Te recomendamos usar los nombres de eventos predeterminados que ofrece Adapty, aunque puedes cambiarlos según tus necesidades.

Adapty envía eventos de suscripción al servidor de Singular server-to-server, para que puedas ver todos los eventos de suscripción en tu dashboard de Singular y vincularlos a tus campañas de adquisición.

Warning

Los perfiles creados antes de configurar la integración no pueden enviar sus eventos a Singular.

Conecta tu app con Singular

Singular habilita el Singular Device ID (SDID) por defecto en las cuentas creadas a partir del 15 de julio de 2026. Estas cuentas solo aceptan eventos a través de la API de eventos v2, y Adapty envía un evento a v2 únicamente cuando el perfil del usuario tiene un SDID. Para enviar eventos a este tipo de cuenta, pasa el SDID a Adapty desde tu app.

Si tu cuenta de Singular se creó antes del 15 de julio de 2026 y el SDID no está habilitado en ella, omite este paso. Adapty envía tus eventos a la API de eventos v1 y no es necesario añadir código en la app.

Activa Adapty y luego inicia el SDK de Singular con un callback de SDID: sdidReceivedHandler en iOS, SDIDAccessorHandler en Android, sdidReceivedCallback en React Native y Flutter, y SingularSdidAccessorHandler en Unity.
Espera a que Singular llame al callback. El SDID llega a tu app de forma asíncrona, después de que el SDK de Singular se inicie. Singular llama al callback en cada lanzamiento, incluso cuando el SDID ya está almacenado en el dispositivo.
Dentro del callback, pasa el SDID a Adapty con setIntegrationIdentifier() y la clave singular_sdid. Ningún SDK de Adapty tiene una constante predefinida para esta clave, así que escríbela como un literal de cadena.
Llama a Adapty.identify() solo después de que setIntegrationIdentifier() se complete. Adapty crea un perfil anónimo al activarse y luego cambia al perfil identificado una vez que identify() se resuelve. Un SDID establecido durante ese cambio puede perderse.


let config = SingularConfig(apiKey: "<SINGULAR_SDK_KEY>", andSecret: "<SINGULAR_SDK_SECRET>")

config.sdidReceivedHandler = { sdid in
    Task {
        do {
            try await Adapty.setIntegrationIdentifier(
                AdaptyIntegrationIdentifier(key: "singular_sdid", value: sdid)
            )
            // Call Adapty.identify() here, if your app identifies users
        } catch {
            // handle the error
        }
    }
}

Singular.start(config)

val config = SingularConfig("<SINGULAR_SDK_KEY>", "<SINGULAR_SDK_SECRET>")
    .withCustomSdid(null, object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {}

        override fun sdidReceived(result: String) {
            Adapty.setIntegrationIdentifier(
                AdaptyIntegrationIdentifier(AdaptyIntegrationIdentifier.Key("singular_sdid"), result)
            ) { error ->
                if (error != null) {
                    // handle the error
                    return@setIntegrationIdentifier
                }
                // Call Adapty.identify() here, if your app identifies users
            }
        }
    })

Singular.init(context, config)

SingularConfig config = new SingularConfig("<SINGULAR_SDK_KEY>", "<SINGULAR_SDK_SECRET>")
    .withCustomSdid(null, new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {}

        @Override
        public void sdidReceived(String result) {
            Adapty.setIntegrationIdentifier(
                new AdaptyIntegrationIdentifier(new AdaptyIntegrationIdentifier.Key("singular_sdid"), result),
                error -> {
                    if (error != null) {
                        // handle the error
                        return;
                    }
                    // Call Adapty.identify() here, if your app identifies users
                }
            );
        }
    });

Singular.init(context, config);


const config = new SingularConfig('<SINGULAR_SDK_KEY>', '<SINGULAR_SDK_SECRET>')
  // null keeps the SDID that Singular generates. Singular's typings require a string.
  .withCustomSdid(null as unknown as string, () => {}, async (sdid) => {
    try {
      await adapty.setIntegrationIdentifier('singular_sdid', sdid);
      // Call adapty.identify() here, if your app identifies users
    } catch (error) {
      // handle `AdaptyError`
    }
  });

Singular.init(config);


final config = SingularConfig('<SINGULAR_SDK_KEY>', '<SINGULAR_SDK_SECRET>');

config.sdidReceivedCallback = (String sdid) async {
  try {
    await Adapty().setIntegrationIdentifier(
      key: 'singular_sdid',
      value: sdid,
    );
    // Call Adapty().identify() here, if your app identifies users
  } on AdaptyError catch (adaptyError) {
    // handle the error
  } catch (e) {
    // handle the error
  }
};

Singular.start(config);

using AdaptySDK;
using Singular;

public class SingularSdidHandler : SingularSdidAccessorHandler
{
    public void DidSetSdid(string result) {}

    public void SdidReceived(string result)
    {
        Adapty.SetIntegrationIdentifier(
            "singular_sdid",
            result,
            (error) => {
                if (error != null) {
                    // handle the error
                    return;
                }
                // Call Adapty.Identify() here, if your app identifies users
            });
    }
}

// Register the handler before the Singular SDK initializes
SingularSDK.SetSingularSdidAccessorHandler(new SingularSdidHandler());

// Call this from the SDID callback of the native Singular SDK
// on each platform: sdidReceivedHandler on iOS, SDIDAccessorHandler on Android
suspend fun onSingularSdidReceived(sdid: String) {
    Adapty.setIntegrationIdentifier("singular_sdid", sdid)
        .onSuccess {
            // Call Adapty.identify() here, if your app identifies users
        }
        .onError { error ->
            // handle the error
        }
}


// Call this from the SDID callback of the Singular SDK
async function onSingularSdidReceived(sdid: string) {
  try {
    await adapty.setIntegrationIdentifier({ key: 'singular_sdid', value: sdid });
    // Call adapty.identify() here, if your app identifies users
  } catch (error) {
    // handle the error
  }
}

Estructura del evento

Adapty selecciona la versión de la API de eventos de Singular según si el perfil del usuario tiene un SDID:

Con SDID: Adapty envía una solicitud POST a https://s2s.singular.net/api/v2/evt con un cuerpo codificado en form-urlencoded. El parámetro sdid reemplaza los identificadores de dispositivo idfa, idfv, aifa, andi y asid. Los booleanos se envían como true o false.
Sin SDID: Adapty envía una solicitud GET a https://s2s.singular.net/api/v1/evt con parámetros de consulta.

Ambas versiones comparten los mismos parámetros en todo lo demás. Un evento v1 tiene esta estructura:

{
  "n": "subscription_renewed",
  "a": "singular_sdk_key_123",
  "p": "iOS",
  "i": "com.example.app",
  "ip": "192.168.100.1",
  "idfa": "00000000-0000-0000-0000-000000000000",
  "idfv": "00000000-0000-0000-0000-000000000000",
  "ve": "17.0.1",
  "att_authorization_status": 3,
  "custom_user_id": "user_12345",
  "utime": 1709294400,
  "partner": "adapty",
  "use_ip": false,
  "is_revenue_event": true,
  "amt": 9.99,
  "cur": "USD",
  "purchase_product_id": "yearly.premium.6999",
  "purchase_transaction_id": "GPA.3383...",
  "e": "{\"is_revenue_event\":true,\"amt\":9.99,\"cur\":\"USD\",\"purchase_product_id\":\"yearly.premium.6999\",\"purchase_transaction_id\":\"GPA.3383...\"}"
}

Donde:

Parámetro	Tipo	Descripción
`n`	String	El nombre del evento (mapeado desde el evento de Adapty).
`a`	String	Tu clave SDK de Singular.
`p`	String	Plataforma (“iOS” o “Android”).
`i`	String	ID de la app en el store (Bundle ID).
`ip`	String	Dirección IP del usuario.
`sdid`	String	Solo v2. ID de dispositivo de Singular, obtenido del identificador de integración `singular_sdid`.
`idfa`	String	iOS, solo v1. ID para anunciantes (en mayúsculas).
`idfv`	String	iOS, solo v1. ID para proveedores (en mayúsculas).
`aifa`	String	Android, solo v1. Google Advertising ID (en minúsculas).
`andi`	String	Android, solo v1. Android ID (en minúsculas).
`asid`	String	Android, solo v1. App Set ID (en minúsculas).
`ve`	String	Versión del sistema operativo.
`att_authorization_status`	Integer	Solo iOS. Estado de ATT (p. ej., `3` para autorizado).
`custom_user_id`	String	El Customer User ID del usuario.
`utime`	Long	Marca de tiempo UNIX del evento en segundos.
`partner`	String	Siempre `adapty`. Identifica el evento como enviado por Adapty.
`use_ip`	Boolean	`true` cuando Adapty no tiene dirección IP para el usuario.
`is_revenue_event`	Boolean	`true` si el evento contiene ingresos. Se envía solo con eventos de ingresos.
`amt`	Float	Importe de los ingresos.
`cur`	String	Código de moneda (p. ej., “USD”).
`purchase_product_id`	String	El ID del producto en el store.
`purchase_transaction_id`	String	ID de transacción original.
`e`	String	Cadena JSON con los detalles del evento (ver más abajo).

El parámetro e (datos de evento personalizados) es una cadena codificada en JSON que contiene:

Parámetro	Tipo	Descripción
`is_revenue_event`	Boolean	`true` si el evento contiene ingresos.
`amt`	Float	Importe de los ingresos.
`cur`	String	Código de moneda.
`purchase_product_id`	String	El ID del producto en el store.
`purchase_transaction_id`	String	ID de transacción original.

Solución de problemas

Los eventos fallan con `invalid api version: v1`

Tu cuenta de Singular fue creada el 15 de julio de 2026 o después, y solo acepta eventos a través de la API de eventos v2. Adapty envió el evento a v1 porque el perfil del usuario no tiene SDID. Para solucionarlo, pasa el SDID a Adapty desde tu app, tal como se describe en Conecta tu app a Singular. Los eventos de usuarios que tengan una versión de la app sin la llamada setIntegrationIdentifier() seguirán fallando hasta que actualicen la app.

`access_level_updated` aparece como fallido en el Event Feed

access_level_updated es un evento exclusivo de webhooks. Adapty nunca lo envía a esta integración. Sin embargo, Adapty registra un resultado para cada integración habilitada, y un evento no compatible se muestra como un error.

Singular

Configurar la integración

Conectar Adapty con Singular

Configurar eventos y etiquetas

Conecta tu app con Singular

Estructura del evento

Solución de problemas

Los eventos fallan con invalid api version: v1

access_level_updated aparece como fallido en el Event Feed

Los eventos fallan con `invalid api version: v1`

`access_level_updated` aparece como fallido en el Event Feed