Интеграция с Singular

Глоссарий

Singular

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

Singular Device ID (SDID)

Уникальный ID, который определяет браузер каждого посетителя, автоматически генерируется Singular Web SDK.

ID приложения

ID мобильного приложения, уникальный для мобильной платформы (Android, iOS). Соответствует значению Bundle ID, которое вы можете найти в Singular в разделе Settings > Apps в панели необходимого приложения.

Пожизненная ценность (Lifetime Value или LTV)

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

Окупаемость затрат на рекламу (Return on advertising spend или ROAS)

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

Веб-событие (web event)

Действия пользователя в Web Shop. События при этих действиях отправляются с клиентской части Web Shop в Singular и необходимы для Web SDK-интеграции.

Событие в приложении (in-app event)

Действие пользователя в приложении. Подробная информация о событиях в приложении приведена в документации Singular. Действия пользователя в Web Shop также рассматриваются как события внутри приложения в случае S2S-интеграции и отправляются в Singular с сервера Xsolla.

Привлечение трафика

Процесс привлечения новых пользователей на сайт, сервис, платформу или приложение с помощью маркетинговой активности.

Ретаргетинг

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

Customer user ID (CUID)

ID пользователя, сгенерированный и установленный владельцем приложения в момент регистрации пользователя. CUID для Web Shop и Singular должны совпадать. Этот параметр используется для атрибуции пользователей.

Вам необходимо настроить передачу этого параметра в постбэке. Если CUID в Web Shop и вашем мобильном приложении не совпадают, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com, чтобы настроить обработку вебхука Проверка пользователя в Web Shop или аутентификации пользователя через диплинк.

Чтобы настроить CUID, следуйте документации Singular SDK.

Постбэк

Процесс получения данных о событиях в приложении. Подробная информация приведена в документации Singular.

Ключ SDK

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

Секрет SDK

Компонент, используемый вместе с ключом Singular SDK для инициализации и аутентификации Singular SDK в приложении. Этот секрет, совместно с ключом SDK, позволяет SDK безопасно взаимодействовать с платформой Singular и корректно атрибутировать установки приложения, события и другие данные для маркетинговой аналитики.

Сценарий интеграции

Singular и Xsolla поддерживают такие типы интеграции, как:

S2S-интеграция для мобильных приложений — позволяет измерять LTV и ROAS для покупок в приложении и в Web Shop. Xsolla отправляет информацию о покупках в Web Shop в Singular как in-app events в мобильном приложении. Singular связывает эти in-app events с количеством установок мобильного приложения, кампаниями по привлечению и повторному привлечению пользователей.
Web SDK интеграция — позволяет измерять и оценивать эффективность кампаний по привлечению пользователей и ретаргетинговых кампаний по привлечению трафика на Web Shop.
Web SDK интеграция позволяет оценить, сколько пользователей пришло через ретаргетинговую кампанию на сайт, и конверсию каналов, ведущих на сайт. Xsolla отправляет информацию о покупках в Web Shop в Singular в виде веб-событий. Singular связывает эти события с соответствующим источником медиа, кампанией, набором объявлений и конкретным объявлением, которые привели пользователя к покупке.

Вы можете настроить интеграцию Web SDK с Singular, чтобы получить расширенную аналитику, если вы используете:

С помощью Web SDK-интеграции Xsolla и Singular вы можете получать информацию о следующих событиях:

Событие	Описание
`load`	Посещение сайта. Содержит URL-адрес с информацией об источнике, откуда пришел пользователь, и Singular Device ID, который хранится в основных cookie сайта.
`identify`	Авторизация на сайте. Содержит Singular Device ID и CUID.
`event`	Покупки товара, а также другие события Site Builder. Содержит Singular Device ID и CUID.

Как это работает

Ниже приведен сценарий взаимодействия систем при реализации кампании по привлечению пользователей и ретаргетинговой кампании. Пользователи переходят по рекламным баннерам на Web Shop и совершают покупку. Набор событий, который при этом отправляется в Singular, позволяет увидеть:

какие пользователи, в каком количестве и с какого баннера перешли;
сколько они заплатили;
эффективна ли кампания по ретаргетингу.

  sequenceDiagram
    participant User
    participant Promo as Web Shop<br>promotional campaign<br>(ad banner)
    participant Shop as Web Shop
    participant SG as Singular
    User->>Promo: 1. Clicks banner
    Promo->>Shop: 2. Redirect with URL parameters
    Shop->>SG: 3. load event
    User->>Shop: 4. Logs in with CUID
    Shop->>SG: 5. identify event
    User->>Shop: 6. Makes purchase
    Shop->>SG: 7. event

Сценарий пользователя:

Пользователь нажимает баннер рекламной кампании.
Пользователь перенаправляется в Web Shop, и URL-адрес этого перехода включает параметры и макросы Singular, указывающие, с какого баннера и с какого сайта перешел пользователь.
С клиентской части Web Shop в Singular отправляется событие о посещении.
Пользователь авторизуется в Web Shop, используя CUID.
Событие авторизации отправляется в Singular.
Пользователь совершает покупку в Web Shop.
Событие покупки отправляется в Singular.

Как настроить в Singular

Авторизуйтесь в вашем аккаунте Singular.
Перейдите в раздел Settings > Apps.

Нажмите Add new app.

Укажите название вашего приложения

Выберите Web в качестве операционной системы.
В поле URL укажите домен вашего Web Shop, например: yourapp.yourcompany.com.
В поле Bundle ID укажите ваш Bundle ID в формате reverse-DNS, например: com.yourcompany.
Нажмите Сохранить.

Как настроить в Личном кабинете

Откройте проект в Личном кабинете.
Перейдите к настройкам вашего сайта одним из следующих способов:
- В боковом меню нажмите Каналы продаж > Веб-сайты, выберите ваш сайт и нажмите Настроить.
- В боковом меню нажмите Интеграции. В открывшемся разделе:
  1. Нажмите панель Singular.

- 1. На панели Web SDK (Site Builder) нажмите Настроить.

- 1. Выберите ваш сайт и нажмите Настроить.
  2. На вкладке Site settings перейдите в раздел Apps.
  3. В панели Singular нажмите Подключить.

В форме Подключение Singular заполните поля SDK key, SDK secret и Bundle ID.

Чтобы найти эту информацию в вашем аккаунте Singular:
1. Войдите в ваш аккаунт Singular.
2. Перейдите в раздел Developer Tools > SDK Integration.
3. Перейдите на вкладку SDK Keys.
4. Нажмите Show Keys.
5. Скопируйте значение поля SDK Key.
6. Скопируйте значение поля SDK Secret.

1. Чтобы найти ваш Bundle ID, перейдите в раздел Settings > Apps > Web Application и скопируйте Bundle ID.

Нажмите Подключить.

Как запускать веб- и in-app- рекламные кампании для Web Shop

Используйте эти инструкции, чтобы запускать и отслеживать рекламные кампании по привлечению и повторному привлечению пользователей для Xsolla Web Shop. Это относится:

к кампаниям web-to-web shop (реклама, направляющая пользователей с веб-источников в ваш Web Shop);
ретаргетинговым кампаниям in-app-to-web shop (реклама, направляющая пользователей из вашего приложения в ваш Web Shop).

Чтобы создать трекинговую ссылку для веб-кампаний в Singular:

Войдите в ваш аккаунт Singular.
Перейдите в раздел Attribution Setup и выберите Create Web Link.
В поле Target (App) выберите ваше веб-приложение, связанное с Xsolla Web Shop.
В поле Partner выберите вашего партнера по рекламной сети.

Введите путь к целевой странице (опционально).
Обновите поля UTM для захвата данных кампании (опционально).
Нажмите Generate Link.

URL-адрес конечного назначения для вашей веб-кампании будет сгенерирован на основе выбранных параметров. Используйте эту ссылку для направления трафика в рамках вашей веб-кампании.

Для более детализированного отслеживания кампаний (большей гранулярности) вы можете добавить макросы в сгенерированный URL. Используйте руководство, чтобы добавить параметры макросов для Singular Web SDK и позволить собирать данные на уровне кампаний. Убедитесь, что вы не перезаписываете существующие параметры ссылки.

Инструкции могут меняться в зависимости от выбранной рекламной сети. Всегда следуйте примечаниям для конкретной рекламной сети, которые отображаются в Web URL Builder.

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

Как добавить Web / Web Shop события в Singular

Войдите в ваш аккаунт Singular.
Перейдите в раздел Settings > Events.
Добавьте события, которые фиксирует ваш Web SDK:
1. Выберите App specific Events.
2. Выберите ваше приложение.
3. В разделе Cohort Events добавьте название события, которое будет отображаться в ваших отчетах.
4. В поле Event maps to the following выберите событие SDK.
5. Нажмите Save.

Подробная информация об отслеживании in-app events приведена в инструкции How to Track In-App Events.

События выручки автоматически включаются в метрику Revenue в отчетах Singular. Вам не нужно добавлять пользовательское событие, если только вы не хотите отслеживать количество событий выручки отдельно.

Как получить отчет об эффективности рекламных кампаний Web Shop в Singular

Чтобы создать отчет для рекламных кампаний web-to-web и in-app-to-web:

Войдите в ваш аккаунт Singular.
Перейдите в раздел Reports > Insights.
Настройте фильтры:
- Установите нужный диапазон дат.
- Выберите приложение, которое хотите проанализировать.

Добавьте измерения для сегментации данных:
- Source
- Campaign Name
- дополнительные измерения по необходимости

Выберите веб-метрики:
- Web New Visitors
- Web Re-Engaged Visitors

Включите данные когорт:
- Revenue
- ROI
- любые события для когорт пользователей, ранее настроенные на странице Settings > Events page

Нажмите Run report в правом верхнем углу.

Установите точную систему наименования для ваших кампаний, которая различает кампании web-to-web и in-app-to-web. Такая таксономия значительно упрощает аналитические отчеты и позволяет вашей команде быстро определять типы кампаний.

Обратитесь к частым вопросам про отчеты, чтобы узнать больше.

Вы можете настроить S2S-интеграцию для мобильных приложений и получать расширенную аналитику событий, если:

у вас есть мобильное приложение на платформе Android/iOS;
вы используете Singular;
вы используете решение Web Shop для продажи внутриигровых товаров.

С помощью S2S-интеграции Xsolla и Singular вы можете получать информацию о следующем событии:

Событие	Описание
xsolla-billing-payment	Покупка товара. Параметры события содержат информацию о покупке.

Как это работает

В рамках интеграции реализован двусторонний обмен данными между Xsolla и Singular. Ниже приведен сценарий взаимодействия систем, когда пользователь совершает покупку.

  sequenceDiagram
    participant User
    participant Mobile App
    participant Web Shop
    participant Xsolla Backend
    participant Singular
    User->>Mobile App: 1. Logs in
    Mobile App->>Singular: 2. Sends CUID
    Singular-->>Xsolla Backend: 3. Sends postback
    User->>Web Shop: 4. Logs in using CUID
    User->>Web Shop: 5. Makes a purchase
    Web Shop->>Xsolla Backend: 6. Sends purchase event
    Xsolla Backend->>Singular: 7. Sends xsolla-billing-payment event

Пользователь (игрок) регистрируется или авторизуется в мобильном приложении.
Ваше приложение отправляет в Singular событие, например login, или любое другое событие, которое содержит CUID.

Чтобы настроить CUID, следуйте документации Singular SDK.

Singular отправляет постбэк к Xsolla, который содержит CUID и данные об устройстве пользователя.
Пользователь авторизуется в Web Shop, используя CUID.
Пользователь совершает покупку в Web Shop.
Событие покупки отправляется на сервер Xsolla и сопоставляется с информацией, полученной от Singular.
Сервер Xsolla отправляет в Singular событие из приложения, которое содержит параметры, необходимые для маппинга.

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

Как настроить в Личном кабинете

В проекте в Личном кабинете перейдите в раздел Интеграции.
Нажмите панель Singular.

В панели S2S-интеграция для приложений нажмите Настроить.
В открывшемся окне проверьте, что флажок Включить эту интеграцию установлен.
Укажите следующие данные:
1. Ключ SDK из Singular.
2. ID приложения, уникальный для мобильной платформы (Android/iOS). Чтобы добавить платформу, нажмите Добавить ID приложения.
Нажмите Сохранить.
Настройте интеграцию на стороне Singular.

После сохранения в панели S2S-интеграции будет отображаться зеленый индикатор.

Чтобы внести изменения:

Нажмите панель Singular.
В открывшемся окне внесите необходимые изменения.
Нажмите Сохранить.

Как настроить в Singular

В Singular вам необходимо:

Получить ключ SDK.
Активировать интеграцию с Xsolla.

Получение ключа SDK

Авторизуйтесь в вашем аккаунте Singular.
Откройте раздел Developer Tools > SDK Integration.
Перейдите на вкладку SDK Keys.
Нажмите Show Keys.
Скопируйте значение из поля SDK Key.

Активация интеграции с Xsolla

Авторизуйтесь в вашем аккаунте Singular.
Перейдите в раздел Attribution Setup > Partner Configuration.
Нажмите Add Partner.
В поисковой строке введите и выберите Xsolla.

В открывшемся окне в раскрывающемся списке выберите приложение, для которого вы настраиваете интеграцию.
Нажмите Next.
Убедитесь, что в блоке Events Postbacks выбрано событие Login.
Нажмите Save.

Убедитесь, что вы настроили CUID:

Должны быть реализованы метод SetCustomerId и событие аутентификации с помощью Singular SDK.
В вашем проекте в Личном кабинете Xsolla настроена интеграция с Singular.
В вашем аккаунте Singular активирована интеграция с Xsolla.

Если в вашем аккаунте Singular включена опция Reject IAP without receipt, свяжитесь с менеджером по работе с клиентами Singular, чтобы включить или отключить поддержку событий Xsolla, связанных с получением дохода.

Структура значений событий

Если вы хотите настроить определенное событие или если текущие возможности интеграции не соответствуют вашим потребностям, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.

Покупка товара

Когда пользователь совершает покупку в Web Shop, Xsolla отправляет событие xsolla-billing-payment в Singular. В параметрах события передается следующая информация о покупке:

Параметр	Описание
content_id	Отдельный артикул товара или массив артикулов в покупке.
quantity	Количество товара соответствующего артикула (один или массив).
revenue	Сумма покупки с учетом скидок. До вычета комиссий и налогов.
currency	Валюта покупки.

Дополнительные данные

В дополнение к параметрам, переданным в событии xsolla-billing-payment, Xsolla отправляет следующие данные:

Параметр	Описание
a	Ключ SDK из Singular.
p	Платформа приложения. Пример: iOS.
ip	Публичный IP-адрес устройства пользователя.
ve	Версия операционной системы устройства пользователя.
ma	Бренд устройства пользователя. Пример: Apple.
mo	Модель устройства пользователя. Пример: iPhone 4S.
lc	Локаль устройства пользователя в формате `^[a-z]{2}-[A-Z]{2}$`. Пример: `en_US`.
i	ID приложения на стороне Singular.
att_authorization_status	Код статуса App Tracking Transparency (ATT).
n	Название события. Максимальная длина — 32 символа.
is_revenue_event	Связано ли событие с получением прибыли.
amt	Количество валюты.
cur	Валюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
custom_user_id	CUID.
partner	Партнер — `xsolla`.
e	Другие пользовательские параметры (опционально).

Спасибо за обратную связь!

Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.

Последнее обновление: 30 декабря 2025

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Содержание

Глоссарий
Сценарий интеграции
Как это работает
Как настроить в Singular
Как настроить в Личном кабинете
Как запускать веб- и in-app- рекламные кампании для Web Shop
Как добавить Web / Web Shop события в Singular
Как получить отчет об эффективности рекламных кампаний Web Shop в Singular
Как это работает
Как настроить в Личном кабинете
Как настроить в Singular
Получение ключа SDK
Активация интеграции с Xsolla
Структура значений событий
Покупка товара
Дополнительные данные

Your browser is not supported. Please try a different browser

Интеграция с Singular

Глоссарий

Singular

Singular Device ID (SDID)

ID приложения

Пожизненная ценность (Lifetime Value или LTV)

Окупаемость затрат на рекламу (Return on advertising spend или ROAS)

Веб-событие (web event)

Событие в приложении (in-app event)

Привлечение трафика

Ретаргетинг

Customer user ID (CUID)

Постбэк

Ключ SDK

Секрет SDK

Сценарий интеграции

Как это работает

Как настроить в Singular

Как настроить в Личном кабинете

Как запускать веб- и in-app- рекламные кампании для Web Shop

Как добавить Web / Web Shop события в Singular

Как получить отчет об эффективности рекламных кампаний Web Shop в Singular

Как это работает

Как настроить в Личном кабинете

Как настроить в Singular

Получение ключа SDK

Активация интеграции с Xsolla

Структура значений событий

Покупка товара

Дополнительные данные