Google Ads connector tools

  • Updated

The Google Ads connector tools in Optimizely Opal give you direct access to your advertising performance data. Use them to retrieve detailed metrics across campaigns, ad groups, and individual keywords. This integration lets you analyze audience demographics, geographic trends, and search queries to understand how your audience interacts with your ads. By centralizing these insights, you can optimize your budgets and refine targeting for Performance Max and Shopping campaigns. This supports data-backed experimentation and drives higher return on investment (ROI).

First, an Opal administrator must connect Opal with Google Ads. After an administrator installs the connector in Optimizely Connect Platform (OCP), you can log in to Google Ads from Opal to access your data. Administrators only need to install the Google Ads connection in OCP once.

Use cases

The following use cases show how you can use Google Ads connector tools in Opal to connect ad performance data with content and creative workflows.

Marketing strategy and performance optimization

Goal – Data-driven budget allocation and campaign scaling.

  • Key performance indicator (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 (the percentage of eligible impressions your ads receive). Opal can draft a recommendation to reallocate funds from budget-constrained campaigns.
  • High-intent keyword discovery – Run the googleads_get_keywords and googleads_get_search_terms tools to surface high-value search queries that drive conversions but are not yet added as exact-match keywords.
  • Channel synergy analysis – Compare performance across Search, Shopping (googleads_get_shopping_performance), and Performance Max (PMax) (googleads_get_asset_groups) to determine which network is most efficient for specific product categories.

A/B experimentation

Goal – Validate creative and copy hypotheses.

  • Ad copy comparison – Use the googleads_get_ads tool to compare the click-through rate (CTR) and conversion rate of different Responsive Search Ads (RSAs). Opal can analyze which headlines or descriptions drive performance and suggest 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 an Optimizely Web Experimentation or Optimizely Feature Experimentation test on those 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 – Use 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 generate a brief for a blog post in CMP to address that topic through organic search content.
  • 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 help generate 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 – Refine your audience and your geography.

  • 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 localized landing page content or localized ad extensions.
  • Audience mapping – Use the googleads_get_audiences tool to see which user lists are assigned. Opal can suggest Similar Segments or In-Market audiences based on the characteristics of the customers who convert at the highest rate.

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.

    Screenshot of the OCP App Directory with the Opal Google Ads Tool tile highlighted.

  2. Click Install App.

    Screenshot of the Opal Google Ads Tool Overview with the Install App button highlighted.

Configure Google Ads API authentication

Configure the Google Ads API authentication so Opal can call Google Ads on behalf of your account.

  1. Select the Settings tab.
  2. Expand the Google Ads API Authentication section.
  3. Enter your Customer ID. See Find your Google Ads customer ID in the Google documentation for instructions.
  4. (Optional) Enter your Login Customer ID. If you manage multiple Google Ads accounts under a Manager account (a single login that controls several customer accounts), this is the Manager account ID. To find it, see the Additional tips to find your customer ID section in the Find your Google Ads customer ID in the Google documentation.

  5. Click Save.

    Screenshot of the Google Ads configuration in OCP with the Google ads API Authentication section expanded with the Save button highlighted.

Configure tool permissions

  1. Select the Settings tab.
  2. Expand the Tool Permissions section.
  3. Toggle Enable Data Reading on to enable read-only tools.
  4. Toggle Enable Data Modifications on to enable write tools.

  5. Click Save.

    Google Ads OCP configuration with the Tools Permissions section expanded.

Add the Google Ads connector tools to Opal

After you install the app in OCP, configure Google Ads API authentication, and configure tool permissions, complete the following in OCP to connect to Opal:

  1. Select the Settings tab.
  2. Expand Add to Opal.

  3. Click Add to Opal for the Opal Account you want to add the Google Ads connector tools to.

    Screenshot of the OCP Add to Opal settings page where Add to Opal is selected for an Opal account.

Click Remove from Opal to remove the connection.

After you complete the steps in this section, each Opal user in your account can follow the steps in Authenticate with Google Ads to connect their own Google Ads login.

Authenticate with Google Ads

After an administrator connects Opal with Google Ads, log in from Opal to access your data. The Google Ads connector tools use user-level authentication, so you can only access data you have permission to view in Google Ads.

To authenticate, complete the following steps in Opal:

  1. Go to Tools > Connectors.

  2. Click Connect on the Google Ads connector tools.

    Screenshot of the Opal Connectors page where Connect is selected on the Google Ads connector.

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

    Screenshot of the Google sign-in window Optimizely displays during Google Ads authentication.

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 installs the Opal Google Ads Tool in OCP and you authenticate with Google Ads, call the following tools in Opal. Click a tool to expand it and learn when to use it, 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 hierarchy of your Google Ads account, monitor high-level performance metrics, manage budgets, and drill into specific ad groups and 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. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • (Optional) campaignIds – JSON array of campaign IDs to filter by. For example, [12345678, 87654321].
    • (Optional) metrics – JSON array of metric names to include. For example, ['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions'].
    • (Optional) adGroupIds – JSON array of ad group IDs to filter by. For example, [98765432, 87654321].
    • (Optional) adGroupStatus – JSON array of ad group statuses to filter by. For 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 drive 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. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • (Optional) campaignIds – JSON array of campaign IDs to filter by. For example, [12345678, 87654321].
    • (Optional) metrics – JSON array of metric names to include. For example, ['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions'].
    • (Optional) adIds – JSON array of ad IDs to filter by. For example, [11111111, 22222222].
    • (Optional) adGroupIds – JSON array of ad group IDs to filter by. For example, [98765432, 87654321].
    • (Optional) adStatus – JSON array of ad statuses to filter by. For 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 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. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • (Optional) campaignIds – JSON array of campaign IDs to filter by. For example, [12345678, 87654321].
    • (Optional) metrics – JSON array of metric names to include. For example, ['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions'].
    • (Optional) adIds – JSON array of ad IDs to filter by. For example, [11111111, 22222222].
    • (Optional) adGroupIds – JSON array of ad group IDs to filter by. For example, [98765432, 87654321].
    • (Optional) adStatus – JSON array of ad statuses to filter by. For 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 cost per click (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 your campaigns use.
    • 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. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • budgetIds – JSON array of campaign budget IDs. For example, [12345678, 87654321].
    • metrics – JSON array of metrics. For example, ['impressions', 'clicks', 'cost_micros'].
    • customerId – Customer ID (digits only).
    • deliveryMethods – JSON array of delivery methods. For 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 to identify the search queries that trigger your ads.

googleads_get_keywords – Get keyword-level data.
  • When to use
    • Analyze performance by keyword match type (Exact, Phrase, Broad). Keyword match types control how broadly Google matches your keyword against user search queries. Exact, Phrase, and Broad widen the match in that order.
    • Identify keywords with high cost but no conversions to pause or exclude.
    • Check Quality Score (Google's 1–10 rating of keyword relevance and ad experience) and expected click-through rate for keywords.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • metrics – JSON array of metrics. For example, ['impressions', 'clicks', 'cost_micros', 'ctr', 'conversions', 'quality_score'].
    • customerId – Customer ID (digits only).
    • campaignIds – JSON array of campaign IDs to filter by. For example, [12345678, 87654321].
    • keywordTexts – JSON array of keyword texts to filter by. For example, ['running shoes', 'sneakers', 'athletic footwear'].
    • adGroupIds – JSON array of ad group IDs to filter by. For example, [98765432, 87654321].
    • matchTypes – JSON array of keyword match types to filter by. For 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 end-user search terms.
  • When to use
    • Discover search queries that triggered ads, and use them to find negative keyword opportunities.
    • Identify emerging search trends and high-intent queries that are not yet added as keywords.
    • Understand how Google matches broad keywords to user queries.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • campaignIds – JSON array of campaign IDs to filter by. For example, [12345678, 87654321].
    • searchTermStatus – JSON array of search term statuses to filter by. For a single status, use ['NONE']. For multiple statuses, use ['ADDED', 'EXCLUDED'].
    • metrics – JSON array of metrics. For 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 for specialized Google Ads formats, such as Performance Max and Shopping, that require unique reporting. They provide insights into asset groups, product performance, and ad distribution across the Google network.

googleads_get_asset_groups – Get Performance Max (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 drive results.
    • Monitor the status and metrics of each PMax component.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • assetGroupIds – JSON array of asset group IDs. For example, [12345678, 87654321].
    • metrics – JSON array of metrics. For example, ['impressions', 'clicks'].
    • customerId – Customer ID (digits only).
    • assetGroupStatus – JSON array of asset group statuses. For example, ['ENABLED']. Valid statuses include ENABLED, PAUSED, and REMOVED.
    • campaignIds – JSON array of campaign IDs. For 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 – Get placement-level PMax reporting.
  • 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. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • campaignIds – JSON array of campaign IDs. For example, [12345678].
    • metrics – JSON array of metrics. For 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 Product ID or category in Shopping and PMax campaigns.
    • Identify "hero" products that are drive the most revenue for your ecommerce store.
    • Spot products with high spend but low return on ad spend (ROAS) to adjust bids or negative keywords (terms that prevent your ads from showing for irrelevant queries).
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • metrics – JSON array of metrics. For example, ['impressions', 'clicks'].
    • productIds – JSON array of product IDs in Merchant Center format. For example, ['online:en:US:12345', 'online:en:US:67890'].
    • adGroupIds – JSON array of ad group IDs. For example, [12345678].
    • customerId – Customer ID (digits only).
    • campaignIds – JSON array of campaign IDs. For 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. These breakdowns help 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. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • metrics – JSON array of metrics. For example, ['impressions', 'clicks'].
    • customerId – Customer ID (digits only).
    • campaignIds – JSON array of campaign IDs. For example, [12345678].
    • adGroupIds – JSON array of ad group IDs. For 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 your budget by focusing spend on the most responsive gender segments.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • metrics – JSON array of metrics. For example, ['impressions', 'clicks'].
    • customerId – Customer ID (digits only).
    • campaignIds – JSON array of campaign IDs. For example, [12345678].
    • adGroupIds – JSON array of ad group IDs. For 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) used for targeting.
    • Audit audience definitions to ensure they align with your current marketing strategy.
    • Identify available audiences for re-marketing or lookalike targeting.
  • Parameters
    • audienceIds – JSON array of audience IDs. For example, [12345678, 87654321].
    • audienceTypes – JSON array of audience types. For 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. Use them to understand where your results come from and what actions users take.

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 cost per acquisition (CPA) for users in California versus 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 categories, for example, Purchase, Lead, and Page View.
  • Parameters
    • startDate – Date range in YYYY-MM-DD format. For example, 2025-01-01.
    • endDate – Date range in YYYY-MM-DD format. For example, 2025-01-31.
    • customerId – Customer ID (digits only).
    • metrics – JSON array of metrics. For example, ['conversions', 'conversions_value'].
    • categories – JSON array of conversion categories. For example, ['PURCHASE', 'LEAD']. Valid categories include PURCHASE, LEAD, SIGNUP, PAGE_VIEW, ADD_TO_CART, and so on.
    • conversionActionIds – JSON array of conversion action IDs. For 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.

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.