Singular

Singular est une plateforme MMP (Mobile Measurement Partner) qui collecte et présente des données issues des campagnes marketing.

Adapty envoie les événements d’abonnement que vous sélectionnez à Singular. Dans le tableau de bord Singular, vous pouvez ensuite voir le chiffre d’affaires généré par chaque campagne et évaluer l’efficacité de votre publicité.

Configurer l’intégration

Connecter Adapty à Singular

Pour configurer l’intégration avec Singular, rendez-vous dans Integrations > Singular dans votre Adapty Dashboard, activez le bouton et renseignez les champs.

Les identifiants suivants sont disponibles :

Singular SDK Key : Obligatoire. La clé SDK de production pour votre application Singular.
Singular SDK Key (Sandbox) : Facultatif. La clé SDK pour votre application Singular en sandbox. Si elle n’est pas renseignée, les événements sandbox ne seront pas envoyés à Singular.

Les deux clés se trouvent dans le tableau de bord Singular sous Developer tools -> SDK Keys -> SDK Key (not SDK Secret) :

Configurer les événements et les tags

Sous les identifiants, vous trouverez trois groupes d’événements que vous pouvez envoyer à Singular depuis Adapty. Pour la liste complète des événements Adapty, consultez Événements.

Nous recommandons d’utiliser les noms d’événements fournis par défaut par Adapty. Vous pouvez toutefois les modifier selon vos besoins.

Adapty envoie les événements d’abonnement à Singular en server-to-server, ce qui vous permet de consulter tous les événements d’abonnement dans votre tableau de bord Singular et de les associer à vos campagnes d’acquisition.

Warning

Les profils créés avant la mise en place de l’intégration ne peuvent pas transmettre leurs événements à Singular.

Connecter votre application à Singular

Singular active par défaut le Singular Device ID (SDID) pour les comptes créés à partir du 15 juillet 2026. Ces comptes n’acceptent les événements que via la v2 de l’Event API, et Adapty n’envoie un événement en v2 que si le profil de l’utilisateur contient un SDID. Pour transmettre des événements à ce type de compte, passez le SDID à Adapty depuis votre application.

Si votre compte Singular a été créé avant le 15 juillet 2026 et que le SDID n’y est pas activé, ignorez cette étape. Adapty envoie vos événements à la v1 de l’Event API et aucune modification du code de l’application n’est nécessaire.

Activez Adapty, puis démarrez le SDK Singular avec un callback SDID : sdidReceivedHandler sur iOS, SDIDAccessorHandler sur Android, sdidReceivedCallback sur React Native et Flutter, et SingularSdidAccessorHandler sur Unity.
Attendez que Singular appelle le callback. Le SDID arrive dans votre application de manière asynchrone, après le démarrage du SDK Singular. Singular appelle le callback à chaque lancement, y compris lorsque le SDID est déjà stocké sur l’appareil.
Dans le callback, transmettez le SDID à Adapty avec setIntegrationIdentifier() et la clé singular_sdid. Aucun SDK Adapty ne possède de constante prédéfinie pour cette clé, écrivez-la donc sous forme de chaîne littérale.
N’appelez Adapty.identify() qu’après la fin de setIntegrationIdentifier(). Adapty crée un profil anonyme à l’activation, puis bascule vers le profil identifié une fois que identify() est résolu. Un SDID défini pendant cette transition peut être perdu.


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
  }
}

Structure d’un événement

Adapty choisit la version de l’API Singular Event pour chaque événement selon que le profil de l’utilisateur possède un SDID :

Avec un SDID : Adapty envoie une requête POST vers https://s2s.singular.net/api/v2/evt avec un corps encodé en form-urlencoded. Le paramètre sdid remplace les identifiants d’appareil idfa, idfv, aifa, andi et asid. Les booléens sont envoyés sous la forme true ou false.
Sans SDID : Adapty envoie une requête GET vers https://s2s.singular.net/api/v1/evt avec des paramètres de requête.

Les deux versions transmettent les mêmes paramètres pour le reste. Un événement v1 est structuré ainsi :

{
  "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...\"}"
}

Where:

Paramètre	Type	Description
`n`	String	Le nom de l’événement (mappé depuis l’événement Adapty).
`a`	String	Votre clé SDK Singular.
`p`	String	Plateforme (“iOS” ou “Android”).
`i`	String	App ID du store (Bundle ID).
`ip`	String	Adresse IP de l’utilisateur.
`sdid`	String	v2 uniquement. Singular Device ID, issu de l’identifiant d’intégration `singular_sdid`.
`idfa`	String	iOS, v1 uniquement. ID for Advertisers (majuscules).
`idfv`	String	iOS, v1 uniquement. ID for Vendors (majuscules).
`aifa`	String	Android, v1 uniquement. Google Advertising ID (minuscules).
`andi`	String	Android, v1 uniquement. Android ID (minuscules).
`asid`	String	Android, v1 uniquement. App Set ID (minuscules).
`ve`	String	Version de l’OS.
`att_authorization_status`	Integer	iOS uniquement. Statut ATT (ex. : `3` pour autorisé).
`custom_user_id`	String	L’identifiant Customer User ID de l’utilisateur.
`utime`	Long	Horodatage UNIX de l’événement en secondes.
`partner`	String	Toujours `adapty`. Identifie l’événement comme envoyé par Adapty.
`use_ip`	Boolean	`true` quand Adapty ne dispose pas d’adresse IP pour l’utilisateur.
`is_revenue_event`	Boolean	`true` si l’événement contient un revenu. Envoyé uniquement avec les événements de revenu.
`amt`	Float	Montant du revenu.
`cur`	String	Code de devise (ex. : “USD”).
`purchase_product_id`	String	L’identifiant produit du store.
`purchase_transaction_id`	String	Identifiant de transaction original.
`e`	String	Chaîne JSON contenant les détails de l’événement (voir ci-dessous).

Le paramètre e (données d’événement personnalisées) est une chaîne encodée en JSON contenant :

Paramètre	Type	Description
`is_revenue_event`	Boolean	`true` si l’événement contient un revenu.
`amt`	Float	Montant du revenu.
`cur`	String	Code de devise.
`purchase_product_id`	String	L’identifiant du produit dans le store.
`purchase_transaction_id`	String	Identifiant de transaction d’origine.

Dépannage

Les événements échouent avec `invalid api version: v1`

Votre compte Singular a été créé le 15 juillet 2026 ou après cette date, et n’accepte les événements que via l’API Event v2. Adapty a envoyé l’événement à v1 car le profil de l’utilisateur ne contient pas de SDID. Pour corriger cela, transmettez le SDID à Adapty depuis votre application, comme décrit dans Connecter votre application à Singular. Les événements des utilisateurs sur une version de l’application sans l’appel setIntegrationIdentifier() continuent d’échouer jusqu’à ce que ces utilisateurs mettent à jour l’application.

`access_level_updated` s’affiche comme échoué dans le flux d’événements

access_level_updated est un événement réservé aux webhooks. Adapty ne l’envoie jamais à cette intégration. Mais Adapty enregistre un résultat pour chaque intégration activée, et un événement non pris en charge est affiché comme un échec.

Singular

Configurer l’intégration

Connecter Adapty à Singular

Configurer les événements et les tags

Connecter votre application à Singular

Structure d’un événement

Dépannage

Les événements échouent avec invalid api version: v1

access_level_updated s’affiche comme échoué dans le flux d’événements

Les événements échouent avec `invalid api version: v1`

`access_level_updated` s’affiche comme échoué dans le flux d’événements