Singular

Singular — это платформа Mobile Measurement Partner (MMP), которая собирает и отображает данные маркетинговых кампаний.

Adapty отправляет в Singular события подписок, которые вы выбираете. В дашборде Singular вы можете видеть, какую выручку приносит каждая кампания, и оценивать эффективность рекламы.

Настройка интеграции

Подключение Adapty к Singular

Чтобы настроить интеграцию с Singular, перейдите в раздел Integrations > Singular дашборда Adapty, включите переключатель и заполните поля.

Доступны следующие учётные данные:

Singular SDK Key: Обязательное поле. Продакшн SDK-ключ вашего приложения в Singular.
Singular SDK Key (Sandbox): Необязательное поле. SDK-ключ для песочницы вашего приложения в Singular. Если не указан, события из песочницы не будут отправляться в Singular.

Оба ключа можно найти в дашборде Singular в разделе Developer tools -> SDK Keys -> SDK Key (не SDK Secret):

Настройте события и теги

Ниже учётных данных находятся три группы событий, которые можно отправлять в Singular из Adapty. Полный список событий Adapty см. в разделе События.

Рекомендуем использовать названия событий по умолчанию, предоставленные Adapty. При необходимости их можно изменить.

Adapty отправляет события подписок на сервер Singular по схеме server-to-server, поэтому вы можете просматривать все события подписок в дашборде Singular и связывать их с вашими рекламными кампаниями.

Warning

Профили, созданные до настройки интеграции, не смогут передавать свои события в Singular.

Подключите приложение к Singular

По умолчанию Singular включает Singular Device ID (SDID) для аккаунтов, созданных 15 июля 2026 года или позже. Такие аккаунты принимают события только через Event API v2, а Adapty отправляет событие в v2 только при наличии SDID в профиле пользователя. Чтобы события доставлялись в подобный аккаунт, передавайте SDID в Adapty из своего приложения.

Если ваш аккаунт Singular создан до 15 июля 2026 года и SDID на нём не включён, пропустите этот шаг. Adapty отправляет события через Event API v1, и изменения в коде приложения не требуются.

Активируйте Adapty, затем запустите Singular SDK с SDID-коллбэком: sdidReceivedHandler на iOS, SDIDAccessorHandler на Android, sdidReceivedCallback на React Native и Flutter, и SingularSdidAccessorHandler на Unity.
Дождитесь, пока Singular вызовет коллбэк. SDID приходит в ваше приложение асинхронно, после запуска Singular SDK. Singular вызывает коллбэк при каждом запуске, в том числе когда SDID уже сохранён на устройстве.
Внутри коллбэка передайте SDID в Adapty через setIntegrationIdentifier() с ключом singular_sdid. Ни один SDK Adapty не имеет предопределённой константы для этого ключа, поэтому используйте строковый литерал.
Вызывайте Adapty.identify() только после завершения setIntegrationIdentifier(). При активации Adapty создаёт анонимный профиль, а затем переключается на идентифицированный после того, как identify() завершится. SDID, установленный в момент этого переключения, может быть потерян.


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

Структура события

Adapty выбирает версию Singular Event API для каждого события в зависимости от того, есть ли в профиле пользователя SDID:

С SDID: Adapty отправляет POST-запрос на https://s2s.singular.net/api/v2/evt с телом в формате form-urlencoded. Параметр sdid заменяет идентификаторы устройства idfa, idfv, aifa, andi и asid. Булевы значения передаются как true или false.
Без SDID: Adapty отправляет GET-запрос на https://s2s.singular.net/api/v1/evt с параметрами запроса.

В остальном оба варианта содержат одинаковые параметры. Событие v1 имеет следующую структуру:

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

Где:

Параметр	Тип	Описание
`n`	String	Название события (маппится из события Adapty).
`a`	String	Ваш Singular SDK Key.
`p`	String	Платформа (“iOS” или “Android”).
`i`	String	Store App ID (Bundle ID).
`ip`	String	IP-адрес пользователя.
`sdid`	String	Только v2. Singular Device ID, из идентификатора интеграции `singular_sdid`.
`idfa`	String	iOS, только v1. ID for Advertisers (в верхнем регистре).
`idfv`	String	iOS, только v1. ID for Vendors (в верхнем регистре).
`aifa`	String	Android, только v1. Google Advertising ID (в нижнем регистре).
`andi`	String	Android, только v1. Android ID (в нижнем регистре).
`asid`	String	Android, только v1. App Set ID (в нижнем регистре).
`ve`	String	Версия ОС.
`att_authorization_status`	Integer	Только iOS. Статус ATT (например, `3` — авторизован).
`custom_user_id`	String	Customer User ID пользователя.
`utime`	Long	UNIX-временная метка события в секундах.
`partner`	String	Всегда `adapty`. Указывает, что событие отправлено Adapty.
`use_ip`	Boolean	`true`, если у Adapty нет IP-адреса пользователя.
`is_revenue_event`	Boolean	`true`, если событие содержит доход. Отправляется только с событиями дохода.
`amt`	Float	Сумма дохода.
`cur`	String	Код валюты (например, “USD”).
`purchase_product_id`	String	ID продукта из стора.
`purchase_transaction_id`	String	Оригинальный ID транзакции.
`e`	String	JSON-строка с деталями события (см. ниже).

Параметр e (данные пользовательского события) — это JSON-строка, содержащая:

Параметр	Тип	Описание
`is_revenue_event`	Boolean	`true`, если событие содержит выручку.
`amt`	Float	Сумма выручки.
`cur`	String	Код валюты.
`purchase_product_id`	String	ID продукта в сторе.
`purchase_transaction_id`	String	Оригинальный ID транзакции.

Устранение неполадок

События не проходят с ошибкой `invalid api version: v1`

Ваш аккаунт Singular был создан 15 июля 2026 года или позднее и принимает события только через Event API v2. Adapty отправил событие на v1, потому что в профиле пользователя нет SDID. Чтобы исправить это, передайте SDID в Adapty из своего приложения, как описано в разделе Подключите приложение к Singular. События от пользователей, использующих версию приложения без вызова setIntegrationIdentifier(), будут продолжать завершаться с ошибкой, пока те не обновят приложение.

`access_level_updated` отображается как «Не выполнено» в Event Feed

access_level_updated — это событие только для вебхуков. Adapty не отправляет его в эту интеграцию. Однако Adapty фиксирует результат для каждой активной интеграции, и неподдерживаемое событие отображается как ошибка.

Singular

Настройка интеграции

Подключение Adapty к Singular

Настройте события и теги

Подключите приложение к Singular

Структура события

Устранение неполадок

События не проходят с ошибкой invalid api version: v1

access_level_updated отображается как «Не выполнено» в Event Feed

События не проходят с ошибкой `invalid api version: v1`

`access_level_updated` отображается как «Не выполнено» в Event Feed