Menginstal dan menggunakan Asisten Developer Google Ads API

Asisten Developer Google Ads API menghadirkan keahlian mendalam domain Google Ads API langsung ke lingkungan coding AI Anda. Gunakan perintah bahasa alami dan perintah garis miring bawaan untuk membuat kueri, menghasilkan kode library klien, menjalankan panggilan API hanya baca, menstreaming laporan ad hoc, dan memecahkan masalah integrasi.

Asisten ini dibuat untuk framework agen Google Antigravity dan Claude Code (v4.0.0) sebagai plugin modular. Plugin ini menggunakan kontrak AGENTS.md dan CLAUDE.md, perintah garis miring bawaan, dan keterampilan domain khusus untuk mempertahankan konteks persisten, batas keamanan yang kuat, dan pipeline validasi otomatis.

Prasyarat

Sebelum memulai, pastikan Anda memiliki hal-hal berikut:

  1. Akses Google Ads API:

  2. Software:

Mulai

Ikuti langkah-langkah berikut untuk meng-clone repositori, menjalankan skrip penginstalan khusus platform, mengonfigurasi kredensial, dan mengaktifkan plugin.

1. Meng-clone repositori

Clone repositori ke komputer lokal Anda dan buka direktori project:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. Menjalankan skrip penginstalan

Jalankan skrip penginstalan untuk platform target Anda. Secara default, library klien Python disertakan. Anda dapat secara opsional menyertakan library klien tambahan (--php, --ruby, --java, --dotnet, atau --all).

Antigravity

Linux / macOS: ```bash ./install.sh agy

Atau sertakan library klien tambahan:

./install.sh agy --java --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type agy

Atau sertakan library klien tambahan:

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

Linux / macOS: ```bash ./install.sh claude

Atau sertakan library klien tambahan:

./install.sh claude --php --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type claude

Atau sertakan library klien tambahan:

.\install.ps1 -Type claude -Php -Dotnet ```

3. Mengonfigurasi kredensial

Pastikan file konfigurasi API Anda (misalnya, google-ads.yaml, google_ads_php.ini, atau google_ads_config.rb) ditempatkan di direktori $HOME Anda.

(Opsional) Untuk mengonfigurasi ID pelanggan default, masukkan nomor ID pelanggan Anda langsung ke config/customer_id.txt (misalnya, 1234567890). Anda juga dapat memeriksa atau menyematkan versi API aktif di config/api_version.txt.

4. Mengaktifkan plugin

  • Antigravity: Mulai ulang sesi host Antigravity / agy Anda untuk memuat plugin.
  • Claude Code: Dalam sesi Claude Code yang aktif, jalankan /reload-plugins atau mulai ulang claude.

5. Berinteraksi dengan Asisten

Anda dapat berinteraksi dengan Asisten menggunakan perintah bahasa alami atau perintah garis miring khusus langsung di terminal Anda.

Fitur utama

  • Panduan konseptual dan Tanya Jawab bahasa alami: Ajukan pertanyaan tentang fitur Google Ads API, aturan arsitektur, atau resource tertentu. Asisten mendasarkan respons pada definisi API resmi, bukan hanya mengandalkan pelatihan LLM umum.

    • "Apa saja jenis kampanye yang tersedia?"
    • "Bagaimana cara memfilter menurut tanggal di GAQL?"
    • "Jelaskan perbedaan antara click_view dan impression_view."
    • "Apa yang dimaksud dengan kumpulan bersama dan bagaimana cara menggunakannya?"
    • Perintah garis miring Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Pembuatan kode library klien yang didasarkan pada data: Hasilkan kode idiomatis yang telah diuji menggunakan library klien Google Ads resmi (Python, Java, PHP, .NET, dan Ruby).

    • "Tampilkan kampanye dengan konversi terbanyak dalam 30 hari terakhir."
    • "Dapatkan semua nama grup iklan yang diaktifkan untuk pelanggan 123-456-7890."
    • "Tulis kode untuk membuat kampanye Performa Maksimal." Kode yang dihasilkan disimpan di direktori saved/code/.

  • Validasi kueri GAQL terprogram: Otomatis jalankan dan validasi kueri kompleks terhadap metadata API, kompatibilitas kolom, aturan nol tayangan, dan segmentasi tanggal sebelum eksekusi.

    • Claude Code: /validate-gaql
    • Bahasa Alami: validate: SELECT campaign.id FROM campaign

  • Pemeriksaan skema Objek dan Protobuf: Periksa struktur resource, kolom bertingkat, jenis data, dan nilai enum secara dinamis untuk versi API aktif tanpa overhead metadata jarak jauh.

    • Claude Code: /inspect-object <resource_or_enum>
    • Bahasa Alami: "Periksa resource kampanye"

  • Pelaporan langsung ad hoc dan ekspor CSV: Minta data performa dalam bahasa Indonesia. Asisten membuat, memvalidasi, dan menjalankan kueri GAQL langsung terhadap akun Anda, menstreaming tabel berformat langsung ke terminal.

    • "Tampilkan 5 kata kunci teratas berdasarkan biaya bulan lalu untuk pelanggan 123-456-7890."
    • "Simpan hasilnya sebagai file CSV." (Diekspor ke saved/csv/).

  • Eksekusi API langsung dan keamanan perubahan: Jalankan skrip hanya baca yang dihasilkan langsung dalam lingkungan virtual yang dikelola.

    • Cukup beri tahu Asisten: "Jalankan kode" atau "Jalankan skrip".
    • Keamanan Perubahan: Untuk keamanan, operasi perubahan (buat, update, hapus) dihasilkan ke saved/code/, tetapi tidak pernah dijalankan langsung oleh asisten. Tinjau dan jalankan secara manual di luar asisten.

  • Diagnostik lanjutan dan pemecahan masalah konversi: Selidiki kegagalan upload konversi offline, validasi file upload sebelumnya, dan hasilkan laporan diagnostik mendetail.

    • Claude Code: /troubleshoot-conversions
    • Bahasa Alami: "Pecahkan masalah konversi untuk pelanggan 123-456-7890." (Laporan disimpan ke saved/data/).

  • Pemetaan hierarki akun MCC: Ambil ID pelanggan sub-akun dan petakan hierarki akun di bawah akun pengelola.

    • Claude Code: /get-cids <manager_cid>
    • Bahasa Alami: "Dapatkan semua ID pelanggan klien di bawah pengelola 123-456-7890"

  • Filter dan pengecualian listingan Performa Maksimal: Hasilkan pohon partisi produk dan pengecualian URL halaman web untuk grup aset.

    • Claude Code: /pmax-filter
    • Bahasa Alami: "Buat filter pengecualian halaman web untuk kampanye PMax saya"

  • Konteks codebase tambahan: Daftarkan logika aplikasi dan arsitektur kustom Anda ke dalam penalaran Asisten.

    • Linux / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): powershell .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Referensi perintah garis miring Claude Code

Saat menggunakan Claude Code, perintah garis miring bawaan berikut tersedia. Di Google Antigravity, panggil kemampuan yang sama ini menggunakan bahasa alami perintah atau nama alat keterampilan seperti validate_gaql dan inspect_object, seperti yang dijelaskan dalam Fitur utama:

Perintah garis miring Tujuan Contoh
/validate-gaql Memvalidasi sintaksis, kompatibilitas, dan aturan GAQL. /validate-gaql
/inspect-object Memeriksa kolom, jenis, dan enum Protobuf. /inspect-object Campaign
/get-cids Menyelesaikan hierarki MCC dan CID klien. /get-cids 1234567890
/troubleshoot-conversions Menjalankan diagnostik upload konversi offline. /troubleshoot-conversions
/pmax-filter Menghasilkan filter dan pengecualian listingan PMax. /pmax-filter
/explain Menyampaikan penjelasan terstruktur 4 bagian. /explain shared set
/step-by-step Merumuskan rencana eksekusi tugas multi-fase. /step-by-step upload conversions
/assistant-tutorial Menjalankan panduan interaktif 11 langkah. /assistant-tutorial

Pemeliharaan dan update

Untuk mengupdate repositori, penginstalan plugin, dan library klien:

Antigravity

Linux / macOS: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

Linux / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

Uninstal

Untuk meng-uninstal plugin asisten:

Antigravity

Linux / macOS: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): powershell Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Kemudian, mulai ulang sesi host Antigravity Anda.

Claude Code

Dalam sesi Claude Code yang aktif: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Atau dari terminal Anda: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Opsional) Hapus registry marketplace lokal: bash claude plugin marketplace remove google-ads-assistant-local

Komunitas dan dukungan

Pedoman kontribusi

Kontribusi Anda sangat kami harapkan. Lihat file CONTRIBUTING.md di repositori GitHub untuk mengetahui pedoman.

Sebelumnya
Apa itu Asisten Developer Google Ads API?