Integration with Singular

Glossary

Singular

Mobile attribution and marketing analytics platform. Singular enables application developers, marketers, and brands to track, measure, and optimize the effectiveness of their marketing campaigns across various channels and devices to drive faster growth with smarter ROI insights. Refer to the Singular documentation for detailed information about the platform.

Singular Device ID (SDID)

Unique ID that identifies each visitor’s browser, generated automatically by Singular Web SDK.

Application ID

Mobile application ID unique for each platform (Android, iOS). It corresponds to the Bundle ID value that you can find in Singular in the Settings > Apps section, in the pane of a necessary application.

Lifetime Value (LTV)

Average revenue that a user generates during the time they use your application. Refer to the Singular documentation for more information about the LTV.

Return on advertising spend (ROAS)

Metric that measures the effectiveness of an advertising campaign by calculating the revenue earned per unit of advertising spend.

Web event

User’s actions in Web Shop, which are sent from the client side of Web Shop to Singular and are necessary for the Web SDK integration.

In-app event

User action within the application. Refer to the Singular documentation for detailed information about the in-app events. User actions in Web Shop are also considered in-app events in the case of S2S integration and sent to Singular from the Xsolla backend.

User acquisition

The process of attracting new users to a site, service, platform, or application through marketing activity.

Retargeting

Reaching out to current or past users through advertising campaigns. Refers to the strategy of engaging users who have previously interacted with your application or site. Refer to the Singular documentation for detailed information.

Customer user ID (CUID)

User ID generated and set by the application owner at the time of user registration. The СUID should be the same for Web Shop and Singular. This parameter is used for user matching and attribution.

You need to pass this parameter in the postback. If CUIDs in the Web Shop and your mobile application don’t match, contact your Customer Success Manager or email to csm@xsolla.com to implement the User validation in Web Shop webhook or authentication via a deep link.

To configure the CUID, refer to the Singular SDK documentation.

Postback

Process of receiving data on in-app events. Refer to the Singular documentation for detailed information.

SDK key

Token that is used to authorize calls for sending event data to Singular. It’s generated on the Singular side. Refer to the Singular documentation for detailed information.

SDK secret

Component used in conjunction with the Singular SDK key to initialize and authenticate the Singular SDK within an application. This secret, along with the SDK key, allows the SDK to communicate securely with the Singular platform and correctly attribute application installations, events, and other data for marketing analytics.

Integration flow

Singular and Xsolla support the following types of integrations:

Mobile application S2S integration — allows completion of full LTV and ROAS measurement for the purchases within the application and on Web Shop. Xsolla sends information about purchases in Web Shop to Singular as mobile in-app events, which Singular then attributes to the number of mobile application installations, user acquisition and re-engagement campaigns.
Web SDK integration — allows you to measure and evaluate the effectiveness of user acquisition and retargeting campaigns for attracting traffic to Web Shop.
Web SDK integration allows assessment of how many users came to the site through a retargeting campaign and the conversion of channels leading to the site. Xsolla sends information about purchases in Web Shop to Singular as web events, which Singular attributes to the corresponding media source, campaign, advertising set, and advertisement that led the user to the purchase.

You can configure Web SDK integration with Singular to get advanced event analytics if you use:

The following events are available via the Xsolla and Singular Web SDK integration:

Event	Description
`load`	Site visit event, including URL parameters that contain the source information where the user is coming from, and a Singular Device ID, which is stored in a first-party cookie.
`identify`	Login event, including the Singular Device ID and CUID.
`event`	Item purchase event, including the Singular Device ID and CUID, and other Site Builder events.

How it works

Below is a scenario of system interaction when implementing a user acquisition and retargeting campaigns. The user goes through advertising banners to Web Shop and makes a purchase. The set of events that are sent to Singular in this process allows us to track:

how many users clicked each banner and where they came from
how much users paid
whether the retargeting campaign was effective

  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

User flow:

The user clicks the ad campaign banner.
The user is redirected to Web Shop, and the URL of this transition includes the Singular parameters and macros, specifying from which banner and website the user was directed.
An event about the visit is sent from the client side of Web Shop to Singular.
The user logs into Web Shop using CUID.
The authorization event is sent to Singular.
The user makes a purchase in Web Shop.
The purchase event is sent to Singular.

How to set up in Singular

Log in to your Singular account.
Go to the Settings > Apps section.

Click Add new app.

Specify your web application name.

Select Web as the OS.
In the URL field, specify the domain of your Web Shop, e.g., yourapp.yourcompany.com.
In the Bundle ID field, specify your Bundle ID in the reverse-DNS format, e.g., com.yourcompany.
Click Save.

How to set up in Publisher Account

Open your project in Publisher Account.
Go to the site builder using one of these methods:
- In the side menu, click Storefronts > Websites, select your site and click Configure.
- In the side menu, click Integrations. In the section that opens:
  1. Click the Singular pane.

- 1. In the Web SDK (Site Builder) pane, click Configure.

- 1. Select your site and click Configure.
  2. On the Site settings tab, go to the Apps section.
  3. In the Singular pane, click Connect.

In the Singular connection form, fill out the SDK key, SDK secret and the Bundle ID fields:

To find this information in your account in Singular:
1. Log in to your Singular account.
2. Go to the Developer Tools > SDK Integration section.
3. Go to the SDK Keys tab.
4. Click Show Keys.
5. Copy the value in the SDK Key field.
6. Copy the value in the SDK Secret field.

1. To find your Bundle ID, go to Settings > Apps > Web Application and copy the Bundle ID.

Click Connect.

How to run web and in-app ad campaigns for Web Shop

Use these instructions to run and track user acquisition and retargeting ad campaigns for Xsolla Web Shop. This applies to both:

web-to-web shop campaigns (ads driving users from web sources to your Web Shop)
in-app-to-web shop retargeting campaigns (ads targeting users from your application to your Web Shop)

To create a Singular website link:

Log in to your Singular account.
Go to the Attribution Setup section and select Create Web Link.
In the Target (App) field, choose your web app related to Xsolla Web Shop.
In the Partner field, select your ad network partner.

Enter a landing page path if needed (optional).
Update UTM fields to capture campaign details (optional).
Click Generate Link.

A final destination URL for your Web Campaign will be generated based on your selection. Traffic this link for your Web Campaign.

For more detailed campaign tracking (granularity), you can add macros to the generated URL. Use the adding macros guide to append macro parameters for the Singular Web SDK, enabling capture of campaign-level data. Be sure not to override any existing parameters on the link.

Instructions may update based on the specific ad network selected. Always follow any ad network-specific notes displayed in the Web URL builder.

For more details, refer to the Singular Website Links guide.

How to add Web/ Web Shop events in Singular

Log in to your Singular account.
Go to Settings > Events section.
Add the events captured by your Web SDK:
1. Select App specific Events.
2. Select your application.
3. In the Cohort Events section, add the event name that will appear in your reports.
4. In the Event maps to the following field, select the SDK event.
5. Click Save.

Refer to the How to Track In-App Events instruction for more information.

Revenue events are automatically included in the Revenue metric for Singular reports. You don’t need to add a custom event unless you want to track the count of revenue events separately.

How to get Web Shop ad campaigns' performance report in Singular

To generate a report for web-to-web and in-app-to-web ad campaigns:

Log in to your Singular account.
Go to the Reports > Insights section.
Configure your filters:
- Set your desired date range.
- Select the app you want to analyze.

Add dimensions to segment your data:
- Source
- Campaign Name
- additional dimensions as needed

Choose your web metrics:
- Web New Visitors
- Web Re-Engaged Visitors

Include cohort data:
- Revenue
- ROI
- any custom cohort events previously configured on the Settings > Events page

Click Run report in the top-right corner.

Establish a clear naming convention for your campaigns that distinguishes between web-to-web and in-app-to-web campaigns. This taxonomy makes reporting analysis significantly easier and ensures your team can quickly identify campaign types.

Refer to Reports FAQ to learn more.

You can configure mobile application integration to get advanced event analytics if you:

have a mobile application for Android/iOS
use Singular
use Web Shop solution to sell in-game items

The following event is available via the Xsolla and Singular S2S integration:

Event	Description
xsolla-billing-payment	Item purchase. The event parameters contain information about a purchase.

How it works

The integration includes a bidirectional data flow between Xsolla and Singular. Below is the system interaction scenario when a user makes a purchase.

  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

The user (player) signs up or logs in to the mobile application.
Your application sends an in-app event to Singular, for example, login, or any other event that includes the CUID.

To configure the CUID, refer to the Singular SDK documentation.

Singular sends a postback to Xsolla, which includes the CUID and other data about the user device.
The user logs into Web Shop using the CUID.
The user makes a purchase in Web Shop.
The purchase event is sent to the Xsolla server and matched with the data received from Singular.
Xsolla’s server sends an in-app event to Singular, which contains parameters required for mapping.

Singular attributes a new event, purchase, and revenue back to the media source that drove the user acquisition or the user re-engagement.

How to set up in Publisher Account

Open your project in the Publisher Account and go to the Integrations section.
Click the Singular pane.

In the Mobile app S2S integration pane, click Configure.
In the window that opens, make sure that the Enable this integration box is checked.
Provide the following data:
1. Singular SDK key.
2. Application ID, unique for each platform (Android/iOS). To add a platform, click Add application ID.
Click Save.
Enable the integration in Singular.

Once you save the settings, a green indicator will be displayed on the S2S integration pane.

To make changes to the connected integration:

Click the Singular pane.
In the window that opens, make the necessary changes.
Click Save.

How to set up in Singular

In Singular, you need to:

Get an SDK key.
Activate the integration with Xsolla.

Get SDK key

Log in to your Singular account.
Open the Developer Tools > SDK Integration section.
Go to the SDK Keys tab.
Click Show Keys.
Copy the value in the SDK Key field.

Activate integration with Xsolla

Log in to your Singular account.
Go to the Attribution Setup > Partner Configuration section.
Click Add Partner.
In the search bar, enter and select Xsolla.

In the window that opens, select an application for which you configure integration.
Click Next.
Make sure that in the Events Postbacks block, the Login event is selected.
Click Save.

Make sure you have set up the CUID:

The SetCustomerId method and your authentication event are implemented using the Singular SDK.
In your Xsolla Publisher Account, integration with Singular is configured.
In your Singular account, integration with Xsolla is activated.

If you have the Reject IAP without receipt option enabled for your application in Singular, contact your Singular Client Manager to enable or disable the Xsolla revenue events.

Event value structure

If you want to set up a specific event or if the current integration options don’t cover your needs, contact your Customer Success Manager or email to csm@xsolla.com.

Item purchase

When a user makes a purchase in Web Shop, Xsolla sends the xsolla-billing-payment event to Singular. The following purchase information is passed in the event parameters:

Parameter	Description
content_id	Single SKU or array of SKU in the purchase.
quantity	Quantity of the item with corresponding SKU (one or an array).
revenue	Purchase amount. Discounts are included. Before taxes and fees.
currency	Purchase currency.

Additional data

In addition to parameters passed in the xsolla-billing-payment event, Xsolla sends the following data:

Parameter	Description
a	Singular SDK key.
p	Application platform. Example: iOS.
ip	Public IP address of the user device.
ve	Operating system version of the user device.
ma	Brand of the user device. Example: Apple.
mo	Model of the user device. Example: iPhone 4S.
lc	Locale of the user device in `^[a-z]{2}-[A-Z]{2}$` format. Example: `en_US`.
i	Application ID on the Singular side.
att_authorization_status	App Tracking Transparency (ATT) status code.
n	Event name. The maximum length is 32 characters.
is_revenue_event	Whether the event is linked to revenue.
amt	Currency amount.
cur	Currency. Three-letter currency code per ISO 4217.
custom_user_id	CUID.
partner	Partner — `xsolla`.
e	Other custom parameters (optional).

Thank you for your feedback!

We’ll review your message and use it to help us improve your experience.

Last updated: December 30, 2025

Found a typo or other text error? Select the text and press Ctrl+Enter.

Contents

Glossary
Integration flow
How it works
How to set up in Singular
How to set up in Publisher Account
How to run web and in-app ad campaigns for Web Shop
How to add Web/ Web Shop events in Singular
How to get Web Shop ad campaigns' performance report in Singular
How it works
How to set up in Publisher Account
How to set up in Singular
Get SDK key
Activate integration with Xsolla
Event value structure
Item purchase
Additional data

Your browser is not supported. Please try a different browser

Integration with Singular

Glossary

Singular

Singular Device ID (SDID)

Application ID

Lifetime Value (LTV)

Return on advertising spend (ROAS)

Web event

In-app event

User acquisition

Retargeting

Customer user ID (CUID)

Postback

SDK key

SDK secret

Integration flow

How it works

How to set up in Singular

How to set up in Publisher Account

How to run web and in-app ad campaigns for Web Shop

How to add Web/ Web Shop events in Singular

How to get Web Shop ad campaigns' performance report in Singular

How it works

How to set up in Publisher Account

How to set up in Singular

Get SDK key

Activate integration with Xsolla

Event value structure

Item purchase

Additional data