Menu

Singular Integration

Applicable to SA 3.0.5 and above.

This feature is controlled by license. Please contact your account manager if you require it.

Overview

This document describes how to import Singular user-level attribution data into Sensors Analytics. Singular integration uses Internal BI Postbacks for real-time callbacks. After Sensors Analytics receives data pushed by Singular, the data can be written to the event table according to the configuration and, when conditions are met, used to update the overseas attribution table.

Singular interface Data granularity API type Data update frequency
Internal BI Postbacks User level Singular server-side real-time callback Real time

Notes:

  1. Before using this feature, make sure your Singular account has permission to configure Internal BI Postbacks.

  2. Singular callback fields and attribution results are subject to the actual content pushed by Singular. If Singular does not return a field, Sensors Analytics will not complete the field automatically.

  3. Data written to the event table counts toward data volume consumption. We recommend configuring only the in-app events that are actually needed for analysis.

Singular Raw Data Integration

You can use Singular Internal BI Postbacks to send Singular Install activation events and in-app events to Sensors Analytics in real time. After integration, Sensors Analytics supports the following capabilities:

  • Write Singular callback Install activation events to the Sensors Analytics event table for analyzing Singular-attributed activation data.

  • Write configured Singular in-app events to the Sensors Analytics event table for analyzing subsequent conversion performance under different attribution sources.

  • Record Install detail data that contains the Sensors Analytics unique user ID in the overseas attribution table, so that you can query overseas channel sources associated with user behavior reported to Sensors Analytics.

  • View default message field mappings and add Singular callback fields as needed for analysis as event properties and third-party attribution properties.

Integration Process

If this is your first time using Singular Integration, complete the following configuration steps in order:

  1. Integrate and configure the Singular SDK and Sensors Analytics SDK

    Integrate both the Singular SDK and Sensors Analytics SDK in your app. On the client side, use the Sensors Analytics SDK to obtain the Sensors Analytics user identifier, and pass this identifier to the Singular SDK. This allows Singular to include Sensors Analytics user identifier when it later sends Install or in-app event callbacks.

  2. Configure Internal BI Postback in the Singular platform

    Copy the data receiving URL generated on the Singular Integration configuration page in Sensors Analytics, paste it into the Singular console, and configure the event types that need to be pushed.

  3. Enable data receiving and event writing in Sensors Analytics, and add additional custom message fields as needed

    In Sensors Analytics, enable the Singular data receiving switch, and configure event writing rules and message field mappings as needed. After the configuration is complete, Sensors Analytics receives, parses, and writes Singular callback data according to the configured rules.

After these configurations are complete, you can query Singular integration events in the Sensors Analytics model, and you can also query overseas channel attribution results associated with events collected by Sensors Analytics.

Client SDK Settings

To associate Singular callback data with user behavior in Sensors Analytics at the user level, you need to pass the Sensors Analytics user identifier to the Singular SDK.

Sensors Analytics identifies users by using the Sensors Analytics unique user ID ($distinct_id) and user login identifier ($is_login) in Singular callbacks. If callback data does not contain the Sensors Analytics unique user ID, the system cannot use the Install detail data to update the overseas attribution table.

During client-side integration, confirm the following:

  • The app has correctly integrated the Singular SDK and Sensors Analytics SDK.

  • The client can obtain the Sensors Analytics unique user ID and login identifier.

  • The Sensors Analytics user identifier has been passed to the Singular SDK as agreed.

  • Singular callback data can include the above Sensors Analytics user identification information.

For detailed configuration procedures, see Third-party Data Integration Guide (Android) and Third-party Data Integration Guide (iOS).

Configure Singular Internal BI Postback

Log in to the Singular console with an account that has configuration permissions, and complete the Internal BI Postback configuration.

Configure Singular callbacks as follows:

  1. Log in to your Singular account.

  2. Go to Attribution Settings > Partner Configuration.

  3. Click Add Partner.

  4. Search for and select Sensors Data.

  5. Copy the data receiving URL from the Singular integration configuration page in Sensors Analytics and enter it as the Postback callback URL.

  6. Select the event types to push as needed.

  7. Save and enable the configuration.

Click to enlarge

Notes:

  1. The data receiving URL is generated by Sensors Analytics by project. Different Sensors Analytics projects have different data receiving URLs. Do not mix them.

  2. If you add custom receiving fields in Sensors Analytics, you must also confirm that the Singular console supports and correctly configures the corresponding callback parameters. Otherwise, Sensors Analytics cannot receive the fields.

Configure Singular Integration in Sensors Analytics

Before configuring Sensors Analytics, confirm that the client SDK settings and Singular console configuration described above have been completed. Otherwise, the following settings will not take effect.

Feature entry:

Channel Tracking > Third-party Data Integration > Attribution > Singular

Click Integration Configuration to open the configuration page.

Enable the Data Receiving Switch

The data receiving configuration controls whether data pushed by Singular is received.

  • Data receiving switch: Disabled by default. After it is enabled, Sensors Analytics can receive Singular real-time callback data. After it is disabled, Sensors Analytics no longer receives Singular real-time callback data and no longer updates attribution records.

  • Data receiving URL: The callback URL generated by the system. Enter this URL as the Postback callback URL in Singular.

  • User identification scheme: Sensors Analytics identifies users by using the Sensors Analytics unique user ID and login identifier in Singular callbacks.

The data receiving switch takes effect in real time. When changing its status, confirm that the configuration is correct to avoid affecting real-time callback results.

The integration status of the Singular integration changes to Integrated only after the activation event (mmp_singular_install) has been integrated and data has been successfully written to the attribution table.

Enable the Event Writing Switch

The event writing configuration controls whether other in-app events returned by Singular are written to the Sensors Analytics event table.

Writing rules:

  • Install activation events are written to the event table by default. The event name is mmp_singular_install, and no additional configuration is required in target writing events.

  • Other in-app events must first be configured in target writing events.

  • After other in-app events are written to Sensors Analytics, the event name is automatically prefixed with mmp_singular_. For example, if the configured event name is purchase, the event name written to Sensors Analytics is mmp_singular_purchase.

Notes:

  1. Writing Singular callback events consumes event volume in the Sensors Analytics package.

  2. Configure target writing events according to the event names actually returned by Singular. If an event name is entered incorrectly, the corresponding event cannot be written to the event table.

  3. Changes to the event writing configuration take effect in real time. Proceed with caution.

Configure Message Fields

Message field configuration is used to view default receiving fields. You can also configure custom receiving fields based on business needs.

Terms:

  • Singular field: The field name in Singular callback data.

  • Sensors Analytics custom property: The event property used in the event table to receive Singular fields. It usually starts with mmp_singular_.

  • Sensors Analytics third-party attribution property: The property used to record third-party attribution results in a unified manner. It usually starts with mmp_. It is actually a virtual property and can be used to query overseas channel sources associated with events reported to Sensors Analytics.

  • Sensors Analytics third-party first-touch channel property: When a user is first attributed to a media channel, this preset user property records the MMP channel attribution result. It is updated for the first time by using profile setonce().

Default Receiving Fields

Sensors Analytics supports writing the following Singular message fields to the event table according to preset rules by default, and synchronously records them in third-party attribution properties. Default receiving fields can only be viewed and cannot be modified.

Singular field Sensors Analytics custom property Sensors Analytics third-party attribution property Sensors Analytics third-party first-touch channel property Notes
app_name mmp_singular_app_name mmp_app_name    
long_name mmp_singular_long_name mmp_bundle_id    
public_id mmp_singular_public_id mmp_public_id    
network_name mmp_singular_network_name mmp_media_source mmp_first_media_source  
idfa mmp_singular_idfa mmp_idfa    
aifa mmp_singular_aifa mmp_aifa    
platform mmp_singular_platform mmp_platform    
attribution_country mmp_singular_attribution_country mmp_attribution_country    
attribution_city mmp_singular_attribution_city mmp_attribution_city    
attribution_state mmp_singular_attribution_state mmp_attribution_state    
event_name mmp_singular_event_name mmp_event_name    
created_at_milli mmp_singular_created_at_milli mmp_start_time    
campaign_name mmp_singular_campaign_name mmp_campaign_name mmp_first_campaign  
campaign_id mmp_singular_campaign_id mmp_campaign_id mmp_first_campaign_id  
subcampaign_name mmp_singular_subcampaign_name mmp_subcampaign_name mmp_first_adgroup  
subcampaign_id mmp_singular_subcampaign_id mmp_subcampaign_id mmp_first_adgroup_id  
creative_name mmp_singular_creative_name mmp_ad_name mmp_first_ad  
creative_id mmp_singular_creative_id mmp_ad_id mmp_first_ad_id  

Custom Receiving Fields

If the default receiving fields do not meet your analysis needs, you can add custom receiving fields as needed. Add custom receiving fields strictly according to the Singular supported macro parameters list, and configure the corresponding Sensors Analytics property that receives each field.

Based on the custom property name you enter, Sensors Analytics automatically adds the mmp_singular_ prefix to distinguish the property as a Singular event-specific property. It also automatically creates a Sensors Analytics third-party attribution property name with the mmp_ prefix to receive third-party channel attribution results in a unified manner.

After custom receiving fields are configured, the data receiving URL automatically appends the corresponding parameters. Also enter the updated Postback URL in the Singular console. Otherwise, Sensors Analytics cannot receive the fields.

For example, if you want callback events to include APP_NAME, enter APP_NAME in the custom receiving field, enter app_name in Sensors Analytics custom property name, and click Save to add the custom receiving field.

This means that when Sensors Analytics receives the APP_NAME message field returned by Singular, it automatically creates and writes the custom property mmp_singular_app_name while writing the event. If the received event is an activation event (mmp_singular_install), it also automatically creates and writes the virtual property mmp_app_name. Later, when the same user reports behavior events through the Sensors Analytics SDK, you can query the associated value of mmp_app_name.

Notes:

  1. Custom fields are written to Sensors Analytics only after Singular actually returns them.

  2. After custom message fields are edited and saved, the mapping rules take effect in real time.

  3. Avoid frequently modifying field mappings that have already been used for analysis, as this may affect historical data and subsequent query definitions.

Data Storage Rules

User Identification Rules

Based on the Sensors Analytics user identification fields configured in the client SDK, Sensors Analytics looks for user identifiers in the returned mmp_singular_install data by default:

Check whether the global_properties field contains the Sensors Analytics unique user ID ($distinct_id) and the Sensors Analytics user login identifier ($is_login), which are the user identifier fields passed through from Sensors Analytics to Singular.

If a valid user identifier can be obtained, the user is recorded based on the Sensors Analytics user identifier.

If a valid Sensors Analytics user identifier cannot be obtained, the data is discarded and not ingested.

Note

If your Sensors Analytics system uses special user identification fields and users cannot be accurately identified by using the above $distinct_id and $is_login, please contact your business manager. We will make adjustments during delivery to adapt to your business situation.

Event Storage Rules

As long as the data receiving switch is enabled, Sensors Analytics writes received Install activation events to the event table by default. If you configure other in-app events in the event writing configuration, the system also writes them according to the configuration.

Event data storage rules:

  • Written event data is associated with the corresponding Sensors Analytics user according to the user identification rules.

  • The created_at_milli in Singular callback data is used as the event time.

  • Install activation events are written as mmp_singular_install by default.

  • Other in-app events are written as mmp_singular_{event name}.

  • Singular callback fields are written to the event table as mmp_singular_ properties.

  • Third-party attribution fields are recorded as mmp_ properties for unified analysis.

User Property Storage Rules

When the system receives a Singular callback Install event and identifies the corresponding user, it updates user-related properties according to the rules. If the user has not previously recorded first-touch third-party channel properties, the system performs the first update based on the attribution fields returned by Singular.

First-touch third-party channel properties are used to record source information when a user is first attributed to a media channel, and can later be used to analyze conversion performance of users from different first-touch channel sources.

Sensors Analytics first-touch third-party channel property (preset user property) Singular message field name Notes
mmp_first_media_source network_name Media channel
mmp_first_campaign campaign_name Campaign name
mmp_first_campaign_id campaign_id Campaign ID
mmp_first_adgroup subcampaign_name Ad group
mmp_first_adgroup_id subcampaign_id Ad group ID
mmp_first_ad creative_name Ad name
mmp_first_ad_id creative_id Ad ID

Third-party Attribution Table Update Rules

Sensors Analytics supports saving attribution results from third-party attribution platforms and associating user behavior reported to Sensors Analytics with third-party attribution results through mapped Sensors Analytics user identifiers.

Singular third-party attribution table update rules:

  • The system updates the overseas attribution table if and only if it receives Install detail data that contains the Sensors Analytics unique user ID.

  • If the user has no previous attribution record, the system adds an attribution record.

  • If the user already has an attribution record, the system inserts or updates the attribution record according to the Install event time and maintains the start and end times of the corresponding attribution record.

  • If the Install detail data does not contain the Sensors Analytics unique user ID, the system does not use the data to update the overseas attribution table.

Data Query Methods

After completing the configuration above, you can query integrated Singular events in Event Analysis, and you can also query third-party attribution channel results associated with events reported by Sensors Analytics.

Query Integrated Singular Events

Using the default integrated Install event as an example:

  1. Go to Event Analysis.

  2. Select the event mmp_singular_install.

  3. Select Singular third-party attribution properties in the group-by items, such as mmp_media_source and mmp_campaign_name.

  4. View Singular activation data under different media sources or campaigns.

If you have configured other in-app events, you can also select mmp_singular_{event name} for querying. Make sure the queried event name is consistent with the event writing configuration.

Query Integrated Singular Users

You can use third-party first-touch channel properties to analyze the first-touch channel sources of Singular integrated users.

Using the default integrated Install event as an example:

  1. Go to Event Analysis.

  2. Select the event mmp_singular_install.

  3. Select third-party first-touch channel properties in the group-by items.

  4. View user scale and conversion performance under different first-touch channel sources.

Query Third-party Attribution Channel Results Associated with Events Reported by Sensors Analytics

If you want to analyze the relationship between user behavior collected by the Sensors Analytics SDK and Singular attribution sources, you can query events reported by Sensors Analytics in Event Analysis and group them by third-party attribution properties.

For example, when analyzing an in-app conversion event:

  1. Go to Event Analysis.

  2. Select the target event reported by the Sensors Analytics SDK.

  3. Select third-party attribution properties in the group-by items, such as mmp_media_source, mmp_campaign_name, mmp_campaign_id, mmp_subcampaign_name, and mmp_ad_name.

  4. View conversion performance under different media sources, campaigns, subcampaigns, or creatives.

Common Singular analysis fields include:

mmp_media_source, mmp_campaign_name, mmp_campaign_id, mmp_subcampaign_name, mmp_subcampaign_id, mmp_ad_name, mmp_ad_id, mmp_platform, mmp_attribution_country, mmp_attribution_city, and mmp_start_time.

Permissions

Permission point Description
View Singular Can view the Singular integration solution
Configure Singular Can configure Singular data integration

Special Notes and Limitations

  • After the data receiving switch is disabled, Sensors Analytics no longer receives Singular real-time callback data and no longer updates attribution records.

  • After the event writing switch is disabled, Singular in-app events other than Install activation events are no longer written to the event table.

  • Custom receiving fields must be supported by corresponding callback parameters in the Singular console. Otherwise, Sensors Analytics cannot receive the fields.

  • Singular callback fields and attribution results are subject to the actual content pushed by Singular.

  • Data written to the event table counts toward data volume consumption. We recommend configuring only the in-app events that are actually needed for analysis.

This document is a Sensors Data product usage guide and does not contain merchantability-related terms. The specific enterprise product purchase and technical service content are subject to the commercial purchase contract.

Previous
AppsFlyer User Data Integration
Next
Segments
Last modified: 2026-07-24