AdWords (Google Ads) Data Connector

This article describes the data connector that pulls data from Google Ads into Singular's analytics platform.

To learn how to configure Google Ads as a partner for Singular's attribution service, see Google Ads (AdWords) Attribution Integration.

Update (October 2020): With the Google Ads API no longer in beta, we have updated the integration to take advantage of new features and options. For example, we can now track all Google campaign types. If you have any questions after reading this article, reach out to Singular Support or your Customer Success Manager.

 

Quick Details

Data Connector Technology API (Google Ads API V5 -  see documentation)
Data breakdown (segmentation)

In addition to the basic breakdowns such as Campaign and Sub-Campaign, You can get your data in one of the following breakdowns:

  • Country (Default)
  • Keyword (does not support UAC campaigns)
  • Publisher (does not support UAC campaigns)

Notes: 

  • Keyword/publisher granularity is not available with country granularity due to a Google limitation.
  • Only the Country breakdown offers data for UAC campaigns.
  • By default, we provide the Country breakdown. Contact us if you want to use one of the other breakdowns.
How far back we pull data

7 days by default

Time zone Defined by the customer in Google settings, per account
Is data available on the creative (ad) level? Yes
Does Singular show your creative assets? Yes (excluding YouTube videos, which Singular only shows thumbnails for)
Known Limitations
  • Country granularity is not available for creatives.
  • The Installs metric is not available at asset granularity (you can't run a report showing the number of installs per asset).
  • The Keyword and Publisher breakdowns (if you choose to use them instead of the Country breakdown) do not include data for UAC campaigns.

Data Mapping

  • Singular’s Creative corresponds to Google Ads’ Ad.
  • Singular’s new Asset dimension corresponds to Google Ads’ Asset. We have added this new level of granularity because in Google, some types of ads, such as UAC (mobile app) ads, contain multiple assets.

Field Type Field in Singular UI Field in Singular API Field in Google
Campaign Dimensions Account ID adn_account_id customer.id
Campaign Dimensions Account Name adn_account_name customer.descriptiveName
Campaign Dimensions App Site ID app_site_id campaign.appCampaignSetting.appId
Campaign Dimensions Campaign URL adn_campaign_url ad.finalUrl
if not available, then ad.trackingUrlTemplate
Campaign Dimensions Country country_field geographicView.countryCriterionId
Campaign Dimensions Date date_field segments.date
Campaign Dimensions Final URL final_url campaign.finalUrls / adGorupCritirion.finalUrls / adGroup.ad.finalUrls
Campaign Dimensions Keyword keyword adGroupCriterion.keyword.text
Campaign Dimensions Network Campaign ID adn_campaign_id campaign.id
Campaign Dimensions Network Campaign Name adn_campaign_name campaign.name
Campaign Dimensions Network Creative ID adn_creative_id adGroupAd.ad.id
Campaign Dimensions Network Creative Name adn_creative_name adGroupAd.ad.name
Campaign Dimensions Network Sub Campaign ID adn_sub_campaign_id adGroup.id
Campaign Dimensions Network Sub Campaign Name adn_sub_campaign_name adGroup.name
Campaign Dimensions OS os campaign.appCampaignSetting.appStore
Campaign Dimensions Platform platform A combination of campaign.appCampaignSetting.appStore and segments.device
Campaign Dimensions Public Id site_public_id campaign.appCampaignSetting.appId
Campaign Dimensions Publisher Site Name publisher_site_name adGroupCriterion.placement.url
Campaign Dimensions Retargeting retention campaign.advertisingChannelSubType == ‘APP_CAMPAIGN_FOR_ENGAGEMENT_’
Campaign Dimensions Sub Ad Network adn_subadnetwork segments.adNetworkType
Campaign Dimensions Target Countries target_countries_str See country
Campaign Dimensions Text creative_text To create this field, we take any available text fields in the ad, which may differ based on the ad type. E.g., for UAC, the field in Google Ads is asset.textAsset.text. If there is more than one text (e.g. headline + description), we concatenate them into one string. 
Campaign Dimensions Timezone adn_timezone customer.timeZone (with some extra logic)
Campaign Dimensions Tracking URL tracking_url adGroupAd.ad.trackingUrlTemplate
Creative Dimensions Asset ID asset_id asset.id
Creative Dimensions Asset Name asset_name asset.name
Creative Dimensions Creative ID creative_id adGroupAa.ad.id
Creative Dimensions Creative Name creative_name adGroupAd.ad.name
Creative Dimensions Creative Reported URL creative_reported_url adGroupAd.ad.finalUrls.0
Metrics Cost adn_cost metrics.costMicro
Metrics Network Clicks adn_clicks metrics.clicks
Metrics Network Impressions adn_impressions metrics.impressions
Metrics Network Installs adn_installs metrics.conversions / metrics.allConversions
Metrics Original Cost adn_original_cost metrics.costMicro
Metrics Original Currency adn_original_currency customer.currencyCode
Metrics Video Views video_views metrics.videoViews
Metrics Completed Video Views completed_video_views metrics.video_quartile_p100_rate
Metrics Video Views - 25% video_views_25pct metrics.video_quartile_p25_rate
Metrics Video Views - 50% video_views_50pct metrics.video_quartile_p50_rate
Metrics Video Views - 75% video_views_75pct metrics.video_quartile_p75_rate

 FAQ and Troubleshooting

I am a Singular customer using the AdWords data connector. How do I know if I'm using the previous version (based on the old AdWords API) or the new one (based on the new Google Ads API)?

Starting October 2020, any users adding the "AdWords data connector" in the Data Connectors page will be getting the new version of the connector, whose details are documented in this article.

Many older customers who were using the old data connector have already been migrated to the new version for better performance and access to more UAC campaign data.

Singular is working on migrating the remaining customers to the new version of the data connector. If you have questions or concerns about the version you are using, reach out to your Singular Customer Success Manager.

How do I set up the AdWords data connector?

See the Data Connectors FAQ for general information about setting up a data connector.

When you set up the AdWords data connector you are asked to log in using a Google Ads account. We highly recommend signing in with a Google Ads Manager account (previously known as an MCC account).

A Google Manager account (MCC) gives us access to all your advertising accounts at once. Then you can pick and choose from the list which accounts you want to include in your Singular reports. If you don't use a Manager account (MCC), you will have to add a separate data connector for each advertising account.

How do I find my Manager account ID (MCC ID)?

To locate your customer ID (for both manager and individual accounts):

  1. Log into your Google Ads account.
  2. Click the help icon in the top right corner.
  3. Find Customer ID at the bottom of the menu.

For more information, see About Google Ads Manager Accounts in Google's documentation.

Why do I sometimes still see country data in the report, even if I'm using a different breakdown?

When you use a breakdown that doesn't provide country information, Singular tries to provide country granularity anyway, by looking at the campaign targeting settings in Google and/or tracker data (if we have it):

  1. If the campaign is targeted at one country, we'll show that country in the report.
  2. If there are multiple countries targeted, and we also have tracker data for the same campaign, we'll estimate the cost per country based on the ratio of installs per country in the tracker data. See How is the Cost metric calculated per country?
How does Singular pull Network Installs for AdWords campaigns?

Google Ads tracks different types of what it calls “conversion actions” - including app downloads, user sign-ups, purchases, and more. By default, since most of our customers are interested in app installs, we pull conversions of the type download and show their metrics in the Network Installs field in our reports.

Note: Network Installs is a metric in Singular that reflects the number of installs reported by the ad network - not to be confused with Installs, which is usually based on data from the attribution tracker. When you build a report query, you can select Network Installs in the Source Metrics section. See What are Source Metrics? for more information.

How can I get data for a different type of conversion event rather than app installs (downloads)?

If you have a web property rather than a mobile app, or you want to see another type of conversions in your Singular reports for any reason, contact us to customize this option for you. We can also pull conversions by the name of the conversion action if needed.

Does Singular pull creatives from AdWords?

Yes, Singular pulls creative metrics as well as the creatives themselves (images, texts, videos, etc.). This is true whether you use the old version of the AdWords integration or the new one. However, only the new integration shows creatives for UAC campaigns.

What is a "creative" in the AdWords context? What is the difference between a “creative” and an “asset”?

Singular’s Creative corresponds to Google Ads’ Ad.

Singular’s new Asset dimension corresponds to Google Ads’ Asset. We have added this new level of granularity because in Google, some types of ads, such as UAC (mobile app) ads, contain multiple assets.

Note: Due to a Google Ads API limitation, you currently can't see Installs broken down by asset, only by creative. In other words, if you run a report that includes the Asset ID or Asset Name dimensions, you can see other metrics, but not installs.

What Google ad types does Singular support?

Singular supports the following Google ad types:

Ad Type Ad Asset(s) Included
Text Image Video
Text      
Expanded Text      
Expanded Dynamic Search      
Shopping Product      
Shopping Smart      
Call Only      
HTML5 Upload      
Dynamic HTML5      
Responsive Search      
Legacy Responsive Search      
Legacy App Install      
Responsive Display      
Video      
App (UAC)      
App Engagement (UAC - deep linked ads)      

Note: Google's name for the ad type (“App Engagement”, “Responsive Search” etc.) does not appear in your Singular reports. The Creative Type dimension you see in your reports is unrelated - it shows whether the creative is an image, text, or video.

I am pulling the country breakdown. Why do I see rows without country information?

This can happen when there are discrepancies between the data that Google provides in different endpoints for the same campaigns.

When Singular pulls data from the Google Ads API, it performs the following steps:

  1. Pulls data in your selected breakdown from the corresponding Google Ads API endpoint, in this case - the location_view endpoint, which provides country information.
  2. Pulls data for the same campaigns from Google's campaign endpoint to get the full metrics.
  3. Compares the metrics for each campaign and if necessary, adds a row to align the data. See the illustration below for an example. Note that the campaign-level data is considered the source of truth.

Screen_Shot_2019-12-01_at_19.29.13.png

Why can’t I see videos in my creative reports?

Google’s privacy policy does not allow us to download YouTube videos. Therefore, for video creatives, we include the video thumbnail + a link to the video on YouTube.

What can't I see Media Bundles in my creative reports?

A Media Bundle is another type of creative, along with "Image", "Text", and "Video". If any of your ad creatives are media bundles, you will be able to see metrics for these creatives, but not the creative itself, because the Google Ads API does not provide the creative.

Why is the Creative Name dimension not always available?

For UAC creatives, Google does not provide a name, only an ID.

Why is the Asset ID/Asset Name dimension not always available?

The Asset ID and Asset Name dimensions are only available for UAC creatives.

Within UAC creatives, Google provides these dimensions with the following limitations:

  • Text assets and video assets do not have an Asset Name, only an Asset ID.
  • Image assets and media bundle assets have both a name and an ID.
  Asset Name Dimension
Asset ID Dimension
Text Assets
   
Video Assets
   
Image Assets
   
Media Bundle Assets
   

 

Was this article helpful?