Google Ads API Technical Design & Integration Document

1. Overview & Objectives

This technical document outlines the integration design of the GMVBest measurement system with the Google Ads API, adhering to Google's Technical & Regulatory Compliance standards. As an independent attribution and measurement partner, GMVBest is engineered to handle advertiser conversion feeds securely and transparently.

Primary Objective: The integration with the Google Ads API utilizes the ConversionUploadService to upload user-level conversion events (e.g., CompleteRegistration, Purchase) captured via our API and SDKs on behalf of our Clients. This enables accurate attribution for Google Ads campaigns and feeds Google's machine learning bidding systems (Smart Bidding) to optimize advertising performance.

2. System Architecture & Data Flow

GMVBest processes incoming advertisement events through an asynchronous, high-concurrency message pipeline. The full data stream operates as follows:

1. Touchpoint Registration: When an end-user clicks a promotion link containing Google tracking parameters (such as gclid, wbraid, or gbraid), the GMVBest system captures and registers a mapped internal link_id.
2. Event Postback: Upon completing a conversion action in-app or on-site, the Client's servers call our Event Reporting API (/report/event) to post the conversion details to GMVBest.
3. Asynchronous Queue: The platform responds immediately to ensure optimal client-side performance, entering the event payload into a Kafka/RabbitMQ queue for asynchronous processing.
4. Google Ads API Conversion Upload: The matching engine reconciles the conversion details to the original click parameters and invokes the Google Ads API's UploadClickConversions endpoint to transmit the offline conversion metadata.

3. OAuth Security & Compliance (Google API Restrictions)

To comply with Google Ads API data security guidelines and developer policies, we enforce the following safeguards:

3.1 Credential Encryption at Rest

All OAuth 2.0 credentials (Refresh Tokens and temporary Access Tokens) obtained during the authorization process are stored in our databases using the AES-256 cryptographic standard. Decryption keys are managed via distributed Hardware Security Modules (HSMs) and are never exposed in plaintext configurations or debugging logs.

3.2 Data Retention & Deletion Rules

• Finite Retention Policy: To satisfy Google Ads conversion tracking windows, click logs and API raw events are automatically anonymized or physically deleted after 90 days.
• On-Demand Deletion: Advertisers can request immediate data purging by writing to contract@gmvbest.com. We commit to removing all Google API credentials, conversion logs, and associated metrics within 30 days of receiving the request.

3.3 "Limited Use" Compliance

GMVBest's use and transfer of information received from Google APIs to any other app will adhere to the Google API Services User Data Policy, including the "Limited Use" requirements:

• Data retrieved is strictly used to provide marketing measurement, conversion matching, and reporting dashboards.
• We prohibit transferring, sharing, or selling Google Ads API data to ad networks, data brokers, or information resellers.
• We do not utilize Google Ads API data for targeted advertising campaigns, creditworthiness checks, financial lending, or training artificial intelligence (AI) models.

4. Event Reporting API Reference

This endpoint receives conversion events from advertiser servers. The system automatically routes events to their original Google Ads campaign via the Google Ads API.

4.1 Endpoint Details

• URL: https://sdk-report.gmvbestopenapi.com/report/event
• Method: POST
• Content-Type: application/json
• Authentication: Header Authorization (Access Key)

4.2 Headers

4.3 Request Body (JSON)

4.4 Response Fields

5. Code Integration Examples

5.1 cURL Example

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 Example

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 Example

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)
}