Apps (App Configuration) FAQ

Learn how to use the App Configuration page (Settings > Apps) to make sure Singular has an up-to-date list of all the apps you are marketing.



General and Terminology Questions

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.

How do apps get added to the list automatically?

New apps are added to the list automatically in two ways:

  1. When the same app name appears in data pulled from your ad network and in data pulled from your attribution tracker.
    • The app is added as a live app.
    • Note that apps are only added this way if there is tracker data for them. Appearing in the ad network's report is not enough.
  2. [For customers of Singular's attribution service] When you integrate the Singular SDK into your app, test it, and send an event to Singular.
    • The new app is added as a test app.
    • Once the app has 1000 tracked installs, it is moved to the live category.
    • For information about implementing the SDK, see SDK Testing and Validation.
What do I do if an app hasn't been added to the list automatically?

[For customers of Singular's attribution service]

If you've integrated the Singular SDK in your app and it is sending events to Singular, the app should appear in the list on the page. Try clicking the Refresh Apps button. You can also add the app manually.

What does the "Refresh Apps" button do?

[For 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.

What are "test apps" and "live apps"?

The Apps page is divided into two tabs - Live Apps and Test Apps. 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's the difference between an "app" and an "app site"?

In Singular, 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. An app site has a URL in the platform's app store.

An app typically 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:

Adding and Editing Apps

How can I add apps to the list manually?

To add an app manually:

  1. In the Singular platform, go to Settings > Apps Configuration.
  2. Select the Live Apps or Test Apps tab.
  3. Click Add New App.

    Add New App

  4. At the top of the form, replace the text “New App” with the app name. Enter the name exactly as it appears in the network reports. Pay attention to uppercase and lowercase letters, spaces, full words vs. acronyms, etc.
  5. Enter the details of the first app site:
    • If the app has already been released to the app store, select Store URL and paste in the URL of the app in the app store.
    • If the app is not live in the app store yet, select Bundle Identifier and enter the app's internal bundle identifier, e.g. com.appname.
    • Select the platform for the app site: “iOS”, “Android”, “Desktop”, etc. Note that the "iOS" option is for apps that run on both iPhones and iPads. If your app is developed only for iPhones or only for iPads, select "iPhone" or "iPad".
    • Optionally, you can enter a Site Nickname to help you identify the app site in the list.
    • Select Save or Save & Add Another.
  6. If the app appears in multiple platforms and app stores, add another app site for each store.

    You can select Add Site at the top of the form to add another site.

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.

How do I edit an existing app or app site?

Edit App

  • To add an app site to an existing app, click the app’s Add Site link.
  • To delete an app (including all of its app sites), click the app’s trashcan icon.
  • To delete only one app site, hover over the app site and click the X icon.
  • To move an app site to another app, hover over the app site, click the move icon, and in the list that opens, choose the target app.

Tip: Often, your apps have multiple versions for different platforms - for example, iOS and Android versions. In Singular, each version is defined as an app site, but you can group them together under the same app. Grouping versions together allows for:

  • Creating smart links: Links that automatically redirect your users to the right app store based on the device type
  • Smarter Reporting: Group your reportings by the app/game name.
How do I move a test app to live or vice versa?

If an app was created as a live app 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.

To move an app site from Live Apps to Test Apps:

  1. Find the app in the Live Apps tab.
  2. Hover over the app site and click the beaker

To move an app site from Test Apps to Live Apps:

  1. Find the app in the Test Apps tab.
  2. Hover over the app site and click the rocket icon.

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), make sure to configure the following settings in the Apps page:

  • Store URL: Redirects your customers to the right location to download your app.
  • (Optional) Destination URLs
  • (Optional) Uninstall tracking
  • (Optional) Deep link URLs
  • (Optional) iOS Universal App Links
What are "Destination URLs" and how do I configure them?

It is possible to set up one or more alternative destinations in addition to the app's store URL. Then, 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 will 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?

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.) in order 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 to 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 has to 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.

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.
Was this article helpful?