Apps (App Configuration) FAQ

The App Configuration page (Settings > Apps) is where you keep an up-to-date list of all the apps you are marketing. Singular needs this list to give you accurate analytics reports broken down by app.



What happens if I use the same app site for multiple platforms?

If you use the same app site for multiple platforms for an app, the app name will be the same in the reports and have the same settings. We strongly recommend using a different bundle ID for each app site.

However, if you do have the same app site for multiple platforms, you can distinguish between them in the reports using Campaign URL if you use different tracking links for each platform. In user-level data, you can distinguish between your apps with the app_version value.

What do I do if I'm marketing a web property/landing page, not a mobile app?

If you are marketing a website, online store, landing page, etc., you still need to add it in the Apps page:

  1. In the Apps page, click Add New App.
  2. For the platform, select "web."
  3. Enter the URL of the page or the primary domain of the website.


The Basics

What is the App Configuration page?

The App Configuration page is where you keep an up-to-date list of all the apps you are marketing. Singular needs this list to give you accurate analytics reports broken down by app.

Why does the app name matter?

Singular uses the app name to map stats from your ad network to the right app so we can give you your stats broken down by app.

If the app name in Singular doesn't match the app name as it appears in ad network data, Singular has other ways to try to map the data to the right app - but it's best to avoid the problem.

For more information, see the Unmapped Data FAQ.

What's an app site and how is it different from an app?

In Singular terminology, an app is an app title as the end-users know it, such as "Google" or "Instagram."

An app site is a version of the app that is specific to a platform, such as iOS or Android. It's called an app site because (when it goes live) it has a URL in the platform's app store.

An app often includes multiple app sites - one for each platform in which the app is available. For example, here is one app defined with two app sites:


What is a Store URL?

The store URL is where users go to download the app in a specific app store, such as the Apple App Store or Google Play. For example:
What is a Bundle Identifier?

The bundle identifier is an internal identifier used by the app developers, e.g., "com.myapp". If the app is not live yet in a specific platform's app store, you can still add an app site for it and define it for the time being by the app's internal bundle identifier.

What are test apps and live apps?

Note: This premium feature is only available to Enterprise customers.

For Enterprise clients, the Apps page is divided into two tabs - Live Apps and Test Apps. When you add an app or an app site, you can first choose the tab in which you want to add it.

Use the tabs to keep track of which apps are live and being marketed and which are not live yet.

Test apps will not be included in drop-down lists or filters anywhere in the Singular platform. In addition, partner configuration settings for these apps will not be editable and will show up in the Partner Configuration page as "Unavailable."

What does the red/green dot next to the app site mean?

Green app sites are live in the platform's app store.

Red app sites are not live yet.

What does the Refresh Apps button do?

Note: This section applies only to customers of Singular's attribution service.

Click this button to have Singular check recent SDK events for new apps and add them to the list in the Apps page.

Tip: If you are a customer of Singular's attribution service, Singular refreshes your app list every 2 hours by checking your SDK events for new apps. So whenever you open the Apps page, the app list you see is mostly up to date. But if you want to make sure the list includes apps that were activated within the last 2 hours, click Refresh Apps to force an extra check right now.

Adding Apps

How do apps get added to the list?

New apps are added to the list in two ways:

  1. Automatically: When your tracker (either the Singular tracker or a third-party MMP) has data about this app including at least one install or event. Singular checks if the app is live in the app store, and if so, it is added to the page.
  2. Manually: When you click Add New App or Add Site and enter the app details.
How can I add an app to the list manually?

To add an app manually:

  1. In the Singular platform, go to Settings > Apps Configuration.
  2. Click Add New App.


  3. In the form that appears, you have space to enter an app name and then enter the details of a specific app site.

    First, enter the app name. Make sure to enter the name exactly as it appears in the network reports. Pay attention to uppercase and lowercase letters, spaces, full words vs. acronyms, etc. If Singular can't recognize the app name in network reports because it's a little different, you may get "unmapped data" in your analytics reports.


  4. Now enter the details of the first app site. For OS, select one of the options.


  5. Identify the app site either by Store URL vs. Bundle ID:

    • If the app is live in the app store, select Store URL and paste in the URL of the app in the app store.


    • If the app is not live yet, select Bundle ID and enter the app's internal bundle identifier, e.g., com.appname.


      Tip: If you've submitted the app for review to the Apple App Store, you already have a Store URL, even if it's not live yet. We recommend adding the Store URL in the Site Public ID input box. This way, Singular will be able to use it once the app goes live.


  6. Click Save.
  7. If the app appears in multiple platforms and app stores, select Add Site. Add another app site for each store.

Why should I add my Android app and my iOS app as "app sites" under the same app?


By keeping all versions of the same app for different platforms together, you help Singular understand ad network data and provide reports that can be broken down by app, platform, or both app and platform.

In addition, the Apps page doesn't let you add two separate apps with the same name. So if you try to add each version as a separate app, you would have to give it a different name, which may cause missing data and other issues in your reporting (because Singular may not be able to map the app's data to the correct app). For more information, see the Unmapped Data FAQ.

How can I add an app that is not live in the app store yet?

You can do so by identifying the app by a "Bundle ID".

To add an app before it's live in the app store:

  1. In the Apps page, click Add New App and enter the app name (note: if you've already created another version of the app in the Apps page, add the new one as a new app site rather than a whole new app).
  2. Select the appropriate platform.
  3. Under Add an app using, select Bundle ID and enter the app's bundle ID. This is the internal identifier used by the app developers.


  4. For iOS apps: If you've already submitted the app to the App Store, you would have received the app's store URL (even though the app is not live yet in that URL). Enter it under Site Public ID. This will help Singular start mapping data to your app correctly.


I added an app before it was live in the app store - how do I update it after it's gone live?

You don't have to - Singular updates the app status automatically for you (for iOS and Android apps). We go over your apps twice a day and check (using the bundle ID) if any apps have gone live in the Apple App Store or Google Play.

How do I move a test app to live or vice versa?

If an app site was created in Live Apps automatically, but you don't want to see it in the drop-down lists and report filters in Singular, you can move it to Test Apps.

If you've set up an app site in Test Apps, you can move it to Live when it's ready.

To move an app site between the tabs, click the menu icon in the top right corner and click Move to Test or Move to Live.


Configuring Your App for Attribution Tracking with Singular

Note: This section applies only to customers of Singular's attribution service.

What settings do I need to configure for the app before I can run campaigns with Singular?

After you've integrated the Singular SDK into your app (according to the instructions in How to Get Started with Singular Attribution), several new settings become available for the app in the App Configuration page.

To see the new settings, make sure the SDK is sending events to Singular, and then go to the app and click the Advanced Settings toggle.

The settings are:

  • Destination URLs
  • Uninstall tracking
  • Deep link URLs
  • iOS Universal App Links
What are Destination URLs and how do I configure them?

You can set up one or more alternative destinations for tracking links in addition to the app's store URL. This way, when you create tracking links for the app, you will be able to select these destinations as targets.

This is useful, for example, when you have custom landing pages or you use an app store A/B testing solution.

To create a new destination URL:

  1. Select the app and then select the app site you want to configure.
  2. Click on the + sign next to the Destination URLs and type your new destination URL.
  3. Click Save.
How do I configure uninstall tracking?

If you have set up the Singular SDK to track uninstalls, you have acquired special credentials that you need to input in the Apps page under Uninstall Tracking.

These credentials enable Singular to track app uninstalls for you.

For more information, see Getting Started with iOS Uninstall Tracking and Getting Started with Android Uninstall Tracking.

What is the "inactivity window"?

The inactivity window is a setting that determines how long a user has to be inactive before they are ineligible for re-engagement attribution. For more information, see What is re-engagement? and How long does a user have to be inactive before a new session counts as a re-engagement?

What is the "minimum session interval"?

The minimum session interval is the minimum time between sessions, which Singular will process sessions received by an app. Values of 5 minutes to 24 hours are supported, and the default value is 12 hours. This mechanism limits the number of repeat sessions that are processed in Singular. For example, if an app has a “Minimum Session Interval” of 1 hour, the behavior is as follows:

Additionally, sessions that trigger core functionality are exempted from this feature, such as:

  • Deep link sessions, deferred deep link, and short link resolution
  • Install sessions
  • Sessions that are eligible for re-engagement from the configured inactivity window
  • Updates to custom user ID or global properties
  • SDK Testing Console
  • SKAdNetwork conversion model updates

The “Minimum Session Interval” does not impact Singular retention reporting. Singular retention is calculated using a rolling 24 hour period (see Retention FAQ), therefore a user’s retention will be logged, as long at least one session is processed during each 24 hour period.

As of May 8th, 2023:

  • All existing integrated apps have no change in behavior and have a minimum session interval of 0 (off).
  • All newly added and integrated apps will have a default minimum session interval of 12 hours. The interval value can be modified for each app on your Apps settings page.

Using Mapping Keys

Note: This beta feature is not yet available to all customers. If you are interested in trying it out, contact your Customer Success Manager.

What are mapping keys?

A mapping key is a unique code, typically shorter and simpler than the app name, that you can define for an app site in the Apps Configuration page and also insert it into campaign names in your ad network. This way, when Singular reads the data for a campaign from the ad network report, Singular can associate the campaign with the correct app and ensure that your campaign data is processed and included in your reports.

Why is it important for Singular to map each campaign to an app?

When pulling data from ad networks, Singular needs to associate each advertising campaign with the app it belongs to and the app’s platform (Android, iOS, etc.) to provide accurate marketing metrics for each of your apps.

Without knowing the app and platform, Singular cannot process the campaign data, and the campaign will not show up in your reports.

In some cases, the network provides the App Site Public ID or the app name + platform as fields in the network reports, which solves the problem.

In many other cases, Singular can derive the app and platform from the name of the campaign, by going over the list of apps in your account and trying to find an app name and a platform inside the campaign name. This is why it is important for the app name in Singular to match the app name as it appears in campaign names in your ad network reports.


When is it necessary to use mapping keys?

As a rule, we recommend making sure your app's name in Singular matches the app name that's defined in your ad network and appears in your campaign names. This is the easiest way to make sure your campaigns are mapped correctly to your app in Singular.  If the names don't match, you should usually either edit the app name in Singular or work with your ad network to change the campaign name on the network side.

However, there are some cases in which it’s difficult to make the names match on all platforms. For example:

  • The campaign name is in English while the app in Singular is in another alphabet, such as Chinese or Korean.
  • An app has slightly different names in the Apple App Store and Google Play Store, and the campaign names differ accordingly.

In such cases, you can use mapping keys to make sure your campaigns are mapped.

How do I add a mapping key?

To add a mapping key:

  1. In the Apps Configuration page, find the app that has unmapped campaigns.
  2. Open the appropriate app site to edit it.
  3. Enter a string in the Mapping Key field.
  4. Working with your ad network, add the same string to the name of the unmapped campaign. Make sure you separate the mapping key from the rest of the campaign name with a standard separator, such as a space, an underline, or a punctuation mark.


For example, say you have an app called “장난감 곰” and a campaign name for it that is called “Teddy Bear iOS FR DE SP.”  To enable Singular to map the campaign to the app:

  1. Edit the app site in Singular and add a mapping key, e.g., "TB111".
  2. Working with your ad network, change the name of the campaign to “Teddy Bear iOS FR DE SP TB111”.

Singular will now recognize the campaign as being associated with the app site.

How should I choose the mapping key string? Are there limitations on the key length?


  • The key has to contain at least 4 characters.
  • The key must be unique to the app site (don’t give another app site the same key).
  • In the campaign name, separate the key from the rest of the name using a standard separator such as a space, an underline, or a punctuation mark.
  • Keywords can't contain potential delimiters or they won't be identified, e.g. _, ?, !, %, &, $, |, /, +, -, [, ], (, ) as well as "*", "_", ".", and ",". For example, a keyword named "MT_Android" won't identify a campaign named "MT_Android_1".

Additional recommendations:

  • To avoid mistakes later, don’t use a key that matches another app’s name. For example, if you have the apps “Jewel Rush” and “Jewel Rush 2”, don’t use the key “jewelrush.”
  • We recommend using English letters and numbers only.