Programmable Search Element Control API

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

JavaScript'in tamamı eşzamansız olarak yüklenir. Bu, tarayıcı Programlanabilir Arama Motoru JavaScript'ini getirirken web sayfanızın yüklenmeye devam etmesini sağlar.

Giriş

Bu dokümanda, Web sayfanıza Programlanabilir Arama Motoru öğeleri eklemek için kullanılacak temel bir modelin yanı sıra öğenin yapılandırılabilir bileşenleri ve esnek JavaScript API açıklamaları da sağlanmaktadır.

Kapsam

Bu dokümanda, 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'nun desteklediği tarayıcıların listesine buradan ulaşabilirsiniz.

Kitle

Bu doküman, sayfalarına Google Programlanabilir Arama işlevi eklemek isteyen geliştiricilere yöneliktir.

Programlanabilir Arama Öğeleri

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

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

Ayrıca, arama sonucu bloğu aşağıdaki girişleri kabul eder:

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

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

Web sayfanıza istediğiniz sayıda geçerli Search Element ekleyebilirsiniz. İki sütunlu mod için gerekli tüm bileşenler (arama kutusu ve arama sonuçları bloğu) mevcut olmalıdır.

Basit bir Search Element örneği:

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

Programlanabilir Arama Motoru kontrol panelinin Görünüm ve İzlenim sayfasında aşağıdaki düzen seçenekleri bulunur. Programlanabilir Arama Öğeleri'ni kullanarak düzen seçenekleri oluşturmaya ilişkin bazı genel yönergeleri burada bulabilirsiniz. Bu seçeneklerin demosunu görmek için bağlantıyı tıklayın.

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

Programlanabilir Arama Öğelerini Özelleştirme

Renkleri, yazı tipini veya bağlantı stilini özelleştirmek için programlanabilir arama motorunuzun Görünüm ve İzlenim 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. Sonuç URL'sini oluşturmak için kullanıcı sorgu dizesiyle birlikte queryParameterName özelliğinin değeri kullanılır.

queryParameterName özelliğinin önünde data- olduğunu unutmayın. Bu ön ek tüm özellikler için gereklidir.

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

Otomatik tamamlama veya hassaslaştırmalar gibi özellikleri etkinleştirmek için Programlanabilir Arama Motoru kontrol panelini 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 örnek, şu özelliklere sahip iki sütunlu bir Search Element'i oluşturur:

• Geçmiş yönetimi etkin
• Görüntülenen maksimum otomatik tamamlama sayısı 5 olarak ayarlandı
• Ayrıntılandırmalar bağlantı olarak görüntülenir.

<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 işlemlerinin ayrıntılı kontrolünü destekler. Bunlar, Search Element JavaScript'e genel __gcse nesnesi aracılığıyla kaydedilir. Geri Çağırmaları Kaydet, desteklenen tüm geri çağırmaları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ğırması, Search Element JavaScript'i DOM'daki arama öğelerini oluşturmadan önce çağrılır. parsetags, __gcse içinde explicit değerine ayarlanırsa Search Element JavaScript, oluşturma işleminde Search Elements'i başlatma geri çağırmasına bırakır (Register Callbacks bölümünde gösterildiği gibi). Bu, oluşturulacak öğeleri seçmek veya gerekli olana kadar oluşturma öğelerini ertelemek için kullanılabilir. Ayrıca, öğelerin özelliklerini geçersiz kılabilir. Örneğin, Kontrol Paneli veya HTML özellikleri aracılığıyla yapılandırılmış bir arama kutusunu varsayılan olarak web aramasını web araması yapacak şekilde bir görsel arama kutusuna dönüştürebilir veya Programlanabilir Arama Motoru formu aracılığıyla gönderilen sorguların bir searchresults-only öğesi içinde yürütülmesini belirtebilir. Demoya göz atın.

Başlatma geri çağırma işleminin rolü, __gcse öğesinin parsetags özelliğinin değeri tarafından kontrol edilir.

• Değeri onload ise Search Element JavaScript, sayfadaki tüm Search Elements öğelerini otomatik olarak oluşturur. Başlatma geri çağırması devam eder ancak Search Elements'in oluşturulmasından sorumlu değildir.
• Değeri explicit ise Search Element JavaScript, Search Elements oluşturmaz. Geri çağırma, bunları render() işlevini kullanarak seçerek veya go() işleviyle tüm Arama Öğelerini oluşturabilir

Aşağıdaki kod, arama sonuçlarıyla birlikte explicit ayrıştırma etiketi ve başlatma geri çağırması kullanılarak div içinde nasıl arama kutusu oluşturulacağını gösterir:

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

Search Element JavaScript, arama kontrol akışında çalışan altı geri çağırmayı destekler. Arama geri çağırma işlevleri çiftler halinde, bir web araması geri çağırması ve eşleşen görsel arama geri çağırması olarak gelir:

• Arama Başlıyor
  • Görsel arama için
  • Web araması için
• Sonuçlar hazır
  • Görsel arama için
  • Web araması için
• Oluşturulan sonuçlar
  • Görsel arama için
  • Web araması için

Başlatma geri çağırmasında olduğu gibi arama geri çağırmaları da __gcse nesnesindeki girişler kullanılarak yapılandırılır. Bu, Search Element JavaScript'i başladığında gerçekleşir. Başlatma sonrasında __gcse üzerinde yapılan değişiklikler yok sayılır.

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

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

HTML, gname adını tanımlamazsa Search Element JavaScript, HTML değiştirilene kadar tutarlı kalacak bir değer oluşturur.

Görsel/Web Aramasına Dayalı Geri Çağırma

Arama başlangıcı geri çağırmaları, Search Element JavaScript'i sunucusundan arama sonuçları istemeden hemen önce çağrılır. Sorgudaki değişiklikleri kontrol etmek için günün yerel saatini kullanmak örnek bir kullanım alanı olabilir.

searchStartingCallback(gname, query)

gname

Arama Öğesi'nin tanımlayıcı dizesi

query

kullanıcı tarafından girilen değer (muhtemelen arama öğesi JavaScript'i tarafından değiştirilmiştir.)

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öndürülen değer yok sayılır ve çağrı yapan kişi 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ğırma

Örnek Arama Başlangıç Geri Çağırma bölümündeki örnek arama, 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: uygulamasına 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ğırma işlevleri, Search Element JavaScript'in tanıtımları ve sonuçları oluşturmadan hemen önce çağrılır. Örnek bir kullanım alanı, promosyonları oluşturan ve normal özelleştirmeyle belirtilemeyen bir stille sonuçlanan bir geri çağırmadır.

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

gname

Arama Öğesi'nin tanımlayıcı dizesi

query

bu sonuçları oluşturan sorgu

promos

Kullanıcının sorgusu için eşleşen promosyonlara karşılık gelen tanıtım nesneleri dizisi. Promosyon nesnesi tanımına bakın.

results

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

div

Arama Öğesi'nin normalde tanıtım ve arama sonuçlarını yerleştireceği DOM'de konumlandırılmış bir HTML div öğesidir. Normalde Search Element JavaScript, bu div öğesinin doldurulmasını gerçekleştirir, ancak bu geri çağırma, sonuçların otomatik olarak oluşturulmasını durdurmayı ve sonuçların kendisini oluşturmak için bu div öğesini kullanmayı seçebilir.

Bu geri çağırma true değeri döndürürse Search Element JavaScript, sayfa altbilgisi çalışmasına atlar.

Örnek Sonuçlar Hazır Geri Çağırması

Örnek Sonuçlar Hazır Geri Çağırması bölümündeki örnek resultsReady geri çağırması, çok basit bir değiştirme işlemiyle promosyonların ve sonuçların varsayılan sunumunu 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ğırma işlevleri, Search Element JavaScript'in sayfa altbilgisini oluşturmadan hemen önce çağrılır. Örnek kullanım alanları, bunu kaydet onay kutusu veya otomatik olarak oluşturulmayan bilgiler gibi arama öğesinin göstermediği sonuç içeriği ekleyen bir geri çağırma ya da daha fazla bilgi düğmeleri ekleyen bir geri çağırmayı içerir.

Sonuçların oluşturduğu geri çağırma, sonuçların hazır geri çağırma işleminin promos ve results parametrelerinde bulunan bilgilere ihtiyaç duyarsa bu bilgileri aralarında aşağıdaki şekilde geçirebilir:

callback(gname, query, promoElts, resultElts);

gname

Arama Öğesi'nin tanımlayıcı dizesi

query

arama dizesine ayarlanır.

promoElts

Promosyonları içeren DOM öğeleri dizisi.

resultElts

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

Döndürülen değer yoktur.

Örnek Sonuçlar Oluşturulan Geri Arama

Örnek Sonuçlar Oluşturulan Geri Çağırma bölümündeki örnek resultsRendered geri çağırması, her bir tanıtıma ve sonuca sahte bir Keep 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ın oluşturduğu geri çağırma işlemi, sonuçlara hazır geri çağırmaya aktarılan bilgilere ihtiyaç duyuyorsa söz konusu verileri, geri çağırmalar arasında iletebilir. Aşağıdaki örnekte, sonuçlar hazır geri çağırması'ndan richSnippet noktasından bir puan değerini oluşturulan sonuçlara aktarmanın 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>

Diğer Geri Arama Örnekleri

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

Tanıtım ve Sonuç Özellikleri

Bunlar, JSDoc gösterimi kullanılarak promotion ve sonuç nesnelerinin özellikleridir. Mevcut olabilecek tüm özellikleri burada listeledik. Mülklerin çoğunun varlığı, promosyonun 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 değeri, bir nesne dizisinin gevşek türüne sahip. 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, bu dizi girişini richSnippet öğesine 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');