Praktik Terbaik

Halaman ini membahas berbagai praktik terbaik untuk pengembangan dengan skrip Google Ads.

Pemilih

Memfilter dengan pemilih

Jika memungkinkan, gunakan filter untuk meminta hanya entity yang Anda butuhkan. Menerapkan filter yang tepat memiliki manfaat berikut:

• Kode ini lebih sederhana dan lebih mudah dipahami.
• Skrip akan dijalankan jauh lebih cepat.

Bandingkan cuplikan kode berikut:

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 10')
    .forDateRange('LAST_MONTH')
    .get();
while (keywords.hasNext()) {
  var keyword = keywords.next();
  // Do work here.
}

var keywords = AdsApp.keywords().get();

while (keywords.hasNext()) {
  var keyword = keywords.next();
  var stats = keyword.getStatsFor(
      'LAST_MONTH');
  if (stats.getClicks() > 10) {
    // Do work here.
  }
}

Pendekatan kedua tidak direkomendasikan karena mencoba mengambil daftar semua kata kunci di akun Anda hanya untuk menerapkan filter ke daftar tersebut.

Menghindari penelusuran hierarki kampanye

Jika Anda ingin mengambil entity pada tingkat tertentu, gunakan metode pengumpulan pada tingkat tersebut, bukan menelusuri seluruh hierarki kampanye. Selain lebih sederhana, cara ini juga akan berperforma jauh lebih baik: sistem tidak perlu membaca semua kampanye dan grup iklan secara tidak perlu.

Bandingkan cuplikan kode berikut yang mengambil semua iklan di akun Anda:

var ads = AdsApp.ads();

var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var adGroups = campaigns.next().
      adGroups().get();
  while (adGroups.hasNext()) {
    var ads = adGroups.next().ads().get();
    // Do your work here.
  }
}

Pendekatan kedua tidak direkomendasikan karena mencoba mengambil seluruh hierarki objek (kampanye, grup iklan) padahal hanya iklan yang diperlukan.

Menggunakan metode pengakses induk tertentu

Terkadang Anda perlu mendapatkan entity induk dari objek yang diambil. Dalam hal ini, Anda harus menggunakan metode pengakses yang disediakan, bukan mengambil seluruh hierarki.

Bandingkan cuplikan kode berikut yang mengambil grup iklan yang memiliki iklan teks dengan lebih dari 50 klik bulan lalu:

var ads = AdsApp.ads()
    .withCondition('Clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();

while (ads.hasNext()) {
  var ad = ads.next();
  var adGroup = ad.getAdGroup();
  var campaign = ad.getCampaign();
  // Store (campaign, adGroup) to an array.
}

var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var adGroups = campaigns.next()
      .adGroups()
      .get();
  while (adGroups.hasNext()) {
    var ads = adGroups.ads()
       .withCondition('Clicks > 50')
       .forDateRange('LAST_MONTH')
       .get();
    if (ads.totalNumEntities() > 0) {
      // Store (campaign, adGroup) to an array.
    }
  }
}

Pendekatan kedua tidak direkomendasikan karena mengambil seluruh hierarki kampanye dan grup iklan di akun Anda, padahal Anda hanya memerlukan sebagian kecil kampanye dan grup iklan yang terkait dengan kumpulan iklan Anda. Pendekatan pertama membatasi dirinya untuk mengambil hanya kumpulan iklan yang relevan, dan menggunakan metode yang sesuai untuk mengakses objek induknya.

Menggunakan filter induk tertentu

Untuk mengakses entitas dalam kampanye atau grup iklan tertentu, gunakan filter tertentu di pemilih, bukan mengambil lalu menjelajahi hierarki.

Bandingkan cuplikan kode berikut yang mengambil daftar iklan teks dalam kampanye dan grup iklan tertentu yang memiliki lebih dari 50 klik bulan lalu.

var ads = AdsApp.ads()
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .withCondition('Clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();

while (ads.hasNext()) {
  var ad = ads.next();
  var adGroup = ad.getAdGroup();
  var campaign = ad.getCampaign();
  // Store (campaign, adGroup, ad) to
  // an array.
}

var campaigns = AdsApp.campaigns()
    .withCondition('Name = "Campaign 1"')
    .get();

while (campaigns.hasNext()) {
  var adGroups = campaigns.next()
      .adGroups()
      .withCondition('Name = "AdGroup 1"')
      .get();
  while (adGroups.hasNext()) {
    var ads = adGroups.ads()
       .withCondition('Clicks > 50')
       .forDateRange('LAST_MONTH')
       .get();
    while (ads.hasNext()) {
      var ad = ads.next();
      // Store (campaign, adGroup, ad) to
      // an array.
    }
  }
}

Pendekatan kedua tidak direkomendasikan karena melakukan iterasi pada hierarki kampanye dan grup iklan di akun Anda, padahal Anda hanya memerlukan kumpulan iklan tertentu serta kampanye dan grup iklan induknya. Pendekatan pertama membatasi iterasi ke daftar iklan dengan menerapkan filter tertentu untuk entity induk pada pemilih.

Gunakan ID untuk pemfilteran jika memungkinkan

Saat memfilter entity, sebaiknya filter entity berdasarkan ID-nya, bukan kolom lain.

Perhatikan cuplikan kode berikut yang memilih kampanye.

var campaign = AdsApp.campaigns()
    .withIds([12345])
    .get()
    .next();

var campaign = AdsApp.campaigns()
    .withCondition('Name="foo"')
    .get()
    .next();

Pendekatan kedua kurang optimal karena kita memfilter menurut kolom non-ID.

Filter menurut ID induk jika memungkinkan

Saat memilih entity, filter menurut ID induk jika memungkinkan. Tindakan ini akan membuat kueri Anda lebih cepat dengan membatasi daftar entity yang diambil oleh server saat memfilter hasil.

Pertimbangkan cuplikan kode berikut yang mengambil AdGroup berdasarkan ID-nya. Asumsikan bahwa ID kampanye induk diketahui.

var adGroup = AdsApp.adGroups()
    .withIds([12345])
    .withCondition('CampaignId="54678"')
    .get()
    .next();

var adGroup = AdsApp.adGroups()
    .withIds([12345])
    .get()
    .next();

Meskipun kedua cuplikan kode memberikan hasil yang sama, pemfilteran tambahan dalam cuplikan kode 1 menggunakan ID induk (CampaignId="54678") membuat kode lebih efisien dengan membatasi daftar entity yang harus diiterasi server saat memfilter hasil.

Gunakan label jika ada terlalu banyak kondisi pemfilteran

Jika Anda memiliki terlalu banyak kondisi pemfilteran, sebaiknya buat label untuk entitas yang Anda proses, dan gunakan label tersebut untuk memfilter entitas Anda.

Pertimbangkan cuplikan kode berikut yang mengambil daftar kampanye berdasarkan namanya.

var label = AdsApp.labels()
    .withCondition('Name = "My Label"')
    .get()
    .next();
var campaigns = label.campaigns.get();
while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  // Do more work
}

var campaignNames = ['foo', 'bar', 'baz'];

for (var i = 0; i < campaignNames.length; i++) {
  campaignNames[i] = '"' + campaignNames[i] + '"';
}

var campaigns = AdsApp.campaigns
    .withCondition('CampaignName in [' + campaignNames.join(',') + ']')
    .get();

while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  // Do more work.
}

Meskipun kedua cuplikan kode memberikan tingkat performa yang serupa, pendekatan kedua cenderung menghasilkan kode yang lebih kompleks seiring bertambahnya jumlah kondisi dalam pemilih Anda. Menerapkan label ke entity baru juga lebih mudah daripada mengedit skrip untuk menyertakan entity baru.

Membatasi jumlah kondisi dalam klausa IN

Saat menjalankan skrip, kasus penggunaan yang umum adalah menjalankan laporan untuk daftar entitas. Developer biasanya melakukannya dengan membuat kueri GAQL yang sangat panjang yang memfilter ID entitas menggunakan klausa IN. Pendekatan ini berfungsi dengan baik jika jumlah entitas terbatas. Namun, seiring bertambahnya panjang kueri, performa skrip Anda akan menurun karena dua alasan:

• Kueri yang lebih panjang memerlukan waktu lebih lama untuk diuraikan.
• Setiap ID yang Anda tambahkan ke klausa IN adalah kondisi tambahan yang harus dievaluasi, sehingga memerlukan waktu lebih lama.

Dalam kondisi seperti ini, sebaiknya terapkan label ke entitas, lalu filter menurut LabelId.

// The label applied to the entity is "Report Entities"
var label = AdsApp.labels()
    .withCondition('LabelName contains "Report Entities"')
    .get()
    .next();

var report = AdsApp.report('SELECT AdGroupId, Id, Clicks, ' +
    'Impressions, Cost FROM KEYWORDS_PERFORMANCE_REPORT ' +
    'WHERE LabelId = "' + label.getId() + '"');

var report = AdsApp.report('SELECT AdGroupId, Id, Clicks, ' +
    'Impressions, Cost FROM KEYWORDS_PERFORMANCE_REPORT WHERE ' +
    'AdGroupId IN (123, 456) and Id in (123,345, 456…)');

Pemberitahuan akun

Perubahan batch

Saat Anda melakukan perubahan pada entity Google Ads, skrip Google Ads tidak akan langsung mengeksekusi perubahan tersebut. Sebagai gantinya, API mencoba menggabungkan beberapa perubahan ke dalam batch, sehingga dapat mengeluarkan satu permintaan yang melakukan beberapa perubahan. Pendekatan ini membuat skrip Anda lebih cepat dan mengurangi beban pada server Google Ads. Namun, ada beberapa pola kode yang memaksa skrip Google Ads untuk sering menghapus batch operasinya, sehingga menyebabkan skrip Anda berjalan lambat.

Pertimbangkan skrip berikut yang memperbarui bid daftar kata kunci.

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 50')
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .forDateRange('LAST_MONTH')
    .get();

var list = [];
while (keywords.hasNext()) {
  var keyword = keywords.next();
  keyword.bidding().setCpc(1.5);
  list.push(keyword);
}

for (var i = 0; i < list.length; i++) {
  var keyword = list[i];
  Logger.log('%s, %s', keyword.getText(),
      keyword.bidding().getCpc());
}

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 50')
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .forDateRange('LAST_MONTH')
    .get();

while (keywords.hasNext()) {
  var keyword = keywords.next();
  keyword.bidding().setCpc(1.5);
  Logger.log('%s, %s', keyword.getText(),
      keyword.bidding().getCpc());
}

Pendekatan kedua tidak direkomendasikan karena panggilan ke keyword.bidding().getCpc() memaksa skrip Google Ads untuk menghapus operasi setCpc() dan hanya menjalankan satu operasi dalam satu waktu. Pendekatan pertama, meskipun mirip dengan pendekatan kedua, memiliki manfaat tambahan dalam mendukung pengelompokan karena panggilan getCpc() dilakukan dalam loop terpisah dari loop tempat setCpc() dipanggil.

Gunakan builder jika memungkinkan

Skrip Google Ads mendukung dua cara untuk membuat objek baru—builder dan metode pembuatan. Builder lebih fleksibel daripada metode pembuatan, karena memberi Anda akses ke objek yang dibuat dari panggilan API.

Pertimbangkan cuplikan kode berikut:

var operation = adGroup.newKeywordBuilder()
    .withText('shoes')
    .build();
var keyword = operation.getResult();

adGroup.createKeyword('shoes');
var keyword = adGroup.keywords()
    .withCondition('KeywordText="shoes"')
    .get()
    .next();

Pendekatan kedua tidak disarankan karena operasi pemilihan tambahan yang terlibat dalam pengambilan kata kunci. Selain itu, metode pembuatan juga tidak digunakan lagi.

Namun, perlu diingat bahwa builder, jika digunakan secara tidak benar, dapat mencegah skrip Google Ads mengelompokkan operasinya.

Pertimbangkan cuplikan kode berikut yang membuat daftar kata kunci dan mencetak ID kata kunci yang baru dibuat:

var keywords = ['foo', 'bar', 'baz'];

var list = [];
for (var i = 0; i < keywords.length; i++) {
  var operation = adGroup.newKeywordBuilder()
      .withText(keywords[i])
      .build();
  list.push(operation);
}

for (var i = 0; i < list.length; i++) {
  var operation = list[i];
  var result = operation.getResult();
  Logger.log('%s %s', result.getId(),
      result.getText());
}

var keywords = ['foo', 'bar', 'baz'];

for (var i = 0; i < keywords.length; i++) {
  var operation = adGroup.newKeywordBuilder()
      .withText(keywords[i])
      .build();
  var result = operation.getResult();
  Logger.log('%s %s', result.getId(),
      result.getText());
}

Pendekatan kedua tidak direkomendasikan karena memanggil operation.getResult() dalam loop yang sama yang membuat operasi, sehingga memaksa skrip Google Ads mengeksekusi satu operasi dalam satu waktu. Pendekatan pertama, meskipun serupa, memungkinkan pengelompokan karena kita memanggil operation.getResult() dalam loop yang berbeda dari tempat operasi tersebut dibuat.

Pertimbangkan untuk menggunakan upload massal untuk pembaruan dalam jumlah besar

Tugas umum yang dilakukan developer adalah menjalankan laporan dan memperbarui properti entitas (misalnya, bid kata kunci) berdasarkan nilai performa saat ini. Jika Anda harus memperbarui sejumlah besar entity, upload massal cenderung memberikan performa yang lebih baik. Misalnya, pertimbangkan skrip berikut yang meningkatkan MaxCpc kata kunci yang TopImpressionPercentage > 0.4-nya selama sebulan terakhir:

var report = AdsApp.report(
  'SELECT AdGroupId, Id, CpcBid FROM KEYWORDS_PERFORMANCE_REPORT ' +
  'WHERE TopImpressionPercentage > 0.4 DURING LAST_MONTH');

var upload = AdsApp.bulkUploads().newCsvUpload([
  report.getColumnHeader('AdGroupId').getBulkUploadColumnName(),
  report.getColumnHeader('Id').getBulkUploadColumnName(),
  report.getColumnHeader('CpcBid').getBulkUploadColumnName()]);
upload.forCampaignManagement();

var reportRows = report.rows();
while (reportRows.hasNext()) {
  var row = reportRows.next();
  row['CpcBid'] = row['CpcBid'] + 0.02;
  upload.append(row.formatForUpload());
}

upload.apply();

var reportRows = AdsApp.report('SELECT AdGroupId, Id, CpcBid FROM ' +
    'KEYWORDS_PERFORMANCE_REPORT WHERE TopImpressionPercentage > 0.4 ' +
    ' DURING LAST_MONTH')
    .rows();

var map = {
};

while (reportRows.hasNext()) {
  var row = reportRows.next();
  var adGroupId = row['AdGroupId'];
  var id = row['Id'];

  if (map[adGroupId] == null) {
    map[adGroupId] = [];
  }
  map[adGroupId].push([adGroupId, id]);
}

for (var key in map) {
  var keywords = AdsApp.keywords()
      .withCondition('AdGroupId="' + key + '"')
      .withIds(map[key])
      .get();

  while (keywords.hasNext()) {
    var keyword = keywords.next();
    keyword.bidding().setCpc(keyword.bidding().getCpc() + 0.02);
  }
}

Meskipun pendekatan kedua memberikan performa yang cukup baik, pendekatan pertama lebih disukai dalam kasus ini karena

• Skrip Google Ads memiliki batasan jumlah objek yang dapat diambil atau diperbarui dalam satu kali proses, dan operasi pemilihan serta pembaruan dalam pendekatan kedua dihitung dalam batas tersebut.

• Upload massal memiliki batas yang lebih tinggi, baik dalam hal jumlah entitas yang dapat diperbarui maupun waktu eksekusi keseluruhan.

Mengelompokkan upload massal menurut kampanye

Saat membuat upload massal, coba kelompokkan operasi menurut kampanye induk. Hal ini meningkatkan efisiensi dan mengurangi kemungkinan perubahan yang bertentangan / error konkurensi.

Pertimbangkan dua tugas upload massal yang berjalan secara paralel. Satu skrip menjeda iklan di grup iklan; skrip lainnya menyesuaikan bid kata kunci. Meskipun tidak terkait, operasi tersebut dapat berlaku untuk entity dalam grup iklan yang sama (atau dua grup iklan yang berbeda dalam kampanye yang sama). Jika hal ini terjadi, sistem akan mengunci parent entity (grup iklan atau kampanye bersama), sehingga menyebabkan tugas upload massal saling memblokir.

Skrip Google Ads dapat mengoptimalkan eksekusi dalam satu tugas upload massal, jadi hal paling sederhana yang dapat dilakukan adalah menjalankan hanya satu tugas upload massal per akun dalam satu waktu. Jika Anda memutuskan untuk menjalankan lebih dari satu upload massal per akun, pastikan upload massal beroperasi pada daftar kampanye yang saling eksklusif (dan entitas turunannya) untuk performa yang optimal.

Pelaporan

Menggunakan laporan untuk mengambil statistik

Jika Anda ingin mengambil sejumlah besar entitas dan statistiknya, sebaiknya gunakan laporan, bukan metode AdsApp standar. Penggunaan laporan lebih disukai karena alasan berikut:

• Laporan memberi Anda performa yang lebih baik untuk kueri besar.
• Laporan tidak akan mencapai kuota pengambilan normal.

Bandingkan cuplikan kode berikut yang mengambil Klik, Tayangan Iklan, Biaya, dan Teks semua kata kunci yang menerima lebih dari 50 klik bulan lalu:

  report = AdsApp.search(
      'SELECT ' +
      '   ad_group_criterion.keyword.text, ' +
      '   metrics.clicks, ' +
      '   metrics.cost_micros, ' +
      '   metrics.impressions ' +
      'FROM ' +
      '   keyword_view ' +
      'WHERE ' +
      '   segments.date DURING LAST_MONTH ' +
      '   AND metrics.clicks > 50');
  while (report.hasNext()) {
    var row = report.next();
    Logger.log('Keyword: %s Impressions: %s ' +
        'Clicks: %s Cost: %s',
        row.adGroupCriterion.keyword.text,
        row.metrics.impressions,
        row.metrics.clicks,
        row.metrics.cost);
  }

var keywords = AdsApp.keywords()
    .withCondition('metrics.clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();
while (keywords.hasNext()) {
  var keyword = keywords.next();
  var stats = keyword.getStatsFor('LAST_MONTH');
  Logger.log('Keyword: %s Impressions: %s ' +
      'Clicks: %s Cost: %s',
      keyword.getText(),
      stats.getImpressions(),
      stats.getClicks(),
      stats.getCost());
}

Pendekatan kedua tidak disarankan karena melakukan iterasi pada kata kunci dan mengambil statistik satu entity dalam satu waktu. Dalam hal ini, laporan akan berjalan lebih cepat karena mengambil semua data dalam satu panggilan dan mengalirkannya sesuai kebutuhan. Selain itu, kata kunci yang diambil dalam pendekatan kedua dihitung dalam kuota skrip Anda untuk jumlah entitas yang diambil menggunakan panggilan get().

Menggunakan penelusuran, bukan laporan

Metode laporan dibuat untuk infrastruktur lama, dan akan menampilkan hasil dalam format datar meskipun Anda menggunakan GAQL. Artinya, API harus mengubah hasil kueri agar sesuai dengan gaya lama, yang tidak didukung untuk semua kolom dan menambah overhead pada setiap panggilan.

Sebaiknya gunakan penelusuran untuk memanfaatkan semua fitur pelaporan Google Ads API baru.

Lebih memilih GAQL daripada AWQL

Meskipun secara teknis AWQL masih berfungsi untuk kueri laporan dan panggilan withCondition, hal ini tidak direkomendasikan. Untuk memiliki kontrol penuh atas kueri, pastikan Anda menggunakan GAQL.

Jangan pilih baris lebih banyak dari yang Anda perlukan

Kecepatan eksekusi laporan (dan pemilih) didasarkan pada jumlah total baris yang akan ditampilkan oleh laporan, terlepas dari apakah Anda melakukan iterasi pada baris tersebut atau tidak. Artinya, Anda harus selalu menggunakan filter tertentu untuk meminimalkan kumpulan hasil sebanyak mungkin agar sesuai dengan kasus penggunaan Anda.

Misalnya, Anda ingin menemukan grup iklan dengan bid di luar rentang tertentu. Akan lebih cepat untuk membuat dua kueri terpisah, satu untuk bid di bawah nilai minimum bawah dan satu lagi untuk bid di atas nilai minimum atas, daripada mengambil semua grup iklan dan mengabaikan grup iklan yang tidak Anda minati.

var adGroups = []
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group WHERE ad_group.cpc_bid_micros < 1000000');

while (report.hasNext()) {
  var row = report.next();
  adGroups.push(row.adGroup);
}
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group WHERE ad_group.cpc_bid_micros > 2000000');

while (report.hasNext()) {
  var row = report.next();
  adGroups.push(row.adGroup);
}

var adGroups = []
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group');

while (report.hasNext()) {
  var row = report.next();
  var cpcBidMicros = row.adGroup.cpcBidMicros;
  if (cpcBidMicros < 1000000 || cpcBidMicros > 2000000) {
    adGroups.push(row.adGroup);
  }
}

Skrip Pengelola Google Ads (MCC)

Lebih memilih executeInParallel daripada eksekusi serial

Saat menulis skrip untuk akun pengelola, gunakan executeInParallel(), bukan eksekusi serial jika memungkinkan. executeInParallel() memberi skrip Anda lebih banyak waktu pemrosesan (hingga satu jam) dan hingga 30 menit per akun yang diproses (bukan 30 menit gabungan untuk eksekusi serial). Lihat halaman batas kami untuk mengetahui detail selengkapnya.

Spreadsheet

Menggunakan operasi batch saat memperbarui spreadsheet

Saat memperbarui spreadsheet, coba gunakan metode operasi massal (misalnya, getRange()) daripada metode yang memperbarui satu sel dalam satu waktu.

Pertimbangkan cuplikan kode berikut yang menghasilkan pola fraktal pada spreadsheet.

var colors = new Array(100);
for (var y = 0; y < 100; y++) {
  xcoord = xmin;
  colors[y] = new Array(100);
  for (var x = 0; x < 100; x++) {
    colors[y][x] = getColor_(xcoord, ycoord);
    xcoord += xincrement;
  }
  ycoord -= yincrement;
}
sheet.getRange(1, 1, 100, 100).setBackgroundColors(colors);

var cell = sheet.getRange('a1');
for (var y = 0; y < 100; y++) {
  xcoord = xmin;
  for (var x = 0; x < 100; x++) {
    var c = getColor_(xcoord, ycoord);
    cell.offset(y, x).setBackgroundColor(c);
    xcoord += xincrement;
  }
  ycoord -= yincrement;
  SpreadsheetApp.flush();
}

Meskipun Spreadsheet Google mencoba mengoptimalkan cuplikan kode kedua dengan meng-cache nilai, performanya masih buruk dibandingkan dengan cuplikan pertama, karena jumlah panggilan API yang dilakukan.