Unmapped Data and Mapping Keys FAQ

Learn about what "unmapped data" is, why it happens, and how you can view it in your reports.

To learn about all your reporting options and settings, see the Reports FAQ.


General Questions

What is unmapped data?

Unmapped data is data that is not mapped to an app and platform.

When Singular pulls data from ad networks, it tries to map every piece of campaign or ad monetization data to the app and platform it belongs to. The goal is for you to be able to view and analyze the performance of each of your apps.

By default, unmapped data is not included in your report. To show this data, check the "Show unmapped data" checkbox. Note that ETL and API responses contain unmapped data by default.

Why does unmapped data occur?

Many networks do include the app and platform information in their reports, or even better - the App ID (site_public_id), which encapsulates both the app and the platform in the most accurate way.

However, some networks do not provide these fields or provide them in a problematic way, e.g. the app name may be spelled differently than in Singular. In these cases, Singular tries to map the data to the app and platform on its own in several ways.

If all the mapping efforts fail, you get unmapped data. That's when you will see App = N/A and/or Platform = Unknown in your data.

How does Singular auto-map data to an app and platform?

When a network doesn’t provide the App ID or the app/network, Singular tries several methods of automatic mapping, including:

For example:


Why are there discrepancies in my ETL/API data?

Starting soon, unmapped data is included by default in ETL and API pulls. Because of the recent change, you might see more data than you're used to.

To review or remove unmapped data, filter data with App Name = "N/A" and Platform = "Unknown".

I have unmapped data - what do I do?
  1. As a best practice, we encourage you to talk to your network about providing the App ID (site_public_id) in its reports.
  2. It is also good practice to keep your app name consistent:
    • When you set up a campaign with an ad network, make sure to name your app the same way you named it in Singular (in the App Configuration page) - in the same language, and with the same spelling, spacing, etc.
    • Then, make sure your campaign name includes the app name correctly (and also the platform). This way, Singular will be able to map the campaign data to the app.

      Note: Beware of using different languages. For example, if you set up your app in Singular in Japanese, but then work with an ad network that only accepts app/campaign names in English, Singular will not be able to auto-map the data to the app.

  3. Singular also provides the option to add mapping keys to your app sites. A mapping key is a unique code, typically shorter and simpler than the app name, that you can define for an app site in Singular and then add it to your campaign names. Learn more about mapping keys.

Using Mapping Keys

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 into campaign names in your ad network.

This way, when Singular reads the data for a campaign (regular or AdMon) 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? (Regular and AdMon campaigns)

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.
  5. Only for AdMon campaigns, add the same string to the Instance ID field in your ad network or mediation platform.


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. Mapping keys that include a separator aren't supported (e.g. "Jewel_Rush" won't be detected)

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.