Google Ads connector tools

  • Updated

The Google Ads connector tools in Optimizely Opal provide a direct bridge to your advertising performance data, letting you retrieve detailed metrics across campaigns, ad groups, and individual keywords. This integration lets teams dive deep into audience demographics, geographic trends, and actual search queries to understand exactly how users are interacting with their ads. By centralizing these insights, marketers can more effectively optimize their budgets, refine targeting for Performance Max and Shopping campaigns, and drive higher ROI through data-backed experimentation.

First, an Opal administrator must connect Opal with Google Ads. After installing the connector in OCP, individual Opal users and agent builders can log in to Google Ads to access their information from Opal. Administrators only need to install the Google Ads connection in OCP once.

Complete the following steps to enable the Google Ads tools in Opal.

Connect Opal with Google Ads

Install the Opal Google Ads Tool in OCP

In the OCP App Directory, complete the following:

  1. Click the Opal Google Ads Tool.

  2. Click Install App. 

Complete Google Ads authentication in OCP

  1. Go to Settings > Google Ads API Authentication.
  2. Enter your Developer Token and Customer ID. 
  3. (Optional) Enter your Login Customer ID.

  4. Click Save. 

Add the Google Ads connector tools to Opal

After you Add the Opal Google Ads Tool in OCP, complete the following in OCP:

  1. Click Settings > Add to Opal.

  2. Click Add to Opal for the Opal Account you want to add the Mixpanel connector tools to. Click Remove from Opal to remove the connection. 

After you complete the steps in this section, Opal users can then follow the steps in the User-level auth for Google Ads section.

User-level auth for Google Ads

After an administrator connects Opal with Google Ads, you can log in from Opal to access your information. The Google Ads connector tools leverage user-level authorization to ensure individual Opal users can only access data they have permission to access within Google Ads. 

To authenticate, complete the following steps in Opal:

  1. Go to Tools > Connectors.
  2. Click Connect on the Google Ads connector tools.

  3. Log in to Google in the window Optimizely displays.

After you connect to Google, the Google Ads connector tools become available in Opal Chat, agents, and workflows.

Google Ads connector tools

After an Opal administrator Add the Opal Google Ads Tool in OCP and you log in using the User-level auth for Google Ads, you can call the following tools in Opal. Click on a tool to expand it to learn when to use the tool, available parameters, and example prompts. If you do not provide a required parameter, Opal prompts you for it.

Campaign and structure management

Use these tools to analyze the core hierarchy of your Google Ads account. Use them to monitor high-level performance metrics, manage budgets, and drill down into specific ad groups and individual ad creatives.

googleads_get_campaigns – Get high-level campaign metrics.
  • When to use
    • Monitor total spend, impressions, and conversions for specific campaigns over a set date range.
    • Compare performance between active and paused campaigns.
    • Identify top-performing campaigns to inform budget reallocation.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • (Optional) campaignIds – JSON array of campaign IDs to filter by. Example, "[12345678, 87654321]". 
    • (Optional) metrics – JSON array of metric names to include. Example, "['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions']".
    • (Optional) adGroupIds – JSON array of ad group IDs to filter by. Example:, "[98765432, 87654321]".
    • (Optional) adGroupStatus – JSON array of ad group statuses to filter by. Example, "['ENABLED', 'PAUSED']". Valid statuses include ENABLED, PAUSED, and REMOVED.
    • (Optional) customerId – Customer ID (digits only).
  • Example prompts
    • Show me the total cost and conversions for all enabled campaigns last month.
    • How did my "Search - Brand" campaign perform over the last 14 days?
    • I need a list of all paused campaigns and their historical click-through rates.
googleads_get_adgroups – Get ad group performance information.
  • When to use
    • Break down campaign results to see which themes or ad groups are driving the most ROI.
    • Analyze conversion rates at the ad group level to identify optimization opportunities.
    • Filter by ad group status to review performance of specific experimental groups.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • (Optional) campaignIds – JSON array of campaign IDs to filter by. Example, "[12345678, 87654321]". 
    • (Optional) metrics – JSON array of metric names to include. Example, "['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions']".
    • (Optional) adIds – JSON array of ad IDs to filter by. Example, "[11111111, 22222222]".
    • (Optional) adGroupIds – JSON array of ad group IDs to filter by. Example, "[98765432, 87654321]".
    • (Optional) adStatus – JSON array of ad statuses to filter by. Example, "['ENABLED', 'PAUSED']" Valid statuses include ENABLED, PAUSED, and REMOVED.
    • (Optional) customerId – Customer ID (digits only).
  • Example prompts
    • What are the top five ad groups by conversion rate in my "Winter Sale" campaign?
    • Show me the impressions and CPC for ad groups in campaign ID 12345.
    • List all enabled ad groups that had more than 10 conversions last week.
googleads_get_ads – Get individual ad performance.
  • When to use
    • Evaluate the performance of specific Responsive Search Ads or Expanded Text Ads.
    • Identify which ad creatives have the highest engagement (CTR).
    • Audit the performance of active ads within a specific campaign to refine copy or assets.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • (Optional) campaignIds – JSON array of campaign IDs to filter by. Example, "[12345678, 87654321]". 
    • (Optional) metrics – JSON array of metric names to include. Example, "['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions']".
    • (Optional) adIds – JSON array of ad IDs to filter by. Example, "[11111111, 22222222]".
    • (Optional) adGroupIds – JSON array of ad group IDs to filter by. Example, "[98765432, 87654321]".
    • (Optional) adStatus – JSON array of ad statuses to filter by. Example, "['ENABLED', 'PAUSED']" Valid statuses include ENABLED, PAUSED, and REMOVED.
    • (Optional) customerId – Customer ID (digits only).
  • Example prompts
    • Compare the performance of all enabled ads in my "Brand" ad group.
    • Which individual ads had the lowest CPC last month?
    • Show me the conversion data for all ads in campaign 987654.
googleads_get_budgets – Get budget settings and spend.
  • When to use
    • Track how much of your daily budget is being utilized across campaigns.
    • Monitor shared budget performance to ensure even delivery.
    • Identify campaigns that are "Limited by Budget" by comparing cost to daily limits.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • budgetIds – JSON array of campaign budget IDs. Example, "[12345678, 87654321]".
    • metrics – JSON array of metrics. Example, "['impressions', 'clicks', 'cost_micros']". 
    • customerId – Customer ID (digits only).
    • deliveryMethods – JSON array of delivery methods. Example, "['STANDARD']". Valid methods include STANDARD and ACCELERATED.
  • Example prompts
    • Show me the daily budget and total spend for all campaigns this week.
    • Which budgets are shared across multiple campaigns and how is the spend distributed?
    • Check the performance of my primary budget for the current month.

Search and keyword intelligence

Use these tools to analyze the effectiveness of your targeted keywords and identify the actual search queries triggering your ads.

googleads_get_keywords – Get Keyword-level data
  • When to use
    • Analyze performance by keyword match type (Exact, Phrase, Broad).
    • Identify keywords with high cost but no conversions to pause or exclude.
    • Check Quality Score and expected CTR for individual keywords.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • metrics – JSON array of metrics. Example, "['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions', 'quality_score']".
    • customerId – Customer ID (digits only).
    • campaignIds – JSON array of campaign IDs to filter by. Example, "[12345678, 87654321]". 
    • keywordTexts – JSON array of keyword texts to filter by. Example, "['running shoes', 'sneakers', 'athletic footwear']".
    • adGroupIds – JSON array of ad group IDs to filter by. Example, "[98765432, 87654321]".
    • matchTypes – JSON array of keyword match types to filter by. Example, "['EXACT', 'PHRASE']". Valid match types include the following:
      • EXACT – Exact match keywords.
      • PHRASE – Phrase match keywords.
      • BROAD – Broad match keywords.
  • Example prompts
    • What are the top 10 keywords by conversion value in campaign 123?
    • Show me all Exact match keywords that have a Quality Score below five.
    • List the cost per conversion for keywords in my "Search - NonBrand" campaign.
googleads_get_search_terms – Get actual user search terms.
  • When to use
    • Discover actual search queries that triggered ads to find new negative keyword opportunities.
    • Identify emerging search trends and high-intent queries that aren't yet added as keywords.
    • Understand how broad match keywords are being mapped to user queries.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • campaignIds – JSON array of campaign IDs to filter by. Example, "[12345678, 87654321]". 
    • searchTermStatus – JSON array of search term statuses to filter by. Single status, "['NONE']". Multiple statuses, "['ADDED', 'EXCLUDED']".
    • metrics – JSON array of metrics. Example, "['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions']".
  • Example prompts
    • Show me the search terms from the last 30 days that have not been added as keywords.
    • Which search queries had more than 5 conversions last month?
    • I need a list of search terms from the "Shoes" ad group with a CTR higher than 10%.

Specialized campaign performance

Use these tools to gain insights into asset groups, product performance, and ad distribution across the Google network. Use these tool for specialized Google Ads-related formats, like Performance Max and Shopping, that require unique reporting. 

googleads_get_asset_groups – Get PMax Asset Group insights
  • When to use
    • Evaluate the performance of different asset groups (combinations of text, images, and video) in Performance Max.
    • Identify which audiences or themes within a PMax campaign are driving results.
    • Monitor the status and metrics of individual PMax components.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • assetGroupIds – JSON array of asset group IDs. Example: "[12345678, 87654321]".
    • metrics – JSON array of metrics. Example, "['impressions', 'clicks']".
    • customerId – Customer ID (digits only).
    • assetGroupStatus – JSON array of asset group statuses. Example, "['ENABLED']". Valid statuses include ENABLED, PAUSED, and REMOVED.
    • campaignIds – JSON array of campaign IDs. Example, "[12345678]".
  • Example prompts
    • Show me the clicks and conversions for asset groups in my PMax campaign.
    • Which asset group in campaign 987 has the highest conversion value?
    • List all enabled asset groups and their performance for the last 30 days.
googleads_get_pmax_placements – Track where PMax ads display.
  • When to use
    • Identify the websites, YouTube channels, or mobile apps where Google displays your Performance Max ads.
    • Audit placements for brand safety and relevance.
    • Understand the distribution of your PMax budget across the Google Display Network.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • campaignIds – JSON array of campaign IDs. Example, "[12345678]".
    • metrics – JSON array of metrics. Example, "['impressions', 'clicks']".
    • customerId – Customer ID (digits only).
  • Example prompts
    • Where did my PMax ads show last week? Show me the top 20 placements by impressions.
    • List the placements for campaign ID 45678 and their respective conversion counts.
    • I need a placement report for my all-asset Performance Max campaign.
googleads_get_shopping_performance – Get product-level metrics.
  • When to use
    • Analyze performance by individual Product ID or category in Shopping and PMax campaigns.
    • Identify "hero" products that are driving the most revenue for your ecommerce store.
    • Spot products with high spend but low ROAS to adjust bids or negative keywords.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • metrics – JSON array of metrics. Example, "['impressions', 'clicks']".
    • productIds – JSON array of product IDs in Merchant Center format. Example, "['online:en:US:12345', 'online:en:US:67890']".
    • adGroupIds – JSON array of ad group IDs. Example, "[12345678]".
    • customerId – Customer ID (digits only).
    • campaignIds – JSON array of campaign IDs. Example, "[12345678]".
  • Example prompts
    • What are my top 10 best-selling products by conversion value in Google Shopping?
    • Show me the impressions and cost for product ID 'online:en:US:12345'.
    • List product performance for the "Electronics" category over the last quarter.

Audience and demographic insights

Use these tools to break down performance by age, gender, and pre-defined audience segments to understand who is engaging with your ads. This helps you tailor your messaging and targeting. 

googleads_get_age_performance – Get age range breakdown.
  • When to use
    • Determine which age groups have the highest conversion rates to refine targeting.
    • Evaluate if your ad creative is resonating with your target demographic.
    • Justify bid adjustments for specific age brackets (for example, 25-34) based on performance.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • metrics – JSON array of metrics. Example, "['impressions', 'clicks']".
    • customerId – Customer ID (digits only). 
    • campaignIds – JSON array of campaign IDs. Example, "[12345678]".
    • adGroupIds – JSON array of ad group IDs. Example, "[12345678]".
  • Example prompts
    • What is the conversion rate for the 18-24 age range in my "University" campaign?
    • Show me a breakdown of clicks and cost by age group for last month.
    • Which age range has the lowest cost per conversion across the whole account?
googleads_get_gender_performance – Get gender-based performance.
  • When to use
    • Compare performance between Male, Female, and Undetermined segments.
    • Identify demographic shifts in performance for specific localized campaigns.
    • Optimize budget by focused spend on the most responsive gender segments.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • metrics – JSON array of metrics. Example, "['impressions', 'clicks']".
    • customerId – Customer ID (digits only). 
    • campaignIds – JSON array of campaign IDs. Example, "[12345678]".
    • adGroupIds – JSON array of ad group IDs. Example, "[12345678]".
  • Example prompts
    • Which gender segment has the highest CTR in my "Apparel" campaign?
    • Show me the conversion value breakdown by gender for campaign ID 445566.
    • Compare impressions by gender for all search campaigns over the last 60 days.
googleads_get_audiences – Get audience configuration.
  • When to use
    • Review the audience segments (User Lists, Custom Audiences) currently used for targeting.
    • Audit audience definitions to ensure they align with your current marketing strategy.
    • Identify available audiences for remarketing or lookalike targeting.
  • Parameters
    • audienceIds – JSON array of audience IDs. Example, "[12345678, 87654321]".
    • audienceTypes –JSON array of audience types. Example, "['USER_LIST']". Types include USER_LIST, CUSTOM_AUDIENCE, and SIMILAR_AUDIENCE.
    • customerId – Customer ID (digits only). 
  • Example prompts
    • List all custom audiences configured in my account.
    • What are the definitions for my current remarketing lists?
    • Show me the IDs for all "In-Market" audiences I am currently tracking.

Geographic and result tracking

These tools provide location-specific data and detailed conversion tracking insights to understand where your results are coming from and what specific actions users are taking.

googleads_get_geographic_performance – Get location-based performance information.
  • When to use
    • Identify high-performing countries, regions, or cities for expanded targeting.
    • Determine which geographic areas should be excluded based on high spend and low conversions.
    • Inform location-based bid adjustments for specialized local service campaigns.
  • Parameters
    • adGroupIds – JSON array of ad group IDs to filter by. Examples include the following:
      • Single ad group – "[12345678]"
      • Multiple ad groups – "[12345678, 87654321]"
    • locationIds – JSON array of location criteria IDs to filter by. Examples include the following:
      • Single location – "[2840]" (United States).
      • Multiple locations – "[2840, 2826, 2124]" (United States, United Kingdom, and Canada).
  • Example prompts
    • What were the top five countries by conversion rate for my "Global Search" campaign?
    • Show me the CPA for users in California vs New York over the last month.
    • List all cities in the UK where my ads generated more than 50 clicks last week.
googleads_get_conversions – Get conversion action details.
  • When to use
    • Analyze the performance of specific conversion actions, such as "Add to Cart" or "Form Submission."
    • Verify that your conversion tracking is recording data correctly.
    • Compare conversion value across different categories. For example, Purchase, Lead, Page View.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. Example, "2025-01-01".
    • endDate – Date range in YYYY-MM-DD format. Example, "2025-01-31".
    • customerId – Customer ID (digits only). 
    • metrics – JSON array of metrics. Example, "['conversions', 'conversions_value']".
    • categories – JSON array of conversion categories. Example, "['PURCHASE', 'LEAD']". Valid categories include PURCHASE, LEAD, SIGNUP, PAGE_VIEW, ADD_TO_CART, and so on.
    • conversionActionIds – JSON array of conversion action IDs. Example, "[12345678, 87654321]"
  • Example prompts
    • What is the conversion value for my "Direct Purchase" action last quarter?
    • Show me a breakdown of different conversion categories for my main website.
    • List all conversion actions and their status for the current month.

Use cases

The following section outlines how marketing teams can leverage Google Ads connector tools within Opal to bridge the gap between ad performance data and creative execution.

Marketing strategy and performance optimization

Goal – Data-driven budget allocation and campaign scaling.

  • KPI monitoring and budget shifting – Use the googleads_get_campaigns and googleads_get_budgets tools to identify campaigns with high conversion rates but low impression share due to budget constraints. Opal can then draft a recommendation for the digital marketing manager to reallocate funds from underperforming campaigns.
  • High-intent keyword discovery – Run the googleads_get_keywords and googleads_get_search_terms tools to find "gem" search queries that are driving conversions but are not yet added as exact-match keywords.
  • Channel synergy analysis – Compare performance across Search, Shopping (googleads_get_shopping_performance), and PMax (googleads_get_asset_groups) to determine which network is most efficient for specific product categories.

A/B experimentation

Goal – Validating creative and copy hypotheses.

  • Ad copy comparison – Use the googleads_get_ads tool to compare the CTR and Conversion Rate of different Responsive Search Ads (RSAs). Opal can analyze which headlines or descriptions are driving the lift and suggest new variations for follow-up testing.
  • Landing page validation – Correlate specific ad groups (googleads_get_adgroups) with conversion data to see which landing pages (mapped to those ad groups) are underperforming. Use this to trigger a new Optimizely Web Experimentation or Optimizely Feature Experimentation test on those specific pages.
  • Demographic sensitivity testing – Use the googleads_get_age_performance and googleads_get_gender_performance tools to see if a specific creative resonates better with certain age groups. If a "Gen Z" creative is underperforming with its target, Opal can draft a brief for a more aligned creative direction.

Content pipeline and creative plans

Goal – Using search data to fuel Optimizely Content Marketing Platform (CMP). 

  • Search-driven content briefs – Analyze top-performing search terms using the  googleads_get_search_terms tool. If a specific question or pain point appears frequently, Opal can automatically generate a brief for a blog post in Optimizely CMP to address that topic organically.
  • PMax asset optimization – Use the googleads_get_asset_groups tool to identify which asset groups in a Performance Max campaign have "Low" performance ratings. Opal can then assist in generating new image prompts or headlines to replace the weak assets.
  • Seasonal creative refresh – Pull geographic performance data using the googleads_get_geographic_performance tool. If a region is showing an uptick in interest for a specific product, use Opal to create localized ad copy or social assets tailored to that region's trends.

Audience insights and target strategy

Goal – Refining the "Who" and "Where".

  • Geographic expansion – Identify cities or regions with high conversion rates but low volume using the googleads_get_geographic_performance tool. Use this insight to create targeted "localized" landing page content or localized ad extensions.
  • Audience mapping – Use the googleads_get_audiences tool to see which user lists are currently assigned. Opal can suggest new "Similar Segments" or "In-Market" audiences to test based on the characteristics of the users currently converting at the highest rate.

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applications.