Singular

Singular is a Mobile Measurement Partner (MMP) platform that collects and presents data from marketing campaigns.

Adapty sends the subscription events you select to Singular. In the Singular dashboard, you can then see how much revenue each campaign generates and evaluate the effectiveness of your advertising.

Set up integration

Connect Adapty to Singular

To set up the integration with Singular, go to Integrations > Singular in your Adapty Dashboard, turn on a toggle, and fill out the fields.

The following credentials are available:

• Singular SDK Key: Required. The production SDK key for your Singular app.
• Singular SDK Key (Sandbox): Optional. The SDK key for your sandbox Singular app. If not set, sandbox events will not be sent to Singular.

Both keys can be found in the Singular dashboard under Developer tools -> SDK Keys -> SDK Key (not SDK Secret):

Configure events and tags

Below the credentials, there are three groups of events you can send to Singular from Adapty. For the full list of Adapty events, see Events.

We recommend using the default event names provided by Adapty. But you can change the event names based on your needs.

Adapty sends subscription events to Singular server-to-server, so you can view all subscription events in your Singular dashboard and link them to your acquisition campaigns.

Connect your app to Singular

Singular enables the Singular Device ID (SDID) by default for accounts created on or after July 15, 2026. These accounts accept events only through the v2 Event API, and Adapty sends an event to v2 only when the user’s profile has an SDID. To deliver events to such an account, pass the SDID to Adapty from your app.

If your Singular account was created before July 15, 2026, and SDID isn’t enabled on it, skip this step. Adapty sends your events to the v1 Event API, and no app code is needed.

1. Activate Adapty, then start the Singular SDK with an SDID callback: sdidReceivedHandler on iOS, SDIDAccessorHandler on Android, sdidReceivedCallback on React Native and Flutter, and SingularSdidAccessorHandler on Unity.
2. Wait for Singular to call the callback. The SDID reaches your app asynchronously, after the Singular SDK starts. Singular calls the callback on every launch, including when the SDID is already stored on the device.
3. Inside the callback, pass the SDID to Adapty with setIntegrationIdentifier() and the singular_sdid key. No Adapty SDK has a predefined constant for this key, so write the key as a string literal.
4. Call Adapty.identify() only after setIntegrationIdentifier() completes. Adapty creates an anonymous profile at activation, then switches to the identified profile once identify() resolves. An SDID set during that switch can be lost.

import Adapty
import Singular

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);

import { adapty } from 'react-native-adapty';
import { Singular, SingularConfig } from 'singular-react-native';

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);

import 'package:adapty_flutter/adapty_flutter.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';

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

import { adapty } from '@adapty/capacitor';

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

Event structure

Adapty picks the Singular Event API version for each event by whether the user’s profile has an SDID:

• With an SDID: Adapty sends a POST request to https://s2s.singular.net/api/v2/evt with a form-urlencoded body. The sdid parameter replaces the device identifiers idfa, idfv, aifa, andi, and asid. Booleans are sent as true or false.
• Without an SDID: Adapty sends a GET request to https://s2s.singular.net/api/v1/evt with query parameters.

Both versions carry the same parameters otherwise. A v1 event is structured like this:

{
  "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:

The e parameter (custom event data) is a JSON-encoded string containing:

Troubleshooting

Events fail with invalid api version: v1

Your Singular account was created on or after July 15, 2026, and accepts events only through the v2 Event API. Adapty sent the event to v1 because the user’s profile has no SDID. To fix this, pass the SDID to Adapty from your app, as described in Connect your app to Singular. Events from users on an app version without the setIntegrationIdentifier() call keep failing until those users update the app.

access_level_updated shows as failed in the Event Feed

access_level_updated is a webhook-only event. Adapty never sends it to this integration. But Adapty records an outcome for every enabled integration, and an unsupported event is displayed as a failure.