Programmable Search Element Control API

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

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

Pengantar

Dokumen ini menyediakan model dasar untuk menambahkan Programmable Search Engine ke laman web, beserta penjelasan tentang komponen 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 Google Programmable Fungsi penelusuran ke halaman mereka.

Elemen Programmable Search

Anda dapat menggunakan markup HTML untuk menambahkan Elemen Programmable Search ke halaman. Masing-masing setidaknya terdiri dari satu komponen: kotak penelusuran, blok penelusuran hasil, atau keduanya. Kotak penelusuran menerima input pengguna di salah satu opsi berikut cara:

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

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

• String kueri yang disematkan di URL
• Eksekusi terprogram

Jenis Elemen Programmable Search berikut tersedia:

Anda dapat menambahkan berapa pun elemen penelusuran yang valid ke halaman web Anda. Untuk dua kolom semua komponen yang diperlukan (kotak penelusuran dan saluran blok hasil) 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>

Membuat berbagai opsi tata letak menggunakan Elemen Programmable Search

Opsi tata letak berikut tersedia di halaman Tampilan dan Nuansa panel kontrol Programmable Search Engine. Berikut adalah beberapa panduan umum tentang cara menyusun opsi tata letak menggunakan Elemen Programmable Search. Untuk melihat demo opsi ini, klik link.

Informasi selengkapnya tentang opsi tata letak.

Menyesuaikan Elemen Programmable Search

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

Anda dapat menggunakan atribut opsional untuk menimpa konfigurasi yang dibuat di Mesin Telusur yang Dapat Diprogram panel kontrol. Hal ini memungkinkan Anda membuat pengalaman penelusuran khusus halaman. Misalnya, kode berikut untuk membuat kotak penelusuran yang membuka halaman hasil (http://www.example.com?search=lady+gaga) di jendela baru. Nilai atribut Atribut queryParameterName, bersama dengan string kueri pengguna, adalah yang digunakan untuk membuat URL hasil.

Perlu diketahui bahwa atribut queryParameterName diawali dengan data-. Awalan ini wajib ada 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-fitur tersebut. Setiap penyesuaian yang Anda tetapkan menggunakan atribut ini akan menggantikan pengaturan 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
• Penajaman 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. Cookie ini terdaftar dengan JavaScript Elemen Penelusuran melalui __gcse global . Register Callback mengilustrasikan 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 penelusuran elemen di DOM. Jika parsetags disetel ke explicit di __gcse, JavaScript Elemen Penelusuran menyerahkan proses rendering Elemen Penelusuran ke callback inisialisasi (seperti yang ditunjukkan dalam Register Callback). Ini mungkin digunakan untuk memilih elemen yang akan dirender, atau untuk menunda elemen rendering sampai elemen tersebut diperlukan. {i>Function<i} ini juga bisa mengganti atribut elemen; misalnya, dapat mengubah kotak penelusuran yang dikonfigurasi melalui Panel Kontrol atau atribut HTML menjadi default ke melakukan penelusuran di kotak penelusuran gambar, atau menentukan bahwa kueri yang dikirimkan melalui formulir Programmable Search Engine dieksekusi dalam elemen {i>searchresults-only<i}. Lihat demo.

Peran callback inisialisasi dikontrol oleh nilai parsetags properti __gcse.

• Jika nilainya adalah onload, Elemen Penelusuran JavaScript merender semua Elemen Penelusuran di halaman secara otomatis. Callback inisialisasi adalah tetap dipanggil, tetapi tidak bertanggung jawab untuk merender Elemen Penelusuran.
• Jika nilainya adalah explicit, JavaScript Elemen Penelusuran tidak dirender 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, bersama dengan hasil penelusuran, dalam bentuk div, menggunakan parsetag dan callback inisialisasi explicit:

    <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 tersedia dalam pasangan, callback penelusuran web dan callback penelusuran gambar yang cocok:

• Awal Penelusuran
  • Untuk penelusuran gambar
  • Untuk penelusuran web
• Hasil sudah siap
  • Untuk penelusuran gambar
  • Untuk penelusuran web
• Hasil dirender
  • Untuk penelusuran gambar
  • Untuk penelusuran web

Seperti callback inisialisasi,callback penelusuran dikonfigurasi menggunakan entri dalam objek __gcse. Hal ini dilakukan sebagai Elemen Penelusuran JavaScript dimulai. Perubahan pada __gcse setelah startup akan diabaikan.

Setiap callback ini diberi gName untuk Elemen Penelusuran sebagai argumen. gname berguna jika halaman berisi lebih dari satu penelusuran. Lakukan penelusuran elemen nilai gname menggunakan atribut data-gname:

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

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

Callback Memulai Penelusuran Gambar/Web

Callback awal penelusuran dipanggil tepat sebelum permintaan JavaScript Elemen Penelusuran hasil penelusuran dari servernya. Sebuah contoh kasus penggunaan adalah menggunakan waktu lokal untuk mengontrol perubahan pada kueri.

searchStartingCallback(gname, query)

gname

String pengidentifikasi Elemen Penelusuran

query

nilai yang dimasukkan oleh pengguna (mungkin diubah oleh penelusuran elemen JavaScript.)

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

Atau, Anda dapat menempatkan fungsi callback dalam 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 awal penelusuran di Contoh Callback Awal Penelusuran 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 tepat sebelum JavaScript Elemen Penelusuran merender promosi dan hasil pengujian tersebut. Contoh kasus penggunaan adalah callback yang merender promosi dan hasil dalam gaya yang tidak dapat ditentukan dengan penyesuaian normal.

resultsReadyCallback(gname, query, promos, results, div)

gname

String pengidentifikasi Elemen Penelusuran

query

kueri yang menampilkan hasil ini

promos

array objek promosi, yang sesuai dengan promosi untuk terhadap kueri pengguna. Lihat definisi objek promosi.

results

array objek hasil. Lihat definisi objek hasil.

div

div HTML diposisikan di DOM tempat Elemen Penelusuran biasanya promosi tempat dan hasil penelusuran. Biasanya, JavaScript Elemen Penelusuran akan menangani mengisi div ini, tetapi callback ini dapat memilih untuk menghentikan rendering hasil secara otomatis dan menggunakan div ini untuk merender hasilnya.

Jika callback ini menampilkan nilai true, JavaScript Elemen Penelusuran akan beralih ke nilai tersebut pekerjaan {i>page-footer<i}.

Contoh Callback Hasil Siap

Contoh callback resultsReady di Contoh Callback Siap Hasil menggantikan presentasi default promosi dan hasil dengan penggantian yang sangat mudah.

    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 Hasil Penelusuran Gambar/Web

Callback ini dipanggil tepat sebelum JavaScript Elemen Penelusuran merender halaman {i>footer.<i} Contoh kasus penggunaan akan menyertakan callback yang menambahkan konten hasil yang penelusuran tidak ditampilkan, seperti kotak centang simpan ini atau informasi yang tidak dirender secara otomatis, atau callback yang menambahkan tombol untuk informasi selengkapnya.

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

callback(gname, query, promoElts, resultElts);

gname

String pengidentifikasi 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 Contoh Callback yang Dirender menambahkan Keep tiruan 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 siap hasil, objek tersebut dapat meneruskan data tersebut antara semua callback. Contoh berikut menunjukkan salah satu dari banyak cara untuk meneruskan nilai rating dari richSnippet dari callback siap hasil ke hasil yang dirender Callback.

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 Lainnya

Contoh callback tambahan dapat ditemukan di Dokumen Contoh Callback Lainnya.

Properti Promosi dan Hasil

Menggunakan notasi JSDoc, berikut adalah properti dari objek promotion dan result. Di sini, kita mencantumkan semua properti yang mungkin ada. Adanya 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 dalam results memiliki jenis array bebas objek terstruktur dalam jumlah besar. Nilai entri dalam himpunan (array) ini dikontrol oleh atribut data terstruktur yang ditemukan di laman web untuk setiap hasil pencarian. Misalnya, situs web ulasan mungkin 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:

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