Custom Dimensions FAQ

Learn how to use custom dimensions to improve and enrich your reports.

For more about Singular reporting, see the Reports FAQ.


General Questions

What are custom dimensions?

Custom dimensions are new dimensions you can define in order to segment, aggregate, and structure your marketing analytics data in new ways to suit your specific needs. After you create custom dimensions, you can use them in your reports just like regular dimensions.

For example, if you have several User Acquisition Managers, each responsible for different ad networks, you can create a custom dimension called UA Manager, which is defined based on the ad network (e.g., if the Source is "Sponsorpay", the UA Manager is "Anna").

After you create the custom dimension, you can filter or aggregate your report data to learn about each individual UA manager’s performance.

Original report:


With custom dimensions:


What can I use custom dimensions for?

You can create any custom dimension you like within the technical limitations. Aside from the "UA Manager" example described above, here are some  examples of dimensions our customers have created for themselves:

  • Channel dimension: "Social", "Search", "Display", or "Retargeting"
  • Strategy dimension: “Branding", "Competitive", or "Other"
  • Incentivized dimension: "Non-Incent" vs "Incent"
  • Targeting dimension: "Females"/"Males" or "18-35"/"35+", etc.
  • Creative category: Categorize your creative assets by language, size, illustration style, seasonal theme, etc.
How are custom dimension values calculated?

Custom dimensions are defined based on the default, predefined dimensions. For example, if you have several User Acquisition Managers, each responsible for different ad networks, you can create a custom dimension called UA Manager, which is defined based on the ad network (e.g., if the Source is "Sponsorpay", the UA Manager is "Anna").

Custom dimensions often rely on having information embedded in the campaign name. For example, you can define a custom dimension as follows: “If the campaign name contains ‘incent’, apply the value ‘Incentivized Traffic’”.

To use custom dimensions this way, work with your network and attribution partners to ensure that the campaign names include the necessary strings.

Where can I use custom dimensions after I define them?
  • Reports page and Creative Reports: After creating custom dimensions, you can add them to your report query and view them in your reports, the same way you add predefined dimensions. The values of custom dimensions are calculated in real time when the report is run.
  • Reporting API: In the reporting API, you can add custom dimensions to your reports by passing their IDs in the dimensions parameter. To get a list of all your custom dimensions and their IDs, query the custom dimensions endpoint:
In the Custom Dimensions page, what's the difference between the Reports tab and the Creatives tab?

The Creatives tab is where you can add custom dimensions that are specific to creative reports. For example, you can create a custom dimension based on the Creative Name dimension. Any custom dimensions you add in this tab will be available only on the Creative Reports page.

Custom dimensions you add in the Reports tab are available both in the Reports page (campaign performance reports) and in the Creative Reports page.

Why do some dimensions have an orange calendar icon next to their name?


The calendar icon marks custom dimensions that are based on the Country or Creative Name fields. These are a newer feature and can only be applied to data starting on November 1, 2019.

If you run a report with these custom dimensions on a date range that includes older data, Singular will not be able to calculate the custom dimension values for the older data (see Reports FAQ: What does "N/A (Custom Dimensions Range)" mean?).

Creating Custom Dimensions

How do I create a new custom dimension?

To create a custom dimension, go to Settings > Custom Dimensions and click New Custom Dimension. Enter a name for the dimension and start defining the possible values.

For each possible value that the custom dimension can have, specify a condition for when this value should be picked. A condition consists of three parts:


You can also combine several conditions using AND/OR logical operators.

Optionally, you can define a default value for when no other value has been picked.

Tip: In the default value box, you can use the macro {source} to have the custom dimension default to the value of the Source dimension (see example below).


The following screenshot shows a custom dimension defined as follows:

  • The dimension name is "UA Manager".
  • Use the value "Anna" if the value of Source is "Facebook", "Sponsorpay", or "Vungle".
  • Use the value "Dan" if the value of Source is "Apple Search Ads" or "IronSource".
  • Otherwise, use the actual value of Source.


A report that includes the new dimension would look as follows:

Source UA Manager Installs Cost Revenue 14d
Sponsorpay Anna 10938 $39,910.62 $1,048.97
Apple Search Ads Dan 9221 $33,383.26 $1,426.19
AdWords AdWords 10516 $24,169.61 $1,951.99
Facebook Anna 9463 $21,064.18 $1,606.53
Mdotm Mdotm 7426 $42,754.12 $1,302.22
ironSource Dan 5531 $22,989.23 $1,343.81
How do I define more complex conditions (using "or" and "and")?

The Custom Dimensions page allows you to add up to 3 levels of "or" and "and" operators to conditions.

You can use this, for example, if you are defining a UA Manager dimension, and a UA Manager named Anna is responsible for MyApp1’s campaigns in the US and the UK, as well as for MyApp2’s performance in Germany and Spain.

In other words, you can tell Singular to apply the value “Anna” when:


To create this condition:

  1. To connect two rules with OR, hover over the first rule and select the OR link on the right.complex_rule_gif1.gif
  2. To add an AND operator, use the AND link below the condition.complex_rule_gif2.gif
  3. To add the highest level of "OR", use the OR link below the condition.complex_rule_gif3.gif
What is the difference between the OR link on the right and the OR link below the condition?

Both links are used to connect conditions with an OR operator, but they have different operator precedence:

  • The OR link on the right is always of lower precedence than an AND.
  • The OR link below is of higher precedence than an AND.

Example: Combining three conditions with OR and AND

  • Using the OR link on the right: the result is (Condition1 OR Condition2) AND (Condition3)or1.png
  • Using the OR link below: the result is (Condition1) OR (Condition2 AND Condition3)or2.png
When the system evaluates a custom dimension, which value is applied if more than one rule is true? What is the prioritization of rules?

When calculating a custom dimension, the reporting system goes down the list of values in order, and picks the first value whose rule is true. Any other values further down the list, whose rules may also be true, are ignored.

Therefore, remember the following guidelines:

  1. Pay attention to the order in which you define the values.
  2. When using substrings in campaign names in your conditions, use underscores, e.g., “_la_” and “_telaviv_”, to prevent confusion.

Example of a problematic rule definition:

Say you define a set of rules for a custom dimension based on city names embedded in the campaign name:

  • Use the value “Los Angeles” if Campaign or Tracker Name contains “la”.
  • Use the value “Tel Aviv” if Campaign or Tracker Name contains “telaviv”.

If the campaign name is “retargeting_telaviv”, the reporting system checks first if the condition for the value “Los Angeles” applies - and it does, because the campaign name contains the substring “la”. Therefore, the value of the custom dimension will be “Los Angeles”.


How many custom dimensions can I create?

You can create up to 5 custom dimensions with up to 70 conditions in total.

What dimensions can I use when defining a new custom dimension?

You can use any of the following dimensions: Account ID, App, Campaign or Tracker Name, Network Campaign Name, Network Sub Campaign Name, Platform, Retargeting, Source, Sub Ad Network, and Tracker Name.

  For more about the different dimensions, see the Reports FAQ.

Can I define custom dimensions based on other custom dimensions?

This is not supported at this point.

Can I use custom metrics with custom dimensions?

This is not supported at this point due to the strain on system resources.

Can I edit a custom dimension to change the order of the rules?

You cannot change the order of the rules in an existing custom dimension. If you want to add a new rule and give it a higher priority than some of the existing rules, you need to remove and re-add the rules in the desired order.

If the rules are complex, it may be easier to create a new rule and copy the content of each existing rule down to the next rule in line, thus leaving a duplicate rule in the right spot that you can overwrite  (see illustration).


Was this article helpful?