Skip to main content
Singular is a marketing analytics and mobile attribution platform. It collects campaign cost and performance data from your ad networks and attribution tracker and joins them, so you can measure spend, installs, revenue, and ROI across channels. This connector extracts aggregated data through the Singular Reporting API.

​
Configuring Singular as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Singular option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

You’ll need a Singular Reporting API key. In Singular, go to Developer Tools > API Keys and copy the reporting API key. The key carries the permissions of the user it belongs to, so use a user that can see all the apps and data you want to extract. The following configurations are available:
  • API Key: Your Singular Reporting API key.
  • Start Date: The first day to extract report data from. If left empty, the last 30 days are extracted on the first run.
  • Lookback Window (days): (Default: 7) Days before the last extracted day that are extracted again on every run. Ad networks restate cost for a few days and cohort metrics keep maturing, so Singular recommends 7 days for network data and your longest cohort period (e.g. 30) when you extract cohort metrics.
  • Apps: Only extract data for these app names. Leave empty for all apps.
  • Sources: Only extract data for these sources (ad networks), e.g. facebook, adwords. Leave empty for all sources.
  • Cohort Metrics: Cohort metric names (e.g. revenue, or the event IDs listed in the cohort_metrics table) added to the Tracker and Combined reports. Their values are stored in the extra_fields column.
  • Cohort Periods: Cohort periods for the cohort metrics, e.g. 1d, 7d, 30d, actual. Defaults to 7d, 30d, and actual.
  • SKAdNetwork Date Type: Whether the SKAN reports are based on the postback date (default) or on Singular’s estimated install date.
  • Max Concurrent Reports: (Default: 5) How many reports are requested from Singular at the same time. Singular allows up to 100 concurrent reports per account, shared with your other integrations.
Once you’re done, click Next.

​
2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data - which is good if, for example, you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data - which is good if, for example, you don’t want to have deleted data in your catalog.
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. Singular refreshes most data once a day, so a daily extraction is usually enough. Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
Streams and Fields

​
Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description.
Report streams request one report per day, up to yesterday (UTC). Each row is identified by report_date and row_id, a hash of the row’s dimension values, so days extracted again by the lookback window update the same rows. Ratio metrics such as CPI, CTR, ROI, and eCPM are not extracted because they are not meaningful once aggregated: calculate them from the underlying cost, install, and revenue columns.
The SKAN and Ad Monetization streams depend on Singular products that not every account has. When the account does not have them, the stream is skipped with a warning in the run log and its table is not updated.

​
Fields by stream

Daily campaign statistics pulled from your ad networks: cost, impressions, clicks and installs, by app, source, OS, country, account, campaign, sub-campaign and data connector.Primary key: report_date, row_id
  • report_date - Day the aggregated row refers to, used as the incremental replication key
  • row_id - Deterministic hash of report_date and the row’s dimension values, identifying the row
  • app - App name in Singular
  • source - Ad network or other media source the data comes from
  • os - Device operating system (e.g. iOS, Android)
  • platform - Device platform (e.g. iPhone, iPad); equals os when the source has no such breakdown
  • country_field - Country (ISO 3166 alpha-3 code)
  • adn_account_id - Ad network account identifier
  • adn_account_name - Ad network account name
  • adn_campaign_id - Campaign identifier as reported by the ad network
  • adn_campaign_name - Campaign name as reported by the ad network
  • adn_sub_campaign_id - Sub-campaign (ad set / ad group) identifier as reported by the ad network
  • adn_sub_campaign_name - Sub-campaign (ad set / ad group) name as reported by the ad network
  • data_connector_id - Identifier of the Singular data connector the network data was pulled with
  • data_connector_source_name - Source name of the data connector
  • data_connector_username - Account/username used by the data connector
  • adn_cost - Cost as reported by the ad network, converted to the account currency
  • adn_original_cost - Cost in the original currency reported by the ad network
  • adn_original_currency - Original currency of the cost reported by the ad network
  • adn_impressions - Impressions as reported by the ad network
  • adn_clicks - Clicks as reported by the ad network
  • adn_installs - Installs as reported by the ad network
  • extra_fields - Columns returned by Singular that have no column of their own, such as cohort metrics (JSON object)
Daily ad network statistics broken down by creative and asset. Singular’s alignment rows (“Missing Creative Data”) are excluded.Primary key: report_date, row_id
  • report_date - Day the aggregated row refers to, used as the incremental replication key
  • row_id - Deterministic hash of report_date and the row’s dimension values, identifying the row
  • app - App name in Singular
  • source - Ad network or other media source the data comes from
  • os - Device operating system (e.g. iOS, Android)
  • platform - Device platform (e.g. iPhone, iPad); equals os when the source has no such breakdown
  • adn_campaign_id - Campaign identifier as reported by the ad network
  • adn_campaign_name - Campaign name as reported by the ad network
  • creative_type - Creative type (e.g. image, video)
  • adn_creative_id - Creative identifier as reported by the ad network
  • adn_creative_name - Creative name as reported by the ad network
  • creative_url - URL of the creative
  • creative_image - Image of the creative
  • creative_text - Text of the creative
  • creative_width - Width of the creative
  • creative_height - Height of the creative
  • creative_is_video - Whether the creative is a video
  • asset_id - Identifier of the creative asset
  • asset_name - Name of the creative asset
  • adn_cost - Cost as reported by the ad network, converted to the account currency
  • adn_impressions - Impressions as reported by the ad network
  • adn_clicks - Clicks as reported by the ad network
  • adn_installs - Installs as reported by the ad network
  • extra_fields - Columns returned by Singular that have no column of their own, such as cohort metrics (JSON object)
Daily ad network statistics broken down by publisher, site and keyword.Primary key: report_date, row_id
  • report_date - Day the aggregated row refers to, used as the incremental replication key
  • row_id - Deterministic hash of report_date and the row’s dimension values, identifying the row
  • app - App name in Singular
  • source - Ad network or other media source the data comes from
  • os - Device operating system (e.g. iOS, Android)
  • platform - Device platform (e.g. iPhone, iPad); equals os when the source has no such breakdown
  • country_field - Country (ISO 3166 alpha-3 code)
  • adn_campaign_id - Campaign identifier as reported by the ad network
  • adn_campaign_name - Campaign name as reported by the ad network
  • keyword_id - Keyword identifier as reported by the ad network
  • keyword - Keyword as reported by the ad network
  • publisher_id - Publisher identifier as reported by the ad network
  • publisher_site_id - Publisher site/app identifier as reported by the ad network
  • publisher_site_name - Publisher site/app name as reported by the ad network
  • adn_cost - Cost as reported by the ad network, converted to the account currency
  • adn_impressions - Impressions as reported by the ad network
  • adn_clicks - Clicks as reported by the ad network
  • adn_installs - Installs as reported by the ad network
  • extra_fields - Columns returned by Singular that have no column of their own, such as cohort metrics (JSON object)
Daily attribution tracker statistics: impressions, clicks, installs, conversions, re-engagements and daily active users, plus the cohort metrics you configure.Primary key: report_date, row_id
  • report_date - Day the aggregated row refers to, used as the incremental replication key
  • row_id - Deterministic hash of report_date and the row’s dimension values, identifying the row
  • app - App name in Singular
  • source - Ad network or other media source the data comes from
  • os - Device operating system (e.g. iOS, Android)
  • platform - Device platform (e.g. iPhone, iPad); equals os when the source has no such breakdown
  • country_field - Country (ISO 3166 alpha-3 code)
  • tracker_campaign_id - Campaign identifier as reported by the attribution tracker
  • tracker_campaign_name - Campaign name as reported by the attribution tracker
  • tracker_impressions - Impressions as reported by the attribution tracker
  • tracker_clicks - Clicks as reported by the attribution tracker
  • tracker_installs - Installs attributed by the attribution tracker
  • tracker_conversions - Conversions (installs plus re-engagements) attributed by the tracker
  • tracker_reengagements - Re-engagements attributed by the attribution tracker
  • daily_active_users - Daily active users
  • extra_fields - Columns returned by Singular that have no column of their own, such as cohort metrics (JSON object)
Daily network and tracker data joined by Singular into the same rows, so cost and performance metrics can be analyzed together, plus the cohort metrics you configure.Primary key: report_date, row_id
  • report_date - Day the aggregated row refers to, used as the incremental replication key
  • row_id - Deterministic hash of report_date and the row’s dimension values, identifying the row
  • app - App name in Singular
  • source - Ad network or other media source the data comes from
  • os - Device operating system (e.g. iOS, Android)
  • platform - Device platform (e.g. iPhone, iPad); equals os when the source has no such breakdown
  • country_field - Country (ISO 3166 alpha-3 code)
  • adn_account_id - Ad network account identifier
  • adn_account_name - Ad network account name
  • unified_campaign_id - Campaign identifier after Singular’s joining of network and tracker data
  • unified_campaign_name - Campaign name after Singular’s joining of network and tracker data
  • sub_campaign_id - Sub-campaign identifier after Singular’s joining of network and tracker data
  • sub_campaign_name - Sub-campaign name after Singular’s joining of network and tracker data
  • adn_cost - Cost as reported by the ad network, converted to the account currency
  • adn_original_cost - Cost in the original currency reported by the ad network
  • adn_original_currency - Original currency of the cost reported by the ad network
  • custom_impressions - Impressions from the source Singular considers authoritative (network or tracker)
  • custom_clicks - Clicks from the source Singular considers authoritative (network or tracker)
  • custom_installs - Installs from the source Singular considers authoritative (tracker, or network for self-attributing networks)
  • tracker_conversions - Conversions (installs plus re-engagements) attributed by the tracker
  • tracker_reengagements - Re-engagements attributed by the attribution tracker
  • daily_active_users - Daily active users
  • extra_fields - Columns returned by Singular that have no column of their own, such as cohort metrics (JSON object)
Daily SKAdNetwork installs and postbacks from Apple SKAN postbacks. Available only to Singular attribution customers with SKAN data.Primary key: report_date, row_id
  • report_date - Day the aggregated row refers to, used as the incremental replication key
  • row_id - Deterministic hash of report_date and the row’s dimension values, identifying the row
  • app - App name in Singular
  • source - Ad network or other media source the data comes from
  • tracker_campaign_id - Campaign identifier as reported by the attribution tracker
  • tracker_campaign_name - Campaign name as reported by the attribution tracker
  • country_field - Country (ISO 3166 alpha-3 code)
  • skan_app_id - Value of the ‘app-id’ parameter in Apple’s SKAdNetwork postback
  • skan_network_id - Value of the ‘ad-network-id’ parameter in Apple’s SKAdNetwork postback
  • skan_campaign_id - SKAdNetwork campaign ID (SKAN 4: the first two digits of the Source ID)
  • skan_publisher_id - Value of the ‘source-app-id’ parameter in Apple’s SKAdNetwork postback
  • skan_redownloads - Whether the SKAdNetwork install is a redownload (true) or a regular download (false)
  • skan_validated - Whether Singular validated the SKAdNetwork postback with Apple
  • skan_version - SKAdNetwork version as received in the postback
  • skan_installs - Installs as reported by the SKAdNetwork framework
  • skan_conversion_values_count - Number of SKAN installs for which Singular received a conversion value
  • skan_p2_postbacks - Number of second-window (p2) postbacks reported by SKAdNetwork
  • skan_p3_postbacks - Number of third-window (p3) postbacks reported by SKAdNetwork
  • extra_fields - Columns returned by Singular that have no column of their own, such as cohort metrics (JSON object)
Daily SKAdNetwork data merged with network and tracker data by unified campaign. Available only to Singular attribution customers with SKAN data.Primary key: report_date, row_id
  • report_date - Day the aggregated row refers to, used as the incremental replication key
  • row_id - Deterministic hash of report_date and the row’s dimension values, identifying the row
  • app - App name in Singular
  • source - Ad network or other media source the data comes from
  • country_field - Country (ISO 3166 alpha-3 code)
  • unified_campaign_id - Campaign identifier after Singular’s joining of network and tracker data
  • unified_campaign_name - Campaign name after Singular’s joining of network and tracker data
  • skan_redownloads - Whether the SKAdNetwork install is a redownload (true) or a regular download (false)
  • skan_validated - Whether Singular validated the SKAdNetwork postback with Apple
  • adn_cost - Cost as reported by the ad network, converted to the account currency
  • skan_installs - Installs as reported by the SKAdNetwork framework
  • skan_conversion_values_count - Number of SKAN installs for which Singular received a conversion value
  • skan_revenue - Campaign revenue measured through SKAdNetwork
  • skan_report_network_clicks - Ad clicks as reported by the network, in the SKAdNetwork report
  • skan_report_network_impressions - Ad impressions as reported by the network, in the SKAdNetwork report
  • tracker_installs - Installs attributed by the attribution tracker
  • extra_fields - Columns returned by Singular that have no column of their own, such as cohort metrics (JSON object)
Daily ad revenue and ad serving statistics pulled from your monetization networks. Available only if ad monetization reporting is set up in Singular.Primary key: report_date, row_id
  • report_date - Day the aggregated row refers to, used as the incremental replication key
  • row_id - Deterministic hash of report_date and the row’s dimension values, identifying the row
  • app - App name in Singular
  • source - Ad network or other media source the data comes from
  • os - Device operating system (e.g. iOS, Android)
  • platform - Device platform (e.g. iPhone, iPad); equals os when the source has no such breakdown
  • site_publid_id - App store identifier of the app (bundle identifier or package name)
  • ad_country - Country in which the ad was served
  • ad_type_id - Identifier of the ad type (ad format or ad unit)
  • ad_type_name - Name of the ad type (ad format or ad unit), e.g. banner or rewarded video
  • ad_placement_id - Identifier of the ad placement within the app, as reported by the network
  • ad_placement_name - Name of the ad placement within the app, as reported by the network
  • ad_requests - Number of ad requests reported by the network
  • filled_ad_requests - Number of filled ad requests reported by the network (equals ad_impressions when not reported)
  • ad_impressions - Impressions reported by the ad network
  • video_views - Video views reported by the ad network
  • completed_video_views - Completed video views reported by the ad network
  • ad_clicks - Clicks reported by the ad network
  • ad_revenue - Ad revenue reported by the ad network, converted to USD
  • bid_requests - Number of bid requests to the ad network
  • bid_responses - Number of bid responses received from the ad network
  • extra_fields - Columns returned by Singular that have no column of their own, such as cohort metrics (JSON object)
Whether Singular already has data for each data connector on each day, and when it was last refreshed.Primary key: data_date, data_connector_id
  • data_date - Day the availability refers to, used as the incremental replication key
  • data_connector_id - Unique identifier of the data connector; can be used to filter reports
  • data_connector_source_name - Name of the source (ad network) the data connector pulls from
  • data_connector_username - Account/username the data connector uses to log into the source
  • status - Status of the data: Data Populated, Data not Populated, Login Error, Setup/Not configured or Disabled
  • is_available - True if there is data from this data connector for the day
  • is_empty_data - True if data was pulled successfully but is empty (all zeros or N/A); null when data was not pulled yet
  • is_active_last_30_days - True if this data connector had non-empty data at least once in the last 30 days
  • last_updated_utc - Last time data for this data connector was saved in the Singular database (UTC)
  • data_connector_timestamp_utc - Date and time data was last pulled from this data connector for the day (UTC)
  • is_all_data_available - True if all data connectors of the account have data for the day
Dimensions reports can be filtered by, with their possible values.Primary key: name
  • name - API name of the dimension that can be used in report filters
  • display_name - Name of the dimension as shown in the Singular platform
  • values - Possible values of the dimension (JSON array of objects with ‘name’, the value to use in filters, and ‘display_name’)
Custom dimensions configured in your Singular account.Primary key: id
  • id - Identifier of the custom dimension, used to request it in reports
  • display_name - Name of the custom dimension as shown in the Singular platform
Cohort metrics and in-app events available in your account.Primary key: name
  • name - Identifier of the cohort metric, used to request it in reports
  • display_name - Name of the cohort metric as shown in the Singular platform
Cohort periods supported by your account.Primary key: period
  • period - Cohort period identifier, used in the cohort_periods report parameter
Conversion events available as report metrics.Primary key: name
  • name - Auto-generated identifier of the conversion event, used to request it in reports
  • display_name - Name of the conversion event as configured in the Events page
SKAdNetwork events available for SKAN reports.Primary key: name
  • name - Auto-generated identifier of the SKAN event, used to request it in SKAN reports
  • display_name - Name of the SKAN event as shown in the Events page

​
Implementation notes

  • Rows are aggregated statistics, not user-level data. User-level data is only available through Singular’s Data Destinations (ETL) product, which this connector does not use.
  • Stats reported by an ad network (e.g. adn_installs) may differ from the ones reported by your attribution tracker (e.g. tracker_installs). The custom_* metrics in the Combined report hold the value Singular considers authoritative for each source.
  • Including data_connector_id splits network and tracker data into separate rows, so the data connector fields are only part of the Network report.
  • If a dimension combination disappears from Singular for a day that is extracted again, the old row is not deleted from your table.