Programmable Search Element Control API

HTML işaretlemesini kullanarak Programlanabilir Arama Motoru bileşenlerini (arama kutuları ve arama sonuçları sayfaları) web sayfalarınıza ve diğer web uygulamalarınıza yerleştirebilirsiniz. Bu Programlanabilir Arama Motoru öğeleri, Programlanabilir Arama sunucusu tarafından depolanan ayarlara ve yaptığınız özelleştirmelere göre oluşturulan bileşenlerden oluşur.

Tüm JavaScript eşzamansız olarak yüklenir. Bu sayede, tarayıcı Programlanabilir Arama Motoru JavaScript'ini getirirken web sayfanızın yüklenmeye devam etmesine olanak tanır.

Giriş

Bu belgede, Programlanabilir Arama Motoru öğelerini web sayfanıza eklemeyle ilgili temel bir modelin yanı sıra öğenin yapılandırılabilir bileşenleri ve esnek JavaScript API'si ile ilgili açıklamalar yer almaktadır.

Kapsam

Bu belgede, Programmable Search Engine Control API'ye özgü işlevlerin ve özelliklerin nasıl kullanılacağı açıklanmaktadır.

Tarayıcı uyumluluğu

Programlanabilir Arama Motoru tarafından desteklenen tarayıcıların listesini burada bulabilirsiniz.

Kitle

Bu doküman, sayfalarına Google Programlanabilir Arama işlevini eklemek isteyen geliştiriciler için hazırlanmıştır.

Programlanabilir Arama Öğeleri

Sayfanıza Programlanabilir Arama Öğesi eklemek için HTML işaretlemesi kullanabilirsiniz. Her öğe en az bir bileşenden oluşur: arama kutusu, arama sonuçları bloğu veya her ikisi. Arama kutusu, kullanıcı girişini aşağıdaki yöntemlerden herhangi biriyle kabul eder:

• Metin girişi alanına yazılan bir arama sorgusu
• URL'ye yerleştirilmiş bir sorgu dizesi
• Programatik yürütme

Ayrıca, arama sonuçları bloğu aşağıdaki yöntemlerle giriş kabul eder:

• URL'ye yerleştirilmiş bir sorgu dizesi
• Programatik yürütme

Aşağıdaki Programlanabilir Arama Öğesi türleri kullanılabilir:

Web sayfanıza istediğiniz sayıda geçerli arama öğesi ekleyebilirsiniz. İki sütunlu modda, gerekli tüm bileşenler (bir arama kutusu ve arama sonuçları bloğu) bulunmalıdır.

Basit bir arama öğesi örneğini aşağıda bulabilirsiniz:

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

Programlanabilir Arama Öğeleri'ni kullanarak farklı düzen seçenekleri oluşturma

Programlanabilir Arama Motoru denetim masasının Görünüm ve Tarz sayfasında aşağıdaki düzen seçenekleri kullanılabilir. Programlanabilir Arama Öğeleri'ni kullanarak düzen seçenekleri oluşturmayla ilgili bazı genel yönergeleri aşağıda bulabilirsiniz. Bu seçeneklerden herhangi birinin demosunu görmek için bağlantıyı tıklayın.

Düzen seçenekleri hakkında daha fazla bilgi

Programlanabilir Arama öğelerini özelleştirme

Renkleri, yazı tipini veya bağlantı stilini özelleştirmek için programlanabilir arama motorunuzun Görünüm ve Tarz sayfasına gidin.

Programlanabilir Arama Motoru denetim masasında oluşturulan yapılandırmaların üzerine yazmak için isteğe bağlı özellikleri kullanabilirsiniz. Bu sayede, sayfaya özel bir arama deneyimi oluşturabilirsiniz. Örneğin, aşağıdaki kod, sonuç sayfasını (http://www.example.com?search=lady+gaga) yeni bir pencerede açan bir arama kutusu oluşturur. Kullanıcı sorgusu dizesiyle birlikte queryParameterName özelliğinin değeri, sonuç URL'sini oluşturmak için kullanılır.

queryParameterName özelliğinin önüne data- eklendiğini unutmayın. Bu önek tüm özellikler için zorunludur.

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

Otomatik tamamlama veya iyileştirmeler gibi özellikleri etkinleştirmek için Programlanabilir Arama Motoru denetim masasını kullandıysanız bu özellikleri özelleştirmek için özellikleri kullanabilirsiniz. Bu özellikleri kullanarak belirttiğiniz tüm özelleştirmeler, kontrol panelinde yapılan ayarları geçersiz kılar. Aşağıdaki örnekte, şu özelliklere sahip iki sütunlu bir Arama Öğesi oluşturulmaktadır:

• Geçmiş yönetimi etkinleştirilmiş olmalıdır.
• Gösterilen maksimum otomatik tamamlama sayısı 5 olarak ayarlanır.
• Daraltmalar bağlantı olarak gösterilir.

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

Desteklenen özellikler

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

Geri aramalar

Geri çağırmalar, arama öğesi başlatma ve arama süreçlerinin ayrıntılı kontrolünü destekler. Bu öğeler, genel __gcse nesnesi aracılığıyla Search Element JavaScript'e kaydedilir. Register Callbacks, desteklenen tüm geri aramaların kaydını gösterir.

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

Başlatma Geri Çağırması

Başlatma geri çağırma işlevi, Arama Öğesi JavaScript'i DOM'da arama öğelerini oluşturmadan önce çağrılır. parsetags, __gcse içinde explicit olarak ayarlanırsa Arama Öğesi JavaScript'i, Arama Öğeleri'nin oluşturulmasını başlatma geri çağırmasına bırakır (Geri Çağırmaları Kaydetme bölümünde gösterildiği gibi). Bu, oluşturulacak öğeleri seçmek veya öğeleri oluşturmayı ihtiyaç duyulana kadar ertelemek için kullanılabilir. Ayrıca, öğelerin özelliklerini de geçersiz kılabilir. Örneğin, denetim masası veya HTML özellikleri aracılığıyla yapılandırılan bir arama kutusunu varsayılan olarak web aramasına yönlendirmek yerine görsel arama kutusuna dönüştürebilir ya da Programlanabilir Arama Motoru formu aracılığıyla gönderilen sorguların yalnızca arama sonuçları öğesinde yürütülmesini belirtebilir. Demoyu izleyin.

Başlatma geri çağırma işlevinin rolü, __gcse öğesinin parsetags özelliğiyle kontrol edilir.

• Değeri onload ise Search Element JavaScript, sayfadaki tüm arama öğelerini otomatik olarak oluşturur. Başlatma geri çağırması hâlâ çağrılıyor ancak Arama Öğeleri'nin oluşturulmasından sorumlu değil.
• Değeri explicit ise Arama Öğesi JavaScript'i Arama Öğelerini oluşturmaz. Geri çağırma işlevi, render() işlevini kullanarak bunları seçmeli olarak oluşturabilir veya go() işleviyle tüm arama öğelerini oluşturabilir.

Aşağıdaki kodda, div içinde arama sonuçlarıyla birlikte arama kutusunun nasıl oluşturulacağı gösterilmektedir. Bu işlem için explicit parsetag ve başlatma geri çağırma işlevi kullanılır:

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

Geri aramaları arama

Arama öğesi JavaScript'i, arama kontrol akışında çalışan altı geri çağırma işlevini destekler. Arama geri çağırmaları çiftler halinde gelir: web araması geri çağırması ve eşleşen görsel araması geri çağırması.

• Aramaya Başlama
  • Görsel arama için
  • Web araması için
• Sonuçlar hazır
  • Görsel arama için
  • Web araması için
• Sonuçlar oluşturuldu
  • Görsel arama için
  • Web araması için

Başlatma geri çağırması gibi,arama geri çağırmaları da __gcse nesnesindeki girişler kullanılarak yapılandırılır. Bu durum, Arama Öğesi JavaScript'i başlatıldığında meydana gelir. Başlangıçtan sonra __gcse üzerinde yapılan değişiklikler yoksayılır.

Bu geri çağırmaların her birine, Arama Öğesi için gName bağımsız değişken olarak iletilir. gname, bir sayfada birden fazla arama olduğunda kullanışlıdır. data-gname özelliğini kullanarak bir search öğesine gname değerleri verin:

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

HTML, gname'i tanımlamıyorsa Arama Öğesi JavaScript'i, HTML değiştirilene kadar tutarlı kalacak bir değer oluşturur.

Görsel/Web Arama Başlatma Geri Çağırması

Aramanın başlatılması geri çağırmaları, Arama Öğesi JavaScript'i sunucusundan arama sonuçları istemeden hemen önce çağrılır. Örneğin, sorguda yapılan değişiklikleri kontrol etmek için günün yerel saatini kullanabilirsiniz.

searchStartingCallback(gname, query)

gname

Arama öğesinin tanımlayıcı dizesi

query

Kullanıcı tarafından girilen değer (arama öğesi JavaScript'i tarafından değiştirilmiş olabilir).

Geri çağırma, bu arama için sorgu olarak kullanılması gereken değeri döndürür. Boş bir dize döndürürse dönüş değeri yoksayılır ve arayan, değiştirilmemiş sorguyu kullanır.

Alternatif olarak, geri çağırma işlevini __gcse nesnesine yerleştirebilir veya geri çağırmayı JavaScript ile nesneye dinamik olarak ekleyebilirsiniz:

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

Örnek arama başlatma geri çağırması

Example Search Starting Callback (Örnek Arama Başlatma Geri Çağırması) bölümündeki örnek arama başlatma geri çağırması, günün saatine bağlı olarak sorguya morning veya afternoon ekler.

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

Bu geri çağırmayı window.__gcse: içine yükleyin.

  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>

Görsel/Web Arama Sonuçları İçin Hazır Geri Arama

Bu geri çağırmalar, Arama Öğesi JavaScript'i promosyonları ve sonuçları oluşturmadan hemen önce çağrılır. Örneğin, promosyonları oluşturup normal özelleştirmeyle belirtilemeyen bir tarzda sonuç veren bir geri çağırma işlemi, kullanım alanına örnek olarak verilebilir.

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

gname

Arama öğesinin tanımlayıcı dizesi

query

Bu sonuçları üreten sorgu

promos

Kullanıcının sorgusuyla eşleşen promosyonlara karşılık gelen bir promosyon nesneleri dizisi. Promosyon nesnesi tanımına bakın.

results

sonuç nesneleri dizisi. Sonuç nesnesi tanımına bakın.

div

Arama öğesinin normalde promosyonları ve arama sonuçlarını yerleştireceği DOM'da konumlandırılmış bir HTML div. Normalde, bu div'in doldurulması Search Element JavaScript tarafından yapılır. Ancak bu geri çağırma, sonuçların otomatik olarak oluşturulmasını durdurmayı ve sonuçları kendisi oluşturmak için bu div öğesini kullanmayı tercih edebilir.

Bu geri çağırma işlevi bir true değeri döndürürse Arama Öğesi JavaScript'i sayfa altbilgisi çalışmasına geçer.

Örnek sonuçlar hazır geri çağırma

Example Results Ready Callback (Örnek Sonuçlar Hazır Geri Çağırması) bölümündeki örnek resultsReady geri çağırması, promosyonların ve sonuçların varsayılan sunumunu çok basit bir değiştirme işlemiyle geçersiz kılar.

    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>

Görsel/Web Arama Sonuçları-Oluşturulan Geri Arama

Bu geri çağırmalar, Arama Öğesi JavaScript'i sayfa altbilgisini oluşturmadan hemen önce çağrılır. Örneğin, arama öğesinin göstermediği sonuç içeriğini (ör. Bunu kaydet onay kutusu veya otomatik olarak oluşturulmayan bilgiler) ekleyen bir geri çağırma ya da Daha fazla bilgi düğmeleri ekleyen bir geri çağırma, kullanım alanlarına örnek olarak verilebilir.

Bir sonuçlar oluşturuldu geri çağırma, sonuçlar hazır geri çağırma işlevinin promos ve results parametrelerinde bulunan bilgilere ihtiyaç duyuyorsa bu bilgileri aşağıdaki gibi iletebilir:

callback(gname, query, promoElts, resultElts);

gname

Arama öğesinin tanımlayıcı dizesi

query

arama dizesi.

promoElts

Promosyon içeren DOM öğelerinin dizisi.

resultElts

Sonuçları içeren DOM öğeleri dizisi.

Dönüş değeri yoktur.

Example Results Rendered Callback

Example Results Rendered Callback (Örnek Sonuçlar Oluşturuldu Geri Çağırması) bölümündeki örnek resultsRendered geri çağırması, her promosyona ve sonuca sahte bir Keep (Sakla) onay kutusu ekler.

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>

Sonuçlar oluşturuldu geri çağırması, sonuçlar hazır geri çağırmasına iletilen bilgilere ihtiyaç duyuyorsa bu verileri geri çağırmalar arasında iletebilir. Aşağıdaki örnekte, sonuçlar hazır geri çağırma işlevinden richSnippet değerini sonuçlar oluşturuldu geri çağırma işlevine iletmenin birçok yolundan biri gösterilmektedir.

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>

Örnek sonuçlar oluşturuldu geri çağırması: Belirli dosya türlerini yeni sekmede/pencerede açma

Aşağıdaki geri çağırma örneği, arama sonucu bağlantılarını oluşturulduktan sonra değiştirerek geçerli pencere yerine yeni bir sekmede/sayfada belirli bir dosyanın (ör. PDF, Excel veya Word) açılmasını sağlayabilir. Bu, kullanıcılar bir dosyayı aynı pencerede açmak ve sonuçlar sayfasından uzaklaşmak istemediğinde göz atma deneyimini iyileştirir.

Bu geri çağırma örneği, arama sonuçlarındaki PDF bağlantılarını tanımlar ve PDF bağlantılarında target="_blank" özelliğini ayarlayarak bu bağlantıların yeni sekmede açılmasını sağlar. Sayfa güncellenirse yeni sonuçları dinamik olarak işlemek için MutationObserver kullanılır. Not: handleSearchResults içindeki .pdf simgesini, ihtiyacınıza göre başka bir dosya türüyle değiştirebilirsiniz.

Bu geri çağırma örneği, Google Hosted ve Overlay düzenlerinde çalışmaz.

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>

Diğer Geri Arama Örnekleri

Ek geri çağırma örneklerini Diğer Geri Çağırma Örnekleri belgesinde bulabilirsiniz.

Tanıtım ve Sonuç Özellikleri

JSDoc gösterimi kullanılarak promotion ve result nesnelerinin özellikleri aşağıda verilmiştir. Burada, bulunabilecek tüm özellikleri listeliyoruz. Özelliklerin çoğu, tanıtımın veya arama sonucunun ayrıntılarına bağlıdır.

{
  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,
}

Sonuçlardaki richSnippet, nesne dizisi türündedir. Bu dizideki girişlerin değerleri, her arama sonucu için web sayfasında bulunan yapılandırılmış veriler tarafından kontrol edilir. Örneğin, bir yorum web sitesi, richSnippet öğesine bu dizi girişini ekleyen yapılandırılmış veriler içerebilir:

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

Programmable Search Element Control API (V2)

google.search.cse.element nesnesi aşağıdaki statik işlevleri yayınlar:

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