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:

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.

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

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

Callback

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.

  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:

    <div id="test"></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
};

<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.

    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.

    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;
    };

  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>

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.

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);
    }
  };

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.

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};
};

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.

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.');
  }
};

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.

{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}

{
  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:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');