google-ads-api-quickstart

Files (8)

• SKILL.md
• dotnet.md · references/
• java.md · references/
• perl.md · references/
• php.md · references/
• python.md · references/
• rest.md · references/
• ruby.md · references/

SKILL.md (first lines)

# Google Ads API Quickstart
This skill guides you from absolute zero to running your first successful request to retrieve campaigns.

## Supported Tracks
You can choose to use this skill with:

1. **Official Client Libraries:** Python, Java, .NET, PHP, Ruby, or Perl.
2. **Direct REST:** Raw HTTP REST requests.

---

## Crucial Requirement: Dynamic Version Resolution & Runtime Resolution

> [!IMPORTANT]
> To ensure the integration is secure, stable, and up-to-date, you must resolve all API and runtime versions dynamically. Do not rely on hardcoded defaults.

### Strict Constraints:

*   **DO NOT Hardcode:** Never use hardcoded Google Ads API versions (e.g., `v24`) or language runtime versions (e.g., `Python 3.8+`, `Java 11+`) in generated code or environment setup instructions, unless the user explicitly requests a specific version.
*   **MANDATORY Dynamic Resolution:** You must dynamically resolve the latest stable versions *at the start of execution* before generating any code or configuration, using the procedures detailed below.

### A. Dynamic API Version Resolution
To ensure the integration is secure, stable, and up-to-date, you **MUST** resolve the absolute newest stable major version of the Google Ads API dynamically.

#### Execution Steps:

1.  **Pre-Flight Version Resolution:** Use your web search or URL-reading tools to inspect the latest entry in the [Google Ads API Release Notes](https://developers.google.com/google-ads/api/docs/release-notes.md.txt) or the highest versioned directory in the [Googleapis Github Repository](https://github.com/googleapis/googleapis/tree/master/google/ads/googleads) to resolve `RESOLVED_API_VERSION` (e.g., `v24`). If using Java, you **MUST** also resolve the latest stable release version of the Google Ads Java Client Library (referred to as `RESOLVED_LIBRARY_VERSION`, e.g., `34.0.0`).

2.  **Mandatory Response Anchor:** You **MUST** output the following confirmation block as the **very first line** of your response to the user. Do not output any greeting, pleasantries, or introductory text before this block.
    
    ```text
    [SYSTEM: Using Google Ads API version: RESOLVED_API_VERSION (Resolved from release notes)]
    ```

3.  **Strict Placeholder Mapping Table:** You **MUST** perform on-the-fly search-and-replace on all code templates and reference files using the mapping table below. Do not leave raw placeholders in the final output.

    | Target Language / Tech | Placeholder in Template | Replacement Pattern | Example (Assuming API `v24`) |
    | :--- | :--- | :--- | :--- |
    | **Java** (Maven/Gradle) | `LATEST_LIBRARY_VERSION` | Search & substitute the latest Maven release version of the library. | `34.0.0` |
    | **Java** (Imports) | `vXX` | Replace with **lower-case** API version. | `com.google.ads.googleads.v24` |
    | **.NET / C#** (Namespaces) | `VXX` | Replace with **title-case** API version. | `Google.Ads.GoogleAds.V24` |
    | **PHP** (Namespaces) | `VXX` | Replace with **title-case** API version. | `Google\Ads\GoogleAds\V24` |
    | **REST** (Endpoint URL) | `vXX` | Replace with **lower-case** API version. | `https://googleads.googleapis.com/v24/...` |

> [!TIP]
> **Offline Fallback:** If the URLs are unreachable or the scrape fails, do not halt execution. Fall back to these last-known stable versions:
> *   **Google Ads API Major Version (`RESOLVED_API_VERSION`):** `v24`
> *   **Java Client Library Version (`RESOLVED_LIBRARY_VERSION`):** `34.0.0`

### B. Dynamic Language Runtime Version Resolution
To prevent the generated setup guides from becoming obsolete due to language deprecation cycles, you **MUST** resolve language requirements dynamically.

#### Execution Steps:

1.  **Fetch Live Requirements:** Use your URL-reading tools to inspect the official [Google Ads Client Libraries - Supported Versions](https://developers.google.com/google-ads/api/docs/client-libs.md.txt#supported_api_versions) page.

2.  **Extract Minimums:** Identify the minimum supported runtime version for the user's chosen language by scanning the Overview page or compatibility tables (e.g., looking for explicit requirements like Python 3.8+, Java 11+, .NET 6.0+, PHP 8.1+, Ruby 3.0+).

3.  **Apply On-The-Fly:** Substitute all runtime placeholders (e.g., `<PYTHON_MIN_VERSION>`) in your generated setup guides with these resolved versions.

> [!TIP]
> **Offline Fallback:** If the URL is unreachable or the scrape fails, do not halt execution. Fall back to these last-known safe minimum versions:
> *   **Python:** `3.9+`
> *   **Java:** `11+`
> *   **.NET:** `6.0+`
> *   **PHP:** `8.1+`
> *   **Ruby:** `3.0+`
> *   **Perl:** `5.28.1+`

---

## Step 1: Obtain Google Ads API Credentials

Before installing libraries or making API calls, you must obtain the five required authentication parameters.

### 1. Developer Token

*   **Purpose:** Identifies your developer access and API quota.
*   **How to Obtain:**
    1. Navigate directly to the **API Center** in your Google Ads Manager Account: https://ads.google.com/aw/apicenter *(Note: You must sign in with a Manager account, not a standard serving account)*.
    2. Copy your Developer Token.

> [!WARNING]
> **Pending Token Restriction:** If your Developer Token status is "Pending" (unapproved), you **MUST ONLY** target **Google Ads Test Accounts**. Attempting to call a production account with a pending token will fail with the error: `DEVELOPER_TOKEN_NOT_APPROVED`.

### 2. OAuth2 Client ID & Client Secret

*   **Purpose:** Identifies your application to Google's OAuth 2.0 server and allows you to request user authorization.
*   **How to Obtain:**
    1. Open the [Google Cloud Console](https://console.cloud.google.com/).
    2. Create a new project (or select an existing one).
    3. Search for the **Google Ads API** in the API Library and click **Enable**.
    4. Configure the **OAuth Consent Screen**:
       *   Select **External** user type.
       *   Set the Publishing Status to **Testing**.
       *   > [!IMPORTANT]
       *   > **Add Test Users:** You **MUST** add the email address of the Google account you use to log into Google Ads as a **Test User** in this step. Otherwise, you will be blocked during authorization.
    5. Create the OAuth Client:
       *   Go to **APIs & Services 🡒 Credentials**.
       *   Click **Create Credentials 🡒 OAuth client ID**.
       *   Select **Desktop App** as the Application Type.
       *   Name the client and click **Create**.
    6. **Download Secrets:** Click the download icon (JSON) next to your newly created Client ID. Save this file locally as `client_secrets.json`.

### 3. OAuth2 Refresh Token

*   **Purpose:** Allows your application to obtain new access tokens automatically without requiring manual user login every hour.
*   **How to Obtain:**
    You must run the Google Cloud (`gcloud`) CLI to generate your refresh token.

    #### 1. Install and Verify gcloud CLI:
    Ensure the [gcloud CLI](https://cloud.google.com/sdk/docs/install) is installed and available in your terminal.

    #### 2. Execute the Login Flow:
    Run the following command in your terminal, passing the path to the `client_secrets.json` file downloaded in the previous step:
    
    ```bash
    gcloud auth application-default login \
      --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
      --client-id-file=client_secrets.json

From artanphn-dotcom/google-skills, Apache-2.0.

More from artanphn-dotcom/google-skills