GPT 操作库 - 通过 Adzviser 连接 Google Ads
简介
本文档为开发者构建特定应用程序的 GPT 操作提供了说明和指南。在继续之前，请确保您已熟悉以下信息：
本指南将介绍如何将 Google Ads 报告数据连接到 ChatGPT，以检索关键绩效指标，例如广告系列、广告组或广告级别的展示次数、点击次数和费用。为简化此过程，您将使用 Adzviser 作为中间件，它可确保从 Google Ads API 返回的数据格式正确，并已准备好在 ChatGPT 的 数据分析 环境中进行分析。
Adzviser 的工作原理：首先，通过 OAuth 将您的 Google Ads 帐户连接到 Adzviser。当您在 ChatGPT 中提出类似“上个月我每个广告系列的支出是多少？”之类的问题时，Adzviser 会发送一个 Google Ads 查询语言请求，并将响应转换为 CSV 文件（小于 10MB）。然后，该文件将返回给 ChatGPT 进行分析。Adzviser 使您能够轻松地审查和分析您的广告系列绩效，并根据历史数据洞察来构思优化策略。
价值 + 示例业务用例
价值：Google Ads 营销人员现在可以利用 ChatGPT 的自然语言功能，轻松查询绩效指标和帐户设置，而无需浏览 Google Ads 用户界面。整个过程中无需上传或下载任何文件。
示例用例：
- 一位电子商务企业主希望快速查看上个月 Google Ads 广告系列的回报广告支出 (ROAS)。
- 一位品牌营销人员旨在通过过去 3 个月的报告数据进行关键字和搜索词分析，以确定要暂停或扩展的关键字，以及要添加为否定关键字的搜索词。
- 一位代理机构营销人员需要生成一份月度报告，其中包含点击成本 (CPC)、每次转化费用 (CPA) 和搜索展示次数份额等关键指标，并进行月度比较。
- 一位自由职业营销人员在入职流程中需要审核新客户的 Google Ads 帐户，以评估绩效并寻找优化机会。
演示/示例
应用程序信息
应用程序关键链接
在开始之前，请查看此应用程序的以下链接：
- 如何在 Adzviser 上创建工作区：https://docs.adzviser.com/getStarted/workspace
- Adzviser 自定义 GPT 文档：https://docs.adzviser.com/chatgpt/expert
- Google Ads 提示库：https://docs.adzviser.com/chatgpt/googleAdsPromptTemplates
应用程序先决条件
在开始之前，请确保在您的应用程序环境中完成以下步骤：
- 确认您对 Google Ads 帐户具有只读、标准或管理员访问权限。
- 在 Adzviser 上注册一个帐户并激活订阅（起价为 0.99 美元）。
- 通过创建工作区将您的 Google Ads 帐户连接到 Adzviser
ChatGPT 步骤
自定义 GPT 说明
创建自定义 GPT 后，请将以下文本复制到“说明”面板中。有疑问吗？请查看入门示例，了解此步骤的详细信息。
***Context***:
您是一位 Google Ads 专家，负责审核帐户健康状况、检索实时报告数据并为营销人员优化绩效。当被要求审核帐户健康状况时，请收集相关的帐户设置，并提供调整帐户结构的建议。当被问及报告数据见解时，请收集相关的指标和细分，全面分析报告数据，然后提供量身定制的建议以优化绩效。
***检索报告数据的说明***：
- 获取实时报告数据的流程
步骤 1. 使用 Python 和代码解释器根据用户输入（例如，“上周”、“上个月”、“昨天”、“过去 28 天”、“上个季度”或“去年”等）计算日期范围。如果未提供特定时间范围，请要求用户澄清。考虑日历变化。例如，“上周”应涵盖上周一至周日。
步骤 2. 使用 `getWorkspace` 函数检索工作区信息。
步骤 3. 使用 `getGoogleAdsMetricsList` 和 `getGoogleAdsBreakdownsList` 等函数获取所查询数据源的相关指标和细分。
步骤 4. 使用 `searchQuery` 函数，并结合已收集的数据，如可用的工作区名称和指标/细分以及计算出的日期范围，来检索实时报告数据。
- 时间粒度：如果用户要求每日/每周/每季度/每月数据，请在 `searchQueryRequest` 的 `time_granularity` 字段中反映此类信息。如果用户未明确要求，则无需添加 `time_granularity`。
- 返回文件：如果返回多个文件，请确保读取所有文件。每个文件包含来自数据源的某个细分或数据源本身的数据。
- 只包含必要的细分：只添加重要的细分。少即是多。例如，如果用户询问“Google Ads 中哪个广告效果最好？”，那么您只需在 `google_ads_request` 的细分列表中添加“广告名称”。无需添加“设备”或“广告系列名称”等细分。
***审核说明***：
- 审核 Google Ads 帐户的流程
步骤 1. 使用 `getWorkspace` 函数检索工作区信息。
步骤 2. 使用 `/google_ads_audit/<specfic_section_to_check>` 函数检索帐户设置。
- 全面审核：当被要求进行全面审核时，请不要一次性调用所有 `/google_ads_audit/<specfic_section_to_check>`。首先向用户展示您接下来计划做什么。然后，一次审核 Google Ads 审核知识文档中的两个部分，然后在获得用户同意后继续进行另外两个部分。对于审核知识文档中未启用自动化的表格中的项目，在检索到的响应中看不到相关数据是非常正常且符合预期的。请重点说明需要用户手动检查的内容，因为这些非自动化步骤也很重要。例如，在检查连接时，adzviser 只检查 Google Ads 帐户是否与 Google Merchant Center 连接。对于其他连接，如 YouTube 频道，请礼貌地要求用户手动检查。
***附加说明***：
- 请务必使用代码解释器和 Python 计算日期范围。用户询问上周、上个月等时，经常会出现返回的日期范围是前一年的情况。
- 如果出现 `ApiSyntaxError: Could not parse API call kwargs as JSON` 错误，请礼貌地告知用户这是由于 OpenAI 模型最近的更新所致，可以通过在 ChatGPT 中开始新的对话来解决。
- 如果用户请求 Google Ads 数据等，并且只有一个工作区已连接到 Google Ads，则请在 `searchQueryRequest` 或 `googleAdsAuditRequest` 中使用此工作区名称。
- 在审核期间，部分流程是检索帐户、广告系列、广告组、关键字和产品级别的绩效指标，请记住还要运行 Python 来计算上个月和前一个时期的日期范围。对于检索这 5 个级别的绩效指标，请发送 5 个不同的请求，每个级别使用不同的细分列表。有关更多信息，请参阅审核知识文档。
OpenAPI 架构
创建自定义 GPT 后，请将以下文本复制到“操作”面板中。有疑问吗？请查看入门示例，了解此步骤的详细信息。
{
"openapi": "3.1.0",
"info": {
"title": "Adzviser Actions for GPT",
"description": "Equip GPTs with the ability to retrieve real-time reporting data and account settings from Google Ads",
"version": "v0.0.1"
},
"servers": [
{
"url": "https://copter.adzviser.com"
}
],
"paths": {
"/google_ads/get_metrics_list": {
"get": {
"description": "Get the list of seletable Google Ads metrics, such as Cost, Roas, Impressions, etc.",
"operationId": "getGoogleAdsMetricsList",
"parameters": [],
"deprecated": false,
"security": [],
"x-openai-isConsequential": false
}
},
"/google_ads/get_breakdowns_list": {
"get": {
"description": "Get the list of seletable Google Ads breakdowns such as Device, Keyword Text, Campaign Name etc.",
"operationId": "getGoogleAdsBreakdownsList",
"parameters": [],
"deprecated": false,
"security": [],
"x-openai-isConsequential": false
}
},
"/search_bar": {
"post": {
"description": "Retrieve real-time reporting data such as impressions, cpc, etc. from marketing channels such as Google Ads, Fb Ads, Fb Insights, Bing Ads, etc.",
"operationId": "searchQuery",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/searchQueryRequest"
}
}
},
"required": true
},
"deprecated": false,
"security": [
{
"oauth2": []
}
],
"x-openai-isConsequential": false
}
},
"/workspace/get": {
"get": {
"description": "Retrieve a list of workspaces that have been created by the user and their data sources, such as Google Ads, Facebook Ads accounts connected with each.",
"operationId": "getWorkspace",
"parameters": [],
"deprecated": false,
"security": [
{
"oauth2": []
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/getWorkspaceResponse"
}
}
}
}
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_merchant_center_connection": {
"post": {
"description": "Retrieve whether the Google Merchant Center is connected to the Google Ads account.",
"operationId": "checkGoogleAdsMerchantCenterConnection",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_account_settings": {
"post": {
"description": "Retrieve the Google Ads account settings such as whether auto tagging is enabled, inventory type, etc.",
"operationId": "checkGoogleAdsAccountSettings",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_negative_keywords_and_placements": {
"post": {
"description": "Retrieve the negative keywords and placements set in the Google Ads account.",
"operationId": "checkGoogleAdsNegativeKeywordsAndPlacements",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_remarketing_list": {
"post": {
"description": "Retrieve the remarketing list set in the Google Ads account.",
"operationId": "checkGoogleAdsRemarketingList",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_conversion_tracking": {
"post": {
"description": "Retrieve the conversion tracking status in the Google Ads account.",
"operationId": "checkGoogleAdsConversionTracking",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_bidding_strategy": {
"post": {
"description": "Retrieve the bidding strategy set for each active campaigns in the Google Ads account.",
"operationId": "checkGoogleAdsBiddingStrategy",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_search_campaign_basic": {
"post": {
"description": "Retrieve the basic information of the search campaigns such as campaign structure, language targeting, country targeting, etc.",
"operationId": "checkSearchCampaignBasic",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_search_campaign_detailed": {
"post": {
"description": "Retrieve the detailed information of the search campaigns such as best performing keywords, ad copies, ad extentions, pinned descriptions/headlines etc.",
"operationId": "checkSearchCampaignDetailed",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_dynamic_search_ads": {
"post": {
"description": "Retrieve the dynamic search ads information such as dynamic ad targets, negative ad targets, best performing search terms etc.",
"operationId": "checkDynamicSearchAds",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
},
"/google_ads_audit/check_pmax_campaign": {
"post": {
"description": "Retrieve the performance of the pmax campaigns such as search themes, country/language targeting, final url expansions, excluded urls.",
"operationId": "checkPmaxCampaign",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/googleAdsAuditRequest"
}
}
},
"required": true
},
"x-openai-isConsequential": false
}
}
},
"components": {
"schemas": {
"getWorkspaceResponse": {
"title": "getWorkspaceResponse",
"type": "array",
"description": "The list of workspaces created by the user on adzviser.com/main. A workspace can include multiple data sources",
"items": {
"type": "object",
"properties": {
"name": {
"title": "name",
"type": "string",
"description": "The name of a workspace"
},
"data_connections_accounts": {
"title": "data_connections_accounts",
"type": "array",
"description": "The list of data sources that the workspace is connected. The name can be an account name and type can be Google Ads/Facebook Ads/Bing Ads",
"items": {
"type": "object",
"properties": {
"name": {
"title": "name",
"type": "string",
"description": "The name of a data connection account"
}
}
}
}
}
}
},
"googleAdsAuditRequest": {
"description": "Contains details about the Google Ads account audit request.",
"type": "object",
"required": [
"workspace_name"
],
"title": "googleAdsAuditRequest",
"properties": {
"workspace_name": {
"type": "string",
"title": "workspace_name",
"description": "Call API getWorkspace first to get a list of available workspaces"
}
}
},
"searchQueryRequest": {
"description": "Contains details about queried data source, metrics, breakdowns, time ranges and time granularity, etc.",
"type": "object",
"required": [
"assorted_requests",
"workspace_name",
"date_ranges"
],
"title": "searchQueryRequest",
"properties": {
"assorted_requests": {
"type": "object",
"title": "assorted_requests",
"description": "For example, if the user asks for \"cost on Google ads last month\", then call getGoogleAdsMetricsList and getGoogleAdsBreakdownsList to retrieve the latest up-to-date info about how to compose a google_ads_request. A metric is a quantitative measurement. It represents data that can be measured and expressed in numbers. Metrics are used to track performance or behavior. Examples include clicks, impressions, conversions, revenue, etc. A breakdown is a qualitative attribute or descriptor. It provides context for metrics by categorizing or segmenting them. Breakdowns are text. Examples include country, channel, campaign name, etc. DO NOT include Date, Month, Quarter or Year in the list of breakdowns in any of the requests below. The breakdowns should be NOT mixed up with metrics, meaning that the selected breakdowns should be passed into the property \"breakdowns\", not \"metrics\", and vice versa.",
"properties": {
"google_ads_request": {
"type": "object",
"description": "DO NOT come up with metrics and breakdowns on your own. You MUST call API getGoogleAdsMetricsList and getGoogleAdsBreakdownsList to be better informed prior of composing a googleAdsRequest.",
"required": [
"metrics",
"breakdowns"
],
"properties": {
"breakdowns": {
"type": "array",
"items": {
"type": "string"
},
"description": "Must call API getGoogleAdsBreakdownsList to retrieve a list of selectable breakdowns."
},
"metrics": {
"type": "array",
"items": {
"type": "string"
},
"description": "Must call API getGoogleAdsMetricsList to retrieve a list of selectable metrics."
}
}
}
}
},
"workspace_name": {
"type": "string",
"title": "workspace_name",
"description": "Call API getWorkspace first to get a list of available workspaces. Multiple data sources (such as Google ads, Bing ads) can be stored in one workspace. If the user does not specify a workspace name, then use the available workspace name from the retrieved list and see which one has Google Ads. If the user has not yet created one, then ask them to go to adzviser.com/main to create a new workspace."
},
"date_ranges": {
"type": "array",
"description": "A list of date ranges requested from the user. They needs to be calculated seperately with Code Interpreter and Python every single time for accuracy. For example, if the user requests \"Google Ads search impression share in May and August\", then this array should be [[\"2024-05-01\", \"2024-05-31\"], [\"2024-08-01\", \"2024-08-31\"]].",
"items": {
"type": "array",
"items": {
"type": "string"
},
"description": "A 2-element array. The first represents the start date and the second the end date. Both are in YYYY-MM-DD format."
}
},
"time_granularity": {
"type": "string",
"title": "time_granularity",
"default": "",
"description": "Describes how granularity you wish the date_ranges to be. For example, If the user asks \"weekly cost on Google Ads\" this year, then this value should be \"Week\". If the user does not specify, then leave it as empty.",
"enum": [
"Date",
"Week",
"Month",
"Quarter"
]
}
}
}
},
"securitySchemes": {
"oauth2": {
"type": "oauth2"
}
}
}
}
身份验证说明
以下是设置此第三方应用程序身份验证的说明。有疑问吗？请查看入门示例，了解此步骤的详细信息。
在 ChatGPT 中
在 ChatGPT 中，点击“身份验证”并选择 “OAuth”。输入以下信息。
- 客户端 ID：（留空）
- 客户端密钥：（留空）
- 授权 URL：https://adzviser.com/authorize-gpt
- 令牌 URL：https://adzviser.com/api/oauth-exchange-token-gpt
- 范围：（留空）
- 令牌交换方法：默认 (POST)
常见问题解答和故障排除
- Google Ads 帐户列表为空：如果您在尝试连接 Google Ads 帐户时遇到 Google Ads 帐户列表为空的情况，则很可能是您尚未为 Google Ads 帐户命名。要解决此问题，请访问 ads.google.com 并登录。然后按照此处的说明为您的 Google Ads 帐户命名。
您希望我们优先集成哪些集成？我们的集成是否存在错误？在我们的 GitHub 上提交 PR 或 issue，我们将进行查看。