Google Ads

Google Ads allows marketers to retrieve statistics about their ads, ad groups, and campaigns running on Google.

For creating Pipelines using this Source, Hevo provides you a fully managed BigQuery data warehouse as a possible Destination. This option remains available till the time you set up your first BigQuery Destination irrespective of any other Destinations that you may have. With the managed warehouse, you are only charged the cost that Hevo incurs for your project in Google BigQuery. The invoice is generated at the end of each month and payment is recovered as per the payment instrument you have set up. You can now create your Pipeline and directly start analyzing your Source data. Read Hevo Managed Google BigQuery.

Hevo uses the Google Adwords API to replicate your Google Ads data into the desired Destination system for scalable analysis. For this, you must authorize Hevo to access data from your Google Ads account.

Hevo fetches two types of objects in Google Ads:

  • Metadata Objects: These objects contain information about the ads that you run on Google Ads. For example, the name of the ad or the campaign to which it belongs.

  • Reports: These objects contain statistics of how your ads are performing. For example, the number of clicks received for the ad group on an android device.

Following are some terms associated with Google Ads that you must know before configuring Google Ads as a Source:

  • Metrics: These are statistical parameters that you measure for an ad or a campaign.

  • Dimensions: These are attributes in a report for which you want to see the statistics.

  • Segments: These are categories used to organize your data around selected criteria.

  • Conversion Window: This is the period of time after an ad interaction such as an ad click or a video view, during which a conversion such as a purchase is recorded in Google Ads.

For example, in the report for the number of clicks received for the ad group on an android device:

  • The number of clicks can be one of the metrics.

  • The name of the ad group can be the dimension.

  • The android device can be one of the segments.


Prerequisites

  • An active Google Ads account from which data is to be ingested.

  • Manage permission is granted on the authenticated Google Ads Account.


Configuring Google Ads as a Source

Perform the following steps to configure Google Ads as the Source in your Pipeline:

  1. Click PIPELINES in the Asset Palette.

  2. Click + CREATE in the Pipelines List View.

  3. In the Select Source Type page, select Google Ads.

  4. In the Configure your Google Ads page, click + ADD GOOGLE ADS ACCOUNT. This redirects you to the Google Ads login page.

  5. Log in to your Google Ads account.

  6. Click Allow to authorize Hevo to access your Google Ads data.

    Click Allow

  7. In the Configure your Google Ads Source page, specify the following:

    Test&Continue

    • Pipeline Name: A unique name for the Pipeline, not exceeding 255 characters.

    • Select Accounts: The Google Ads account(s) from where you want to replicate the data.

    • Select Reports: Select one of the following report types to ingest data from your Google Ads reports.

      • Predefined Reports: Hevo automatically selects all the metrics and dimensions for each Google Ads report that you want to replicate.

        To know how to configure predefined reports, read Predefined Reports.

      • Custom Reports: Hevo allows you to manually select the metrics and dimensions for each Google Ads report that you want to replicate.

        To know how to configure custom reports, read Custom Reports.

    • Metadata Objects (Optional): Select the metadata objects of your Google Ads that you want to replicate. Example: ACCOUNTS, CAMPAIGNS. Default: All.

    • Historical Sync Duration: The duration for which past data must be ingested. Default: 1 Year.

  8. Click CONTINUE.

  9. Proceed to configuring the data ingestion and setting up the Destination.


Predefined Reports

In case of predefined reports, Hevo automatically selects all the metrics and dimensions for each Google Ads report that you want to replicate to your Destination system.

To configure predefined reports, specify the following Predefined Report Settings:

Predefined settings

  • Report Names: Select the check box next to each report whose data you want to replicate to the Destination system.

  • Aggregation Window: The duration for which the report’s data is aggregated. Aggregation is done on a daily basis. Default: Daily.

    • Daily: Aggregates the data present in the reports once a day daily.

    • Last 7 days: Aggregates the data present in the reports for the last 7 days on a daily basis.

    • Last 14 days: Aggregates the data present in the reports for the last 14 days on a daily basis.

    • Last 30 days: Aggregates the data present in the reports for the last 30 days on a daily basis.

  • Advanced Settings:

    • Conversion Window (in days): Specify the duration at which you want to refresh the data to capture conversions. Default: 30 days. Max value: 90. Min Value: 1.

Custom Reports

In case of custom reports, you can manually select the metrics and dimensions for each Google Ads report that you want to replicate.

To configure custom reports, specify the following Custom Report Settings:

Custom settings

  • Report Name: Select the check box next to the report whose data you want to replicate to the Destination system.
    Note: The following reports do not have any segments. Therefore, these are not available for selection. To ingest data from these reports, use predefined reports.

    • call-metrics-call-details-report

    • campaign-criteria-report

    • campaign-negative-keywords-performance-report

    • campaign-negative-locations-report

    • campaign-negative-placements-performance-report

    • campaign-shared-set-report

    • click-performance-report

    • label-report

    • shared-set-criteria-report

    • shared-set-report

  • Segments: Select the criteria for organizing the data. These are displayed based on the report you select.

  • Dimensions: Select the dimension(s) you want to replicate. These are displayed based on the segments you select.

  • Metrics: Select the metric(s) you want to replicate. These are displayed based on the dimensions you select.

  • Aggregation Window: Select the duration for which the report’s data is aggregated on a daily basis. Default: Daily.

    • Daily: Aggregates the data present in the reports once a day daily.

    • Last 7 days: Aggregates the data present in the reports for the last 7 days on a daily basis.

    • Last 14 days: Aggregates the data present in the reports for the last 14 days on a daily basis.

    • Last 30 days: Aggregates the data present in the reports for the last 30 days on a daily basis.

  • Advanced Settings:

    • Conversion Window (in days): Specify the duration at which you want to refresh the data to capture conversions. Default: 30 days. Max value: 90. Min Value: 1.

Data Replication

  • Historical Data: Hevo loads all the metadata objects once the Pipeline is created.

    • For existing Pipelines: Historical data for one year is ingested.

    • For Pipelines created after Hevo release 1.63: Historical data for one year is ingested by default but can be changed as per the user’s requirement.

  • Incremental Data: Once the historical data ingestion is complete, every subsequent run of the Pipeline fetches new and updated data for the selected reports.

  • Data Refresh: Hevo refreshes the data based on the specified conversion window. For example, if the conversion window is 30, Hevo refreshes the data for the last 30 days from today.


Schema and Primary Keys

Note: All the amount fields in the reports are listed in Micros. See sample reports:

Hevo uses the following schema to upload the records in the Destination:

  • Primary Keys for Metadata Objects

    Object Primary Key
    ACCOUNTS CustomerId
    ADS AdGroupId, Id, CustomerId
    AD_GROUPS Id, CustomerId
    CAMPAIGNS Id, CustomerId
  • Primary Keys for Reports

    Report Primary Key
    KEYWORDS_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    AD_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    URL_PERFORMANCE_REPORT Url, CriteriaParameters, Date, ExternalCustomerId
    ADGROUP_PERFORMANCE_REPORT AdGroupId, Date, ExternalCustomerId
    CAMPAIGN_PERFORMANCE_REPORT CampaignId, Date, ExternalCustomerId
    ACCOUNT_PERFORMANCE_REPORT AccountDescriptiveName, Date, ExternalCustomerId
    GEO_PERFORMANCE_REPORT CampaignId, MostSpecificCriteriaId, Date, ExternalCustomerId
    SEARCH_QUERY_PERFORMANCE_REPORT Query, Date, ExternalCustomerId
    AUTOMATIC_PLACEMENTS_PERFORMANCE_REPORT Domain, Date, ExternalCustomerId
    CAMPAIGN_NEGATIVE_KEYWORDS_PERFORMANCE_REPORT Campaign Id, Id, Date, ExternalCustomerId
    CAMPAIGN_NEGATIVE_PLACEMENTS_PERFORMANCE_REPORT Campaign Id, Id, Date, ExternalCustomerId
    SHARED_SET_REPORT SharedSetId, Date, ExternalCustomerId
    CAMPAIGN_SHARED_SET_REPORT CampaignId, SharedSetId, Date, ExternalCustomerId
    SHARED_SET_CRITERIA_REPORT SharedSetId, Id, Date, ExternalCustomerId
    CREATIVE_CONVERSION_REPORT CriterionId, AdGroupId, Date, ExternalCustomerId
    CALL_METRICS_CALL_DETAILS_REPORT AdGroupId, ExternalCustomerId, CallStartTime, Date
    KEYWORDLESS_QUERY_REPORT CriterionId, Date, ExternalCustomerId
    KEYWORDLESS_CATEGORY_REPORT Category0, Category1, Category2, Date, ExternalCustomerId
    CRITERIA_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    CLICK_PERFORMANCE_REPORT GclId, Date, ExternalCustomerId
    BUDGET_PERFORMANCE_REPORT BudgetId, Date, ExternalCustomerId
    BID_GOAL_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    DISPLAY_KEYWORD_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    PLACEHOLDER_FEED_ITEM_REPORT AdGroupId, AdId, FeedId, FeedItemId, Date, ExternalCustomerId
    PLACEMENT_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    CAMPAIGN_NEGATIVE_LOCATIONS_REPORT Campaign Id, Id, Date, ExternalCustomerId
    GENDER_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    AGE_RANGE_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    CAMPAIGN_LOCATION_TARGET_REPORT Id, Date, ExternalCustomerId
    CAMPAIGN_AD_SCHEDULE_TARGET_REPORT Id, Date, ExternalCustomerId
    PAID_ORGANIC_QUERY_REPORT AdGroupId, CampaignId, KeywordId, Date, ExternalCustomerId
    AUDIENCE_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    DISPLAY_TOPICS_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    USER_AD_DISTANCE_REPORT CampaignId, DistanceBucket, Date, ExternalCustomerId
    SHOPPING_PERFORMANCE_REPORT OfferId, Date, ExternalCustomerId
    PRODUCT_PARTITION_REPORT Id, Date, ExternalCustomerId
    PARENTAL_STATUS_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    PLACEHOLDER_REPORT AdGroupId, ExtensionPlaceholderCreativeId, Date, ExternalCustomerId
    AD_CUSTOMIZERS_FEED_ITEM_REPORT FeedItemId, Date, ExternalCustomerId
    LABEL_REPORT LabelId, Date, ExternalCustomerId
    FINAL_URL_REPORT EffectiveFinalUrl, Date, ExternalCustomerId
    VIDEO_PERFORMANCE_REPORT AdGroupId, CampaignId, CreativeId, VideoChannelId, VideoId, Date, ExternalCustomerId
    TOP_CONTENT_PERFORMANCE_REPORT AdGroupId, Id, Date, ExternalCustomerId
    CAMPAIGN_CRITERIA_REPORT CampaignId, Id, Date, ExternalCustomerId
    CAMPAIGN_GROUP_PERFORMANCE_REPORT Id, Date, ExternalCustomerId
    LANDING_PAGE_REPORT UnexpandedFinalUrlString, Date, ExternalCustomerId
    MARKETPLACE_PERFORMANCE_REPORT CampaignId, AdGroupId, Date, ExternalCustomerId
  • As of Hevo Release 1.45, the data type of the __hevo_report_date field is changed to timestamp from the earlier type of long to make it easier to query by. This change is applicable to all Pipelines created from Release 1.45 onwards.

    Data type of 'hevo_report_date' field as 'timestamp'

  • Metadata Objects: Hevo attaches the following fields to all the metadata object Events fetched from Google APIs:

    • __hevo_report_date: The starting date of the time period for which the report is generated. If the aggregation window is 7 and the report data is generated for May 9 to May 15, then the __hevo_report_date is May 9.

    • __hevo_id: The unique ID of the Google Ads Event. Hevo derives this by hashing Google Ads data’s primary key columns.

  • Reports: Hevo attaches the following fields to all the report Events ingested from Google APIs:

    • __hevo_report_date: The starting date of the time period for which the report is generated. If the aggregation window is 7 and the report data is generated for May 9 to May 15, then the __hevo_report_date is May 9.

    • __hevo_id: The unique id of the Google Ads Event. Hevo derives this by hashing Google Ads data’s primary key columns along with __hevo_report_date and customer_id.

      Example: For the metadata object KEYWORDS_PERFORMANCE_REPORT, __hevo_id is generated using AdGroupId, Id, __hevo_report_date, and ExternalCustomerId. Thereby, Hevo ensures that if another record gets replicated with the same AdGroupId, Id, ExternalCustomerId, and __hevo_report_date, it is considered as an update to the Destination table.

  • Event Types:

    • The name of the Event Type is derived based on the aggregation window selected for the report.

      For example, if the selected report is AD_PERFORMANCE_REPORT and the aggregation window is Last 7 days, then the Event Type is named ad_performace_report_last_7_days.

      If the selected aggregation window is Daily, then the Event Type is named without any suffix.

      For example, if the selected report is AD_PERFORMANCE_REPORT and the aggregation window is Daily, then the Event Type is named ad_performance_report.

    • If you have selected a custom report, then the name of the Event Type is derived by adding the suffix __custom to the report name.

    • Some metrics can have values of different data types. For example, queryable and metadata information. For such metrics, Hevo adds a metadata column to the Destination to preserve the meta information.

    For example: if the value of the metric cost is auto:1000, Hevo would create two columns: cost and cost meta with values 1000 and auto: respectively.

    The following are some more examples where Hevo creates an additional metadata column to preserve the meta information:

    Actual Value Queryable Value Meta Information
    10% 10 %
    <10% 10 <%
    >10% 10 >%
    auto:x x auto:
    auto null auto
    10,000.5 10000.5 ,

Source Considerations

  • MySQL and Postgres Destination: For Account, AdGroups, Ads, and Ad Campaign objects, if the table or column name exceeds the maximum limit of 64 characters, Hevo maps them to a shortened name as mandated by Google. Refer to this list for shortened names mapping.

  • Google Ads does not support custom metrics and custom dimensions in the reports.


Data Model

Hevo provides support for replicating following metadata objects and reports:

Objects

  • Accounts

  • Ad Campaigns

  • Ad Groups

  • Ads

Reports


Limitations

  • Hevo currently does not support replication of the following dimensions:

    • ConversionAdjustment

    • IsNegative

    • CurrencyCode

    • ProductTitle

    • StoreId


Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Aug-8-2021 NA Added a note in the Schema and Primary Keys section about fields in tables being reported in Micros.
Jul-26-2021 NA Added a note in the Overview section about Hevo providing a fully-mananged Google BigQuery Destination for Pipelines created with this Source.
May-19-2021 1.63 - Updated the content to reflect the latest UI and functionality.
- Added the section, Custom Reports.
Last updated on 11 Aug 2021