Google Ads API 对接与技术设计文档

1. 概述与设计宗旨

本技术文档详述了 GMVBest 测量系统如何对接并集成 Google Ads API（基于官方 Technical & Regulatory Compliance 合规标准）。GMVBest 作为一个独立的数据测量与归因平台，旨在代表广告主客户安全、合规地管理其转化数据回传链条。

核心目的：本系统接入 Google Ads API 的主要用途是通过 ConversionUploadService 服务，将广告主通过 API 或 SDK 收集到的最终用户转化事件（例如：注册、购买、应用内付费）安全地上传至 Google Ads 平台。这能够为广告主的 Google 广告系列提供精准的效果归因，协助 Google Ads 的机器学习优化算法进行精准出价（Smart Bidding）。

2. 系统架构与数据流

GMVBest 采用安全隔离、异步高并发的数据流水线处理广告事件上报。完整的数据链路如下图所示：

1. 触点捕获：最终用户在点击包含 Google 广告追踪参数（如 gclid、wbraid、gbraid）的推广链接时，GMVBest 系统捕获并生成关联的内部 link_id。
2. 事件上报：当最终用户在客户端完成转化动作，广告主服务器通过调用本平台的 事件上报 API（/report/event）将事件上报至 GMVBest 服务器。
3. 异步队列解析：本平台接收上报后，接口即时响应以保证性能。上报事件随后进入高可靠的异步消息队列（Kafka/RabbitMQ）中。
4. Google Ads API 调用：归因匹配引擎将事件匹配至 Google 原始点击标识，然后调用 Google Ads API 的 UploadClickConversions 接口进行离线转化上传。

3. OAuth 安全性与合规（符合 Google API 限制）

为了满足 Google Ads API 的数据安全及隐私限制，我们设计了最高级别的防护机制：

3.1 凭据安全存储与密钥管理

所有从 Google Ads API OAuth 2.0 流程获得的 Refresh Token 和 Access Token 均在数据库中采用 AES-256 算法 加密存储。解密密钥通过分布式硬件安全模块（HSM）管理，严禁以明文形式出现在系统日志或配置文件中。

3.2 数据保留与删除规则

• 有限保留期：为了满足 Google Ads 转化回传的 90 天有效窗口限制，所有用户的点击追踪日志及原始 API 访问数据均在 90 天后自动启动匿名化和物理删除程序。
• 即时删除：广告主可通过后台或致信 contract@gmvbest.com 发起即时删除，我们承诺在收到请求后 30 天内彻底清除其所有的 Google API 凭据、回传日志及相关转化数据。

3.3 严格的“使用限制”合规

GMVBest 对从 Google API 收到的信息的使用和转移将遵守 Google API 服务用户数据政策，包括其中的“使用限制（Limited Use）”要求：

• 所获取的数据仅用于提供营销归因、转换分析和报表展示服务。
• 严禁将数据向广告网络、数据分销商、数据经纪人等任何第三方进行传输、共享或转售。
• 严禁将数据用于定向广告系列、信用评估、金融信贷或训练任何 AI / 人工智能模型。

4. 广告事件上报 API 参考

本 API 用于将广告事件上报至 GMVBest 归因系统。系统会根据 link_id 自动识别并将事件通过 Google Ads API 等回传至对应广告渠道。

4.1 接口信息

• 接口地址: https://sdk-report.gmvbestopenapi.com/report/event
• 请求方法: POST
• Content-Type: application/json
• 认证方式: Header Authorization（Access Key）

4.2 请求 Headers

4.3 请求 Body (JSON)

4.4 响应参数

5. 多语言接入代码示例

5.1 Bash (cURL) 示例

curl -X POST https://sdk-report.gmvbestopenapi.com/report/event \
  -H "Content-Type: application/json" \
  -H "Authorization: your_access_key" \
  -d '{
    "link_id": "your_link_uuid",
    "event_name": "Purchase",
    "extra": {
      "currency": "USD",
      "value": 19.99
    }
  }'

5.2 Python 示例

import requests
import json

url = "https://sdk-report.gmvbestopenapi.com/report/event"
headers = {
    "Content-Type": "application/json",
    "Authorization": "your_access_key"
}
payload = {
    "link_id": "your_link_uuid",
    "event_name": "Purchase",
    "extra": {
        "currency": "USD",
        "value": 19.99
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())

5.3 Go 示例

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://sdk-report.gmvbestopenapi.com/report/event"
	payload := map[string]interface{}{
		"link_id":    "your_link_uuid",
		"event_name": "Purchase",
		"extra": map[string]interface{}{
			"currency": "USD",
			"value":    19.99,
		},
	}

	jsonValue, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonValue))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "your_access_key")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Error: %s", err)
		return
	}
	defer resp.Body.Close()
	fmt.Println("Response Status:", resp.Status)
}