Google Ads Scripts rehberi: ne zaman kullanılır, nasıl test edilir?

Google Ads Scripts, Google Ads hesabında JavaScript ile çalışan küçük programlardır. Hesaptaki verileri okuyabilir, kampanya, reklam grubu ve anahtar kelime gibi öğeleri değiştirebilir, sonucu e-mail ile gönderebilir ya da Google Sheets'e yazabilirler. Script'ler Google Ads'te Araçlar menüsünün altındaki Toplu işlemler bölümünde, Komut dosyaları sayfasında oluşturulur.

Ama her otomasyon işi için doğru araç script değildir. Basit bir koşulla kampanya durdurmak için otomatik kural yeterli, yüzlerce hesabı yöneten bir ürün içinse Google Ads API gerekir. Bu rehber önce hangi işin hangi araçla yapılacağını ayırıyor. Ardından script'in yapısını, güncel limitleri ve bir script'i hesabında çalıştırmadan önce nasıl test edeceğini anlatıyor. Sonunda Google'ın dokümanlarındaki yöntemlerle yazılmış bir başlangıç script'i ve eski script'leri tanımak için bir kontrol listesi var.

Kod yazmadan toplu yönetim için Google otomatik kuralları, toplu yüklemeleri ve Google Ads Editor'ü öneriyor. Script'ler ise JavaScript bilen ya da bilen biriyle çalışan ve büyük bir hesabı olan reklamverenlere uygun. Aşağıdaki tablo seçimi ihtiyaca göre özetliyor.

Seçimi belirleyen asıl soru, işin bir kuralın koşul ve işlem yapısına sığıp sığmadığı. Birden fazla veriyi birleştiren, dışarıdan bilgi alan ya da özel bir rapor üreten işler script gerektirir. Basit bir eşiğe bağlı işler ise kuralla daha güvenli yapılır, çünkü kuralların yaptığı son değişiklikler geri alınabiliyor. Script'lerde böyle yerleşik bir geri alma yok.

Zamanlama ayrı bir operasyon notu. Kurallar koşullar oluştuktan sonra genellikle iki saat içinde çalışıyor. Script'ler saatlik, günlük, haftalık, aylık ya da istendiğinde çalışacak şekilde planlanabiliyor. Ama bu, script'in her durumda daha hızlı tepki vereceği anlamına gelmiyor, çünkü script de ancak planlandığı saatte ve elindeki veriyle çalışır.

Her script bir main fonksiyonuyla başlar ve hesaba AdsApp nesnesi üzerinden erişir. Hesaptaki öğelere iki yoldan ulaşabilirsin. İlki seçiciler: AdsApp.campaigns() gibi bir koleksiyonu withCondition ile filtreler, sonra sonuçların üzerinde tek tek dolaşırsın. İkincisi raporlar: Google Ads Query Language (GAQL) ile yazılmış bir sorguyu AdsApp.search() ile çalıştırırsın.

Rapor altyapısı Google Ads API'ye dayanıyor ve hangi alanların, metriklerin ve koşulların isteneceği GAQL ile belirleniyor. search() sonuçlarındaki alan adları sorguda alt çizgiyle yazılsa da sonuçta camelCase olarak döner. Sorguda metrics.cost_micros yazarsın, sonuçta row.metrics.costMicros okursun.

İstatistik okuyacaksan seçiciler yerine raporları kullan. Raporlar büyük sorgularda daha iyi performans veriyor ve normal getirme kotalarına takılmıyor. Google'ın en iyi uygulamalar sayfası eski report() yöntemi yerine search() kullanılmasını da öneriyor.

Birimlere dikkat et. metrics.cost_micros mikro birimde gelir, hesap para birimine çevirmek için 1.000.000'a bölünür. Dönüşüm değeri olan metrics.conversions_value ise mikro birimde değil. Script'ten ROAS (reklam harcaması getirisi) hesaplıyorsan dönüşüm değerini mikrodan çevrilmiş maliyete böl. Sonucu ROAS hesaplayıcısıyla karşılaştırabilirsin.

Güncel limitler

Aşağıdaki değerler Google'ın limitler sayfasından alındı ve 30 Ekim 2026'daki durumu gösteriyor. Google bu limitlerin önceden haber verilmeden değişebileceğini söylüyor, bu yüzden script'lerin hata yakalaması gerekiyor.

Türkçe ve İngilizce kaynaklarda sık geçen iki hata bu tabloyla düzeliyor. 50.000 sonuç kesin bir tavan değil, varsayılan bir değer. 250 ise aynı anda çalışabilen değil, yetkilendirilebilen script sayısı. Bu sınırın hesap başına mı kullanıcı başına mı olduğu Google'ın sayfalarında farklı ifade ediliyor: limitler sayfası hesap başına, genel bakış sayfası kullanıcı başına diyor.

Hesap yönetiminde sık sorulan bir soru, dönüşüm getirmeden harcama yapan anahtar kelimelerin ne zaman incelenmesi gerektiği. Bu kararın eşiği marjdan çıkar. Başa baş dönüşüm başına maliyetin (CPA) nasıl hesaplandığı performans pazarlaması metrikleri yazısında anlatılıyor. Ama eşik başa baş CPA'ya eşit olursa, gerçekte iyi çalışan anahtar kelimeleri de sık sık işaretlersin.

Varsayımsal hesap: Bir anahtar kelimenin gerçek CPA'sı başa baş değerine eşit olsun ve dönüşümler birbirinden bağımsız gelsin. Bu durumda başa baş CPA'nın belirli bir katı kadar harcayıp hiç dönüşüm almama olasılığı yaklaşık olarak aşağıdaki gibi. Bu bir Poisson yaklaşımı ve tek bir kelimenin tek bir değerlendirmesi için geçerli.

Bu tablo bir durdurma kuralı değil, bir inceleme alarmının eşiği. Yüzlerce kelimeyi her gün kontrol edersen, yüzde 5'lik olasılıkla bile her gün birkaç sağlıklı kelime listeye girebilir. Günlük değerlendirme pencereleri birbiriyle örtüştüğü ve her kelime modeldeki koşulları sağlamadığı için bu sayı kesin değil. Gerçek hesaplarda dönüşümler mevsime ve güne göre de dalgalanır.

İki şey daha eşiği bozar. Birincisi dönüşüm gecikmesi. Google Ads dönüşüm verisinin hazır olması, Google'ın veri güncelliği sayfasına göre son tıklama modelinde 3 saate, diğer atıf modellerinde 15 saate kadar sürebiliyor. Ayrıca müşteri tıkladıktan günler sonra satın alabilir. Son günleri değerlendirmeye katarsan, dönüşümü henüz gelmemiş kelimeleri işaretlersin. Bu yüzden hesabındaki tıklamadan dönüşüme geçen süreye bak ve o kadar günü değerlendirme dışında bırak.

İkincisi dönüşümün ne olduğu. Bir form doldurma ile bir satış aynı CPA mantığıyla değerlendirilmez. Script'in saydığı dönüşüm, eşiği hesapladığın iş sonucuyla aynı olmalı. Hesapta farklı değerde birden çok dönüşüm varsa, eşiği hangi dönüşüme göre belirlediğini netleştir.

Aşağıdaki script, son 7 günü dışarıda bırakarak ondan önceki 30 günde hiç dönüşüm almamış ve eşikten fazla harcamış anahtar kelimeleri bulur. Kampanyası, reklam grubu ve kendisi etkin olan kelimelere bakar. Her satırı loga yazar ve önizleme modunda değilse sonucu e-mail ile gönderir. Hesapta hiçbir şeyi değiştirmez. Örnekte başa baş CPA 250 TL, eşik bunun üç katı olan 750 TL. Hariç tutulan 7 gün de örnek bir değer, kendi hesabının dönüşüm süresine göre değiştir. Örneğin script 5 Kasım'da çalışırsa 30 Eylül–29 Ekim aralığını sorgular, bugün dahil 30 Ekim–5 Kasım arasındaki 7 gün dışarıda kalır.

// Ayarlar
const ESIK = 750;          // başa baş CPA'nın üç katı (örnekte 250 TL × 3)
const GUN = 30;            // değerlendirilen gün sayısı
const HARIC_GUN = 7;       // dönüşümü henüz gelmemiş olabilecek son günler
const ALICI = 'ornek@alanadi.com';

function main() {
  const hesap = AdsApp.currentAccount();
  const saatDilimi = hesap.getTimeZone();
  const gunMs = 24 * 60 * 60 * 1000;
  const simdi = new Date();
  const bitis = Utilities.formatDate(
      new Date(simdi.getTime() - HARIC_GUN * gunMs), saatDilimi, 'yyyy-MM-dd');
  const baslangic = Utilities.formatDate(
      new Date(simdi.getTime() - (HARIC_GUN + GUN - 1) * gunMs), saatDilimi, 'yyyy-MM-dd');

  const sorgu =
    'SELECT campaign.name, ad_group.name, ad_group_criterion.criterion_id, ' +
    'ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ' +
    'metrics.cost_micros ' +
    'FROM keyword_view ' +
    `WHERE segments.date BETWEEN '${baslangic}' AND '${bitis}' ` +
    "AND campaign.status = 'ENABLED' " +
    "AND ad_group.status = 'ENABLED' " +
    "AND ad_group_criterion.status = 'ENABLED' " +
    'AND metrics.conversions = 0 ' +
    `AND metrics.cost_micros > ${ESIK * 1000000}`;

  const satirlar = [];
  for (const row of AdsApp.search(sorgu)) {
    const kelime = row.adGroupCriterion;
    const harcama = Number(row.metrics.costMicros) / 1000000;
    satirlar.push(
        `${row.campaign.name} > ${row.adGroup.name} > ${kelime.keyword.text} ` +
        `[${kelime.keyword.matchType}, ${kelime.criterionId}]: ${harcama.toFixed(2)}`);
  }

  const baslik = `${hesap.getName()} (${hesap.getCustomerId()}), ` +
      `${baslangic} / ${bitis}, eşik ${ESIK} ${hesap.getCurrencyCode()}`;
  console.log(`${baslik}: ${satirlar.length} anahtar kelime`);
  satirlar.forEach((satir) => console.log(satir));

  if (satirlar.length > 0 && !AdsApp.getExecutionInfo().isPreview()) {
    MailApp.sendEmail(ALICI, 'Dönüşümsüz harcama uyarısı',
        `${baslik}\n\n${satirlar.join('\n')}`);
  }
}

Bu örnek metrics.conversions metriğini kullanır ve belirli bir dönüşüm işlemini ayrıca seçmez. Bu metriğe dahil edilen dönüşümler, CPA eşiğini hesapladığın iş sonucuyla uyumlu olmalı.

Script, Google'ın başlangıç sayfasındaki AdsApp.search döngüsünü ve tarih sayfasındaki yöntemi kullanıyor. Tarihler hesabın saat diliminde hesaplanıyor, çünkü script'ler hesabın saat dilimi ne olursa olsun varsayılan olarak America/Los_Angeles saatini kullanıyor. Sorgudaki alanlar Google Ads API'nin keyword_view alan listesinde yer alıyor.

Script bu yazı için gerçek bir hesapta çalıştırılarak test edilmedi. Kendi hesabında önce önizlemeyle çalıştır ve loga yazılan satırları kontrol et. Eşiği belirlerken tıklama başına maliyeti (CPC) CPC hesaplayıcısıyla, dönüşüm oranını da dönüşüm oranı hesaplayıcısıyla kontrol edebilirsin.

Üretimde kullanmadan önce

Başlangıç script'i bir alarm üretir ama alarmın kendisini yönetmez. Günlük çalıştırmak saatlik e-mail yağmurunu önler, ama aynı kelimenin ertesi gün yeniden listeye girmesini engellemez. Bir kelimeyi inceleyip bilerek açık bıraktıysan, onu bir etiketle işaretleyip sorgudan çıkarman ya da daha önce gönderilen kelimeleri bir tabloda tutman gerekir.

"Sonuç yok" ile "script çalışmadı" da aynı şey değil. Script hiç kelime bulamadığında e-mail göndermez ve bu sessizlik, çalışmayan bir script'in sessizliğiyle karışabilir. Script'in çalıştığını Script geçmişi sayfasından izle ya da sonuç olmasa da kısa bir "sonuç yok" e-mail'i gönderen bir sürüm kullan.

Önizleme modu sanıldığı kadar güvenli değil. Önizlemede kampanya verisinde hiçbir değişiklik yapılmıyor, ama bu yalnızca AdsApp üzerinden yapılan çağrılar için geçerli. Diğer servisler normal çalışır, yani önizlemede bile e-mail gider ve Sheets'e yazılır. Yukarıdaki script e-mail göndermeden önce bu yüzden isPreview() ile önizlemede olup olmadığını kontrol ediyor.

Değişiklik yapan bir script yazıyorsan, önce değişiklikleri sadece loga yazan bir sürümünü çalıştır, sonra tek bir kampanyayla sınırla. Script değişiklikleri için kurallardaki gibi bir geri alma düğmesine güvenme. Bir bütçeyi ya da teklifi değiştirmeden önce eski değerini bir tabloya yaz, gerekirse aynı script'le ters işlemi yapabilirsin.

Script'ler senin adına çalışır. Script'ler kullanıcının adına işlem yapan bağımsız birimler ve kullanıcı oturum açmamışken de çalışabiliyor. Script'i yetkilendiren kişinin hesaba erişimi kaldırılırsa script durur ve erişimi olan biri tarafından yeniden yetkilendirilmesi gerekir. Ajans değişikliğinde ya da ekipten biri ayrıldığında script'ler bu yüzden sessizce durabilir.

Performance Max, Shopping ve video kampanyalarında dikkat

Bir script'in "tüm kampanyalar" dediği şey her zaman tüm kampanyalar değildir. Standart kampanya seçicisi AdsApp.campaigns(), limitler sayfasına göre video ve Shopping kampanyalarını sonuçlardan çıkarır. Bütçe ya da durum kontrolü yapan bir script, bu kampanyaları hiç görmeden "her şey yolunda" diyebilir.

Performance Max kampanyaları ayrı bir koleksiyondan, performanceMaxCampaigns() ile gelir ve görebileceğin reklam grubu ya da reklam nesneleri yoktur. Öğe grupları script içinde oluşturulamıyor, ama mevcut bir öğe grubuna öğe eklenip çıkarılabiliyor. Performance Max kampanyası oluşturmak ise yalnızca mutate ile mümkün. Performance Max'te anahtar kelime olmadığı için yukarıdaki başlangıç script'i bu kampanyaları kapsamaz.

Otomatik teklif stratejilerinde manuel teklif değiştiren eski script'lere de dikkat et. Anahtar kelimenin teklif stratejisi maksimum tıklama başına maliyet (TBM) teklifi kullanmıyorsa, setCpc değişikliği kullanılan stratejiye bağlı olarak gerçek teklifi etkilemeyebilir.

Birden fazla hesabı yöneten ajanslar ve ekipler script'i yönetici hesabında çalıştırabilir. Yönetici hesabı script'lerinde hesaplara AdsManagerApp.accounts() ile ulaşılıyor ve executeInParallel ile aynı anda en fazla 50 hesap işlenebiliyor. Bu durumda her hesap için 30 dakika süre var ve her hesabın döndürebileceği veri 10 MB ile sınırlı.

Tüm hesaplar bittiğinde çalışacak bir callback fonksiyonu tanımlarsan script'in toplam süresi 60 dakikaya çıkıyor. 50'den fazla hesabın varsa hesapları bir etiketle ya da koşulla gruplara ayırıp her grubu ayrı çalıştırman gerekir. Üst düzey yönetici hesabının oluşturduğu toplu işlemler yalnızca o hesapta görünüyor, alt yönetici ya da müşteri hesaplarında görünmüyor. Müşteri hesabına erişen biri, o hesapta çalışan script'i kendi listesinde görmeyebilir.

Eski bir script'i nasıl tanırsın

İnternette bulunan script'lerin önemli bir kısmı Google Ads'in eski sürümü için yazılmış. Türkçe ve İngilizce kaynaklarda hâlâ önerilen script'lerin bir kısmı artık çalışmıyor ya da yanlış veriyle çalışıyor. Bir script'i kopyalamadan önce şu işaretlere bak.

• AdWordsApp ya da MccApp adlarını kullanıyor. Güncel dokümanlar yalnızca AdsApp ve AdsManagerApp adlarını kullanıyor.
• Raporlarda KEYWORDS_PERFORMANCE_REPORT gibi eski rapor adları var. Bu eski sorgu dili teknik olarak hâlâ çalışıyor ama önerilmiyor.
• Ortalama pozisyona göre teklif veriyor. Google, Şubat 2019 tarihli duyurusunda ortalama pozisyonu aynı yılın eylül ayında kaldıracağını yazdı ve yerine üst ve en üst gösterim oranı metriklerini önerdi.
• Bağlı Google Sheets dosyasını herkese açık ve düzenlenebilir yapmanı istiyor. Dosyayı yalnızca script'i çalıştıran hesapla paylaşman yeterli.

Google'ın hazır script'leri

Kendi script'ini yazmadan önce Google'ın hazır çözümlerine bakmak zaman kazandırır. Aşağıdaki tablo bunları ve Google'ın her biri için önerdiği zamanlamayı gösteriyor.

Account Summary Report için önerilen saat önemli bir ayrıntıyı gösteriyor: Google Ads istatistikleri üç saate kadar gecikebiliyor. Gece yarısı çalışan bir günlük rapor, bir önceki günün son saatlerini eksik gösterebilir. Link Checker ise açılış sayfalarında hata veren linkleri bulur. Çalışan ama dönüştürmeyen sayfaları incelemek ayrı bir iş, dönüşüm oranı optimizasyonu rehberinde anlatılıyor. Ziyaretçinin açılış sayfasından ödemeye kadar hangi adımda kaybolduğunu huni analizi hesaplayıcısıyla görebilirsin.

Yapay zekâyla yazılmış bir script'i çalıştırmadan önce

Yapay zekâ araçları script yazmayı kolaylaştırıyor ama sık sık eski yöntem adları, var olmayan alanlar ya da yanlış birimler üretiyor. Bir script'i hesabında çalıştırmadan önce şu sırayı izle.

1. Kullanılan her nesne ve yöntem adını Google'ın referans dokümanında ara. Bulamadığın bir yöntemi kullanma.
2. GAQL sorgusundaki her alanı Google Ads API'nin alan listesinde kontrol et ve hangi alanların mikro birimde geldiğine bak.
3. Script'i önizlemede çalıştır ve önizlemede de e-mail gönderip Sheets'e yazdığını hesaba kat.
4. Değişiklik yapan kısmı önce yalnızca loga yazacak şekilde çalıştır, sonra tek bir kampanyayla sınırla.
5. Değiştireceğin her değerin eski hâlini bir tabloya yaz, böylece gerekirse ters işlemi yapabilirsin.
6. Script'in etkisini ölçmek istiyorsan, değişikliği uygulamadığın bir karşılaştırma grubu tut. Bunun nasıl kurulduğu kontrol grubu yazısında anlatılıyor.

Script'ler, kuralların yetmediği yerde güçlü bir araç. Ama bir script'i hesabına eklerken onu bir kod parçası değil, senin adına karar veren bir ekip arkadaşı gibi düşün. Ne yaptığını, hangi verilere baktığını, neyi göremediğini ve yanlış alarm ürettiği durumları bilmen gerekir.