Programmable Search Element Control API

Anda dapat menyematkan komponen Programmable Search Engine (kotak penelusuran dan halaman hasil penelusuran) di halaman web dan aplikasi web lainnya menggunakan markup HTML. Elemen Programmable Search Engine ini terdiri dari komponen yang dirender berdasarkan setelan yang disimpan oleh server Programmable Search, beserta penyesuaian yang Anda lakukan.

Semua JavaScript dimuat secara asinkron, yang memungkinkan halaman web Anda terus dimuat saat browser mengambil JavaScript Programmable Search Engine.

Pengantar

Dokumen ini memberikan model dasar untuk menambahkan elemen Programmable Search Engine ke halaman web Anda, beserta penjelasan tentang komponen elemen yang dapat dikonfigurasi dan JavaScript API yang fleksibel.

Cakupan

Dokumen ini menjelaskan cara menggunakan fungsi dan properti khusus untuk Programmable Search Engine Control API.

Kompatibilitas browser

Daftar browser yang didukung oleh Programmable Search Engine dapat ditemukan di sini.

Audiens

Dokumentasi ini ditujukan bagi developer yang ingin menambahkan fungsi Google Programmable Search ke halaman mereka.

Elemen Programmable Search

Anda dapat menggunakan markup HTML untuk menambahkan Elemen Programmable Search ke halaman Anda. Setiap elemen terdiri dari minimal satu komponen: kotak penelusuran, blok hasil penelusuran, atau keduanya. Kotak penelusuran menerima input pengguna dengan cara berikut:

  • Kueri penelusuran yang diketik di kolom input teks
  • String kueri yang disematkan dalam URL
  • Eksekusi terprogram

Selain itu, blok hasil penelusuran menerima input dengan cara berikut:

  • String kueri yang disematkan dalam URL
  • Eksekusi terprogram

Jenis Elemen Penelusuran Terprogram berikut tersedia:

Jenis elemen Komponen Deskripsi
standar <div class="gcse-search"> Kotak penelusuran dan hasil penelusuran, ditampilkan di <div> yang sama.
dua kolom <div class="gcse-searchbox"> dan <div class="gcse-searchresults"> Tata letak dua kolom dengan hasil penelusuran di satu sisi dan kotak penelusuran di sisi lainnya. Jika Anda berencana menyisipkan beberapa elemen dalam mode dua kolom di halaman web, Anda dapat menggunakan atribut gname untuk memasangkan kotak penelusuran dengan blok hasil penelusuran.
khusus kotak penelusuran <div class="gcse-searchbox-only"> Kotak penelusuran mandiri.
searchresults-only <div class="gcse-searchresults-only"> Blok hasil penelusuran mandiri.

Anda dapat menambahkan sejumlah Elemen Penelusuran yang valid ke halaman web Anda. Untuk mode dua kolom, semua komponen yang diperlukan (kotak penelusuran dan blok hasil penelusuran) harus ada.

Berikut adalah contoh Elemen Penelusuran sederhana:

<!-- Put the following javascript before the closing </head> tag
and replace 123456 with your own Programmable Search Engine ID. -->
<script async src="https://cse.google.com/cse.js?cx=123456"></script>

<!-- Place this tag where you want both of the search box and the search results to render -->
<div class="gcse-search"></div>

Menyusun berbagai opsi tata letak menggunakan Elemen Programmable Search

Opsi tata letak berikut tersedia di halaman Tampilan dan Nuansa pada panel kontrol Mesin Telusur Programmable. Berikut adalah beberapa pedoman umum tentang menyusun opsi tata letak menggunakan Elemen Penelusuran yang Dapat Diprogram. Untuk melihat demo salah satu opsi ini, klik link tersebut.

Opsi Komponen
Lebar penuh <div class="gcse-search">
Ringkas <div class="gcse-search">
Dua kolom <div class="gcse-searchbox">, <div class="gcse-searchresults">
Dua halaman <div class="gcse-searchbox-only"> di halaman pertama, <div class="gcse-searchresults-only"> (atau komponen lain) di halaman kedua.
Hasil saja <div class="gcse-searchresults-only">
Dihosting Google <div class="gcse-searchbox-only">

Informasi selengkapnya tentang opsi tata letak.

Menyesuaikan Elemen Programmable Search

Untuk menyesuaikan warna, font, atau gaya link, buka halaman Tampilan dan Nuansa mesin telusur yang dapat diprogram.

Anda dapat menggunakan atribut opsional untuk mengganti konfigurasi yang dibuat di panel kontrol Programmable Search Engine. Hal ini memungkinkan Anda membuat pengalaman penelusuran khusus halaman. Misalnya, kode berikut membuat kotak penelusuran yang membuka halaman hasil (http://www.example.com?search=lady+gaga) di jendela baru. Nilai atribut queryParameterName, beserta string kueri pengguna, digunakan untuk membuat URL hasil.

Perhatikan bahwa atribut queryParameterName diawali dengan data-. Awalan ini diperlukan untuk semua atribut.

<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">

Jika Anda telah menggunakan panel kontrol Programmable Search Engine untuk mengaktifkan fitur seperti pelengkapan otomatis atau penyempurnaan, Anda dapat menggunakan atribut untuk menyesuaikan fitur tersebut. Setiap penyesuaian yang Anda tentukan menggunakan atribut ini akan menggantikan setelan yang dibuat di panel kontrol. Contoh berikut membuat Elemen Penelusuran dua kolom dengan fitur berikut:

  • Pengelolaan histori diaktifkan
  • Jumlah maksimum pelengkapan otomatis yang ditampilkan ditetapkan ke 5
  • Penyempurnaan ditampilkan sebagai link.

<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5">
<div class="gcse-searchresults" data-refinementStyle="link">

Atribut yang didukung

Atribut Jenis Deskripsi Komponen
Umum
gname String (Opsional) Nama untuk objek Elemen Penelusuran. Nama digunakan untuk mengambil komponen terkait berdasarkan nama, atau untuk menyambungkan komponen searchbox dengan komponen searchresults. Jika tidak diberikan, Programmable Search Engine akan otomatis membuat gname, berdasarkan urutan komponen di halaman web. Misalnya, searchbox-only tanpa nama pertama memiliki gname "searchbox-only0", dan yang kedua memiliki gname "searchbox-only1", dan seterusnya. Perhatikan bahwa gname yang dibuat secara otomatis untuk komponen dalam tata letak dua kolom akan menjadi two-column. Contoh berikut menggunakan gname storesearch untuk menautkan komponen searchbox dengan komponen searchresults: 
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

Saat mengambil objek, jika lebih dari satu komponen memiliki gname yang sama, Programmable Search Engine akan menggunakan komponen terakhir di halaman.

 Semua
autoSearchOnLoad Boolean Menentukan apakah akan menjalankan penelusuran berdasarkan kueri yang disematkan di URL halaman yang sedang dimuat. Perhatikan bahwa string kueri harus ada di URL untuk menjalankan penelusuran otomatis. Default: true. Semua
enableHistory Boolean Jika true, mengaktifkan pengelolaan histori untuk tombol Kembali dan Maju browser. Lihat demo.

kotak penelusuran

khusus kotak penelusuran
queryParameterName String Nama parameter kueri—misalnya, q (default) atau query. Ini akan disematkan di URL (misalnya, http://www.example.com?q=lady+gaga). Perhatikan bahwa hanya menentukan nama parameter kueri saja tidak akan memicu penelusuran otomatis saat pemuatan. String kueri harus ada di URL untuk menjalankan penelusuran otomatis. Semua
resultsUrl URL URL halaman hasil. (Defaultnya adalah halaman yang dihosting Google.) khusus kotak penelusuran
newWindow Boolean Menentukan apakah halaman hasil terbuka di jendela baru. Default: false. khusus kotak penelusuran
ivt Boolean

Parameter ini memungkinkan Anda memberikan nilai boolean yang memberi tahu Google bahwa Anda ingin mengizinkan iklan yang menggunakan penyimpanan lokal & cookie khusus traffic tidak valid di traffic dengan izin cookie dan tanpa izin cookie.

true Jika parameter ini tidak ada atau Anda menyetelnya ke "true", kami akan menyetel cookie khusus traffic tidak valid dan menggunakan penyimpanan lokal hanya pada traffic yang memiliki izin cookie.

false Jika Anda menyetel parameter ini ke "false", kami akan menyetel cookie khusus traffic tidak valid dan menggunakan penyimpanan lokal di traffic dengan izin cookie dan tanpa izin cookie.

Default: false

Contoh penggunaan: <div class="gcse-search" data-ivt="true"></div>

hasil penelusuran

searchresults-only
mobileLayout String

Menentukan apakah gaya tata letak seluler harus digunakan untuk perangkat seluler.

enabled Menggunakan tata letak seluler hanya untuk perangkat seluler.

disabled Tidak menggunakan tata letak seluler untuk perangkat apa pun.

forced Menggunakan tata letak seluler untuk semua perangkat.

Default: enabled

Contoh penggunaan: <div class="gcse-search" data-mobileLayout="disabled"></div>

Semua
Pelengkapan Otomatis
enableAutoComplete Boolean Hanya tersedia jika pelengkapan otomatis telah diaktifkan di panel kontrol Programmable Search Engine. true mengaktifkan pelengkapan otomatis. Semua
autoCompleteMaxCompletions Bilangan bulat Jumlah maksimum pelengkapan otomatis yang akan ditampilkan.

kotak penelusuran

khusus kotak penelusuran
autoCompleteMaxPromotions Bilangan bulat Jumlah maksimum promosi yang akan ditampilkan dalam pelengkapan otomatis.

kotak penelusuran

khusus kotak penelusuran
autoCompleteValidLanguages String Daftar bahasa yang dipisahkan koma yang harus mengaktifkan pelengkapan otomatis. Bahasa yang didukung.

kotak penelusuran

khusus kotak penelusuran
Penyempurnaan
defaultToRefinement String Hanya tersedia jika penyesuaian telah dibuat di panel kontrol Programmable Search Engine. Menentukan label penyesuaian default yang akan ditampilkan.Catatan: Atribut ini tidak didukung untuk tata letak yang Dihosting Google. Semua
refinementStyle String Nilai yang dapat diterima adalah tab (default) dan link. link hanya didukung jika penelusuran gambar dinonaktifkan, atau jika penelusuran gambar diaktifkan, tetapi penelusuran web dinonaktifkan.

hasil penelusuran

searchresults-only
Penelusuran gambar
enableImageSearch Boolean Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Jika true, mengaktifkan penelusuran gambar. Hasil gambar akan ditampilkan di tab terpisah.

hasil penelusuran

searchresults-only
defaultToImageSearch Boolean Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Jika true, halaman hasil penelusuran akan menampilkan hasil penelusuran gambar secara default. Hasil web akan tersedia di tab terpisah.

Semua
imageSearchLayout String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Menentukan tata letak halaman hasil penelusuran gambar. Nilai yang dapat diterima adalah classic, column, atau popup.

hasil penelusuran

searchresults-only
imageSearchResultSetSize Integer, String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Menentukan ukuran maksimum set hasil penelusuran untuk penelusuran gambar. Misalnya, large, small, filtered_cse, 10.

 Semua
image_as_filetype String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Membatasi hasil ke file dengan ekstensi yang ditentukan.

Ekstensi yang didukung adalah jpg, gif, png, bmp, svg, webp, ico, raw.

Semua
image_as_oq String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Memfilter hasil penelusuran menggunakan Logika OR.

Contoh penggunaan jika Anda menginginkan hasil penelusuran yang menyertakan "term1" atau "term2":<div class="gcse-search" data-image_as_oq="term1 term2"></div>

Semua
image_as_rights String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Filter berdasarkan pemberian lisensi.

Nilai yang didukung adalah cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived, dan kombinasi nilai tersebut.

Lihat kombinasi umum.

Semua
image_as_sitesearch String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Membatasi hasil ke halaman dari situs tertentu.

Contoh penggunaan: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

Semua
image_colortype String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Membatasi penelusuran ke gambar hitam putih (mono), skala abu-abu, atau berwarna. Nilai yang didukung adalah mono, gray, color.

Semua
image_cr String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Membatasi hasil penelusuran pada dokumen yang berasal dari negara tertentu.

Nilai yang didukung

Semua
image_dominantcolor String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Membatasi penelusuran pada gambar dengan warna dominan tertentu. Nilai yang didukung adalah red, orange, yellow, green, teal, blue, purple, pink, white, gray, black, brown.

Semua
image_filter String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Pemfilteran otomatis hasil penelusuran.

Nilai yang didukung: 0/1

Contoh penggunaan: <div class="gcse-search" data-image_filter="0"></div>

Semua
image_gl String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Meningkatkan hasil penelusuran yang negara asalnya cocok dengan nilai parameter.

Nilai yang didukung

Semua
image_size String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Menampilkan gambar dengan ukuran tertentu, dengan ukuran dapat berupa salah satu dari: icon, small, medium, large, xlarge, xxlarge, atau huge.

Semua
image_sort_by String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Urutkan hasil menggunakan tanggal atau konten terstruktur lainnya.

Untuk mengurutkan berdasarkan relevansi, gunakan string kosong (image_sort_by="").

Contoh penggunaan: <div class="gcse-search" data-image_sort_by="date"></div>

Semua
image_type String Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

Membatasi penelusuran ke gambar dengan jenis tertentu. Nilai yang didukung adalah clipart (Gambar klip), face (Wajah orang), lineart (Gambar garis), stock (Foto stok), photo (Foto), dan animated (GIF animasi).

Semua
Penelusuran web
disableWebSearch Boolean Jika true, menonaktifkan penelusuran web. Biasanya hanya digunakan jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.

hasil penelusuran

searchresults-only
webSearchQueryAddition String Istilah tambahan ditambahkan ke kueri penelusuran menggunakan OR logis.

Contoh penggunaan: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

 Semua
webSearchResultSetSize Integer, String Ukuran maksimum kumpulan hasil. Berlaku untuk penelusuran gambar dan penelusuran web. Nilai default bergantung pada tata letak dan apakah Programmable Search Engine dikonfigurasi untuk menelusuri seluruh web atau hanya situs tertentu. Nilai yang dapat diterima mencakup:
  • Bilangan bulat dari 1-20
  • small: meminta set hasil kecil, biasanya 4 hasil per halaman.
  • large: meminta kumpulan hasil yang besar, biasanya 8 hasil per halaman.
  • filtered_cse: meminta hingga 10 hasil per halaman, untuk maksimum 10 halaman atau 100 hasil.
 Semua
webSearchSafesearch String Menentukan apakah SafeSearch diaktifkan untuk hasil penelusuran web. Nilai yang diterima adalah off dan active. Semua
as_filetype String Membatasi hasil ke file dengan ekstensi yang ditentukan. Daftar jenis file yang dapat diindeks oleh Google dapat ditemukan di Pusat Bantuan Search Console.

Semua
as_oq String Memfilter hasil penelusuran menggunakan Logika OR.

Contoh penggunaan jika Anda menginginkan hasil penelusuran yang menyertakan "term1" atau "term2":<div class="gcse-search" data-as_oq="term1 term2"></div>

 Semua
as_rights String Filter berdasarkan pemberian lisensi.

Nilai yang didukung adalah cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived, dan kombinasi nilai tersebut.

Lihat https://wiki.creativecommons.org/wiki/CC_Search_integration untuk kombinasi umum.

Semua
as_sitesearch String Membatasi hasil ke halaman dari situs tertentu.

Contoh penggunaan: <div class="gcse-search" data-as_sitesearch="example.com"></div>

 Semua
cr String Membatasi hasil penelusuran pada dokumen yang berasal dari negara tertentu.

Nilai yang didukung

Contoh penggunaan: <div class="gcse-search" data-cr="countryFR"></div>

 Semua
filter String Pemfilteran otomatis hasil penelusuran.

Nilai yang didukung: 0/1

Contoh penggunaan: <div class="gcse-search" data-filter="0"></div>

 Semua
gl String Meningkatkan hasil penelusuran yang negara asalnya cocok dengan nilai parameter.

Setelan ini hanya akan berfungsi bersama dengan setelan nilai bahasa.

Nilai yang didukung

Contoh penggunaan: <div class="gcse-search" data-gl="fr"></div>

 Semua
lr String Membatasi hasil penelusuran pada dokumen yang tertulis dalam bahasa tertentu.

Nilai yang didukung

Contoh penggunaan: <div class="gcse-search" data-lr="lang_fr"></div>

Semua
sort_by String Urutkan hasil menggunakan tanggal atau konten terstruktur lainnya. Nilai atribut harus berupa salah satu opsi yang diberikan dalam setelan Pengurutan Hasil mesin telusur yang dapat diprogram.

Untuk mengurutkan berdasarkan relevansi, gunakan string kosong (sort_by="").

Contoh penggunaan: <div class="gcse-search" data-sort_by="date"></div>

 Semua
Hasil penelusuran
enableOrderBy Boolean Memungkinkan pengurutan hasil menurut relevansi, tanggal, atau label. Semua
linkTarget String Menetapkan target link. Default: _blank.

hasil penelusuran

searchresults-only
noResultsString String Menentukan teks default yang akan ditampilkan jika tidak ada hasil yang cocok dengan kueri. String hasil default dapat digunakan untuk menampilkan string yang dilokalkan dalam semua bahasa yang didukung, sedangkan string yang disesuaikan tidak dapat.

hasil penelusuran

searchresults-only
resultSetSize Integer, String Ukuran maksimum kumpulan hasil. Misalnya, large, small, filtered_cse, 10. default bergantung pada tata letak dan apakah mesin telusur dikonfigurasi untuk menelusuri seluruh web atau hanya situs tertentu. Semua
safeSearch String Menentukan apakah SafeSearch diaktifkan untuk penelusuran web dan gambar. Nilai yang diterima adalah off dan active. Semua

Callback

Diagram Urutan Callback
diagram urutan callback dari JavaScript Elemen Penelusuran

Callback mendukung kontrol mendetail atas inisialisasi elemen penelusuran dan proses penelusuran. Objek ini didaftarkan dengan JavaScript Elemen Penelusuran melalui objek __gcse global. Mendaftarkan Callback menggambarkan pendaftaran semua callback yang didukung.

Mendaftarkan Callback

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };

Callback Inisialisasi

Callback inisialisasi dipanggil sebelum JavaScript Elemen Penelusuran merender elemen penelusuran di DOM. Jika parsetags disetel ke explicit di __gcse, JavaScript Elemen Penelusuran akan menyerahkan rendering Elemen Penelusuran ke callback inisialisasi (seperti yang ditunjukkan dalam Mendaftarkan Callback). Hal ini dapat digunakan untuk memilih elemen yang akan dirender, atau untuk menunda rendering elemen hingga diperlukan. Hal ini juga dapat menggantikan atribut elemen; misalnya, hal ini dapat mengubah kotak penelusuran yang dikonfigurasi melalui Panel Kontrol atau atribut HTML agar default ke penelusuran web menjadi kotak penelusuran gambar, atau menentukan bahwa kueri yang dikirimkan melalui formulir Mesin Telusur Programmable dieksekusi dalam elemen khusus hasil penelusuran. Lihat demo.

Peran callback inisialisasi dikontrol oleh nilai properti parsetags dari __gcse.

  • Jika nilainya onload, JavaScript Elemen Penelusuran akan merender semua Elemen Penelusuran di halaman secara otomatis. Callback inisialisasi masih dipanggil, tetapi tidak bertanggung jawab untuk merender Elemen Penelusuran.
  • Jika nilainya explicit, JavaScript Elemen Penelusuran tidak merender Elemen Penelusuran. Callback dapat merendernya secara selektif menggunakan fungsi render(), atau merender semua Elemen Penelusuran dengan fungsi go()

Kode berikut menunjukkan cara merender kotak penelusuran, beserta hasil penelusuran, di div, menggunakan parsetag explicit dan callback inisialisasi:

Contoh Panggilan Balik Inisialisasi

Kita perlu menyertakan <div> dengan nilai ID tempat kita ingin menempatkan kode Elemen Penelusuran: 

    <div id="test"></div>
 Tambahkan JavaScript ini setelah <div>. Perhatikan bahwa referensinya adalah test, id yang kita gunakan untuk mengidentifikasi <div>
const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};

Sertakan HTML ini untuk mulai memuat Elemen Penelusuran. Ganti nilai cx dalam klausa src dengan cx Anda sendiri. 

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

Callback Penelusuran

JavaScript Elemen Penelusuran mendukung enam callback yang beroperasi dalam alur kontrol penelusuran. Callback penelusuran datang berpasangan, yaitu callback penelusuran web dan callback penelusuran gambar yang cocok:

  • Mulai Penelusuran
    • Untuk penelusuran gambar
    • Untuk penelusuran web
  • Hasil siap
    • Untuk penelusuran gambar
    • Untuk penelusuran web
  • Hasil ditampilkan
    • Untuk penelusuran gambar
    • Untuk penelusuran web

Seperti callback inisialisasi, callback penelusuran dikonfigurasi menggunakan entri dalam objek __gcse. Hal ini terjadi saat JavaScript Elemen Penelusuran dimulai. Modifikasi pada __gcse setelah startup akan diabaikan.

Setiap callback ini meneruskan gName untuk Elemen Penelusuran sebagai argumen. gname berguna saat halaman berisi lebih dari satu penelusuran. Berikan nilai gname pada elemen penelusuran menggunakan atribut data-gname:

<div class="gcse-searchbox" data-gname="storesearch"></div>

Jika HTML tidak mengidentifikasi gname, JavaScript Elemen Penelusuran akan membuat nilai yang akan tetap konsisten hingga HTML diubah.

Callback Memulai Penelusuran Gambar/Web

Callback memulai penelusuran dipanggil tepat sebelum JavaScript Elemen Penelusuran meminta hasil penelusuran dari servernya. Contoh kasus penggunaan adalah menggunakan waktu lokal dalam sehari untuk mengontrol perubahan pada kueri. 

searchStartingCallback(gname, query)
gname
String identifikasi Elemen Penelusuran
query
Nilai
yang dimasukkan oleh pengguna (mungkin diubah oleh JavaScript elemen penelusuran).

Callback menampilkan nilai yang harus digunakan sebagai kueri untuk penelusuran ini. Jika menampilkan string kosong, nilai yang ditampilkan akan diabaikan dan pemanggil menggunakan kueri yang tidak diubah.

Atau, Anda dapat menempatkan fungsi callback di objek __gcse atau menambahkan callback ke objek secara dinamis dengan JavaScript: 

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Contoh Callback Memulai Penelusuran

Contoh callback memulai penelusuran di Example Search Starting Callback menambahkan morning atau afternoon ke kueri, bergantung pada waktu.

Contoh Callback Mulai Penelusuran 
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

Instal callback ini di window.__gcse: 

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      image: {
        starting: 'myImageSearchStartingCallbackName',
      },
      web: {
        starting: myWebSearchStartingCallback,
      },
    };
  
  <script
  async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Callback Siap Hasil Penelusuran Gambar/Web

Callback ini dipanggil segera sebelum JavaScript Elemen Penelusuran merender promosi dan hasil. Contoh kasus penggunaan adalah callback yang merender promosi dan menghasilkan gaya yang tidak dapat ditentukan dengan penyesuaian normal. 

resultsReadyCallback(gname, query, promos, results, div)
gname
String identifikasi Elemen Penelusuran
query
kueri yang menghasilkan hasil ini
promos
array objek promosi, yang sesuai dengan promosi yang cocok untuk kueri pengguna. Lihat definisi objek promosi.
results
array objek hasil. Lihat definisi objek hasil.
div
div HTML yang diposisikan di DOM tempat Elemen Penelusuran biasanya menempatkan promosi dan hasil penelusuran. Biasanya, JavaScript Elemen Penelusuran akan menangani pengisian div ini, tetapi callback ini dapat memilih untuk menghentikan rendering hasil otomatis dan menggunakan div ini untuk merender hasil itu sendiri.

Jika callback ini menampilkan nilai true, JavaScript Elemen Penelusuran akan melewati pekerjaan footer halaman.

Contoh Callback Siap Hasil

Callback resultsReady contoh di Example Results Ready Callback menggantikan presentasi default promosi dan hasil dengan penggantian sangat sederhana.

Contoh Callback Hasil Siap 
    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

      const table = document.createElement('table');
      if (promos) {
        for (const promo of promos) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          cell.appendChild(makePromoElt(promo));
        }
        resultsDiv.appendChild(table);
        resultsDiv.appendChild(document.createElement('br'));
      }
      if (results) {
        const table = document.createElement('table');
        for (const result of results) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          const [anchor, span] = makeResultParts(result);
          cell.appendChild(anchor);
          const cell2 = row.insertCell(-1);
          cell2.appendChild(span);
        }
        resultsDiv.appendChild(table);
      }
      return true;
    };

Instal callback ini di window.__gcse: 

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };
 
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Seperti callback memulai penelusuran, di atas adalah salah satu dari banyak cara untuk menempatkan callback dalam objek __gcse.

Callback yang Dirender Hasil Penelusuran Gambar/Web

Callback ini dipanggil tepat sebelum JavaScript Elemen Penelusuran merender footer halaman. Contoh kasus penggunaan mencakup callback yang menambahkan konten hasil yang tidak ditampilkan oleh elemen penelusuran seperti kotak centang simpan ini atau informasi yang tidak dirender secara otomatis, atau callback yang menambahkan tombol untuk informasi selengkapnya.

Jika callback hasil yang dirender memerlukan informasi yang ada dalam parameter promos dan results dari callback hasil siap, callback tersebut dapat meneruskannya di antara keduanya, seperti ini: 

callback(gname, query, promoElts, resultElts);
gname
String identifikasi Elemen Penelusuran
query
string penelusuran.
promoElts
array elemen DOM yang berisi promosi.
resultElts
array elemen DOM yang berisi hasil.

Tidak ada nilai yang ditampilkan.

Contoh Callback Hasil yang Dirender

Contoh callback resultsRendered di Example Results Rendered Callback menambahkan kotak centang Keep dummy ke setiap promosi dan hasil.

Contoh Callback Perenderan Hasil 
myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

Instal callback ini di window.__gcse: 

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};
 
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Jika callback hasil yang dirender memerlukan informasi yang diteruskan ke callback hasil siap, callback tersebut dapat meneruskan data antara callback. Contoh berikut menunjukkan salah satu dari banyak cara untuk meneruskan nilai rating dari richSnippet dari callback hasil siap ke callback hasil ditampilkan.

Contoh Callback Hasil Siap Bekerja Sama dengan Callback Hasil yang Dirender 
const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};
 Instal callback ini menggunakan kode seperti ini saat menyiapkan __gcse: 
const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};
 
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
Contoh Callback Hasil yang Dirender: Membuka jenis file tertentu di tab/jendela baru

Contoh callback berikut dapat mengubah link hasil penelusuran setelah dirender untuk membuka file tertentu di tab/halaman baru, bukan di jendela saat ini (misalnya: PDF, Excel, atau Word). Hal ini meningkatkan kualitas pengalaman penjelajahan saat pengguna tidak ingin membuka file di jendela yang sama dan berpindah dari halaman hasil.

Contoh callback ini mengidentifikasi link PDF dalam hasil penelusuran dan menetapkan atribut target="_blank" pada link PDF sehingga link tersebut terbuka di tab baru. MutationObserver digunakan untuk menangani hasil baru secara dinamis jika halaman diperbarui. Catatan: Anda dapat mengganti .pdf di handleSearchResults dengan jenis file lain sesuai kebutuhan Anda.

Contoh callback ini tidak berfungsi pada tata letak Overlay dan yang Dihosting Google.

Membuka jenis file tertentu di tab/jendela baru 
function handleSearchResults() {
  const links = document.querySelectorAll('.gsc-results .gs-title');
  links.forEach(link => {
    const url = link.href;
    if (url?.toLowerCase().endsWith('.pdf')) {
      link.setAttribute('target', '_blank');
    }
  });
}

const myWebResultsRenderedCallback = () => {
  // Call handleSearchResults when results are rendered
  handleSearchResults();
  // Set up a MutationObserver to handle subsequent updates to the results
  const observer = new MutationObserver(handleSearchResults);
  const searchResultsContainer = document.querySelector('.gsc-results');
  if (searchResultsContainer) {
    observer.observe(searchResultsContainer, {
      childList: true,
      subtree: true
    });
  } else {
    console.log('No Results.');
  }
};

Instal callback ini di window.__gcse: 

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: myWebResultsRenderedCallback,
  },
};
 
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Contoh Callback Lainnya

Contoh callback tambahan dapat ditemukan dalam dokumen Contoh Callback Lainnya.

Properti Promosi dan Hasil

Dengan menggunakan notasi JSDoc, berikut adalah properti objek promotion dan result. Di sini, kita mencantumkan semua properti yang mungkin ada. Keberadaan banyak properti bergantung pada detail promosi atau hasil penelusuran.

Properti Promosi
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
Properti Objek Hasil
{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

richSnippet di results memiliki jenis array objek yang tidak terikat. Nilai entri dalam array ini dikontrol oleh data terstruktur yang ditemukan di halaman web untuk setiap hasil penelusuran. Misalnya, situs web ulasan dapat menyertakan data terstruktur yang menambahkan entri array ini ke richSnippet: 

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

Programmable Search Element Control API (V2)

Objek google.search.cse.element memublikasikan fungsi statis berikut:

Fungsi Deskripsi
.render(componentConfig, opt_componentConfig) Merender Elemen Penelusuran.

Parameter

Nama Deskripsi
componentConfig Konfigurasi untuk komponen Elemen Programmable Search. Menentukan hal berikut:
  • div (string|Element): id dari <div> atau elemen div tempat Elemen Programmable Search akan dirender.
  • tag (string): Jenis komponen yang akan dirender. (Jika opt_componentConfig diberikan, nilai atribut tag harus searchbox.) Nilai yang diizinkan adalah:
    • search: Kotak penelusuran dan hasil penelusuran, ditampilkan bersama-sama
    • searchbox: Komponen kotak penelusuran dari Elemen Penelusuran yang Dapat Diprogram.
    • searchbox-only: Kotak penelusuran mandiri, yang akan dipasangkan dengan blok hasil penelusuran yang ditentukan oleh opt_componentConfig dalam tata letak dua kolom.
    • searchresults-only: Blok hasil penelusuran mandiri. Penelusuran dipicu oleh parameter kueri yang disematkan dalam URL, atau oleh eksekusi terprogram.
  • gname (string): (Opsional) Nama unik untuk komponen ini. Jika tidak diberikan, Programmable Search Engine akan otomatis membuat gname.
  • attributes (Objek): Atribut opsional dalam bentuk pasangan key:value. Atribut yang didukung.
opt_componentConfig Opsional. Argumen konfigurasi komponen kedua. Digunakan dalam mode TWO_COLUMN untuk menyediakan komponen searchresults. Menentukan hal berikut:
  • div (string): id dari <div> atau elemen div tempat elemen akan dirender.
  • tag (string): Jenis komponen yang akan dirender. Jika opt_componentConfig diberikan, nilai atribut tag harus berupa searchresults. Selain itu, nilai atribut tag dari componentConfig harus searchbox.
  • gname (string): (Opsional) Nama unik untuk komponen ini. Jika tidak disediakan, Programmable Search Engine akan otomatis membuat gname untuk komponen ini. Jika diberikan, nilai ini harus cocok dengan gname di componentConfig.
  • attributes (Objek): Atribut opsional dalam bentuk pasangan key:value. Atribut yang didukung.
.go(opt_container) Merender semua tag/class Elemen Penelusuran dalam penampung yang ditentukan.

Parameter

Nama Deskripsi
opt_container Penampung yang berisi komponen Elemen Penelusuran untuk dirender. Tentukan ID penampung (string) atau elemen itu sendiri. Jika dihilangkan, semua komponen Elemen Penelusuran yang Dapat Diprogram di dalam tag body halaman akan dirender.
.getElement(gname) Mendapatkan objek elemen menurut gname. Jika tidak ditemukan, tampilkan null.

Objek element yang ditampilkan memiliki atribut berikut:

  • gname: Nama objek elemen. Jika tidak diberikan, Programmable Search Engine akan otomatis membuat gname untuk objek. Informasi selengkapnya.
  • type: Jenis elemen.
  • uiOptions: Atribut akhir yang digunakan untuk merender elemen.
  • execute - function(string): Mengeksekusi kueri terprogram.
  • prefillQuery - function(string): Mengisi kotak penelusuran dengan string kueri tanpa menjalankan kueri.
  • getInputQuery - function(): Mendapatkan nilai saat ini yang ditampilkan di kotak input.
  • clearAllResults - function(): Menghapus kontrol dengan menyembunyikan semuanya kecuali kotak penelusuran, jika ada.

Kode berikut menjalankan kueri "news" di Elemen Penelusuran "element1":

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() Menampilkan peta semua objek elemen yang berhasil dibuat, yang dikunci oleh gname.