Programmable Search Element Control API

אפשר להטמיע רכיבים של Programmable Search Engine (תיבות חיפוש ודפי תוצאות חיפוש) ב את דפי האינטרנט ויישומי אינטרנט אחרים באמצעות תגי עיצוב של HTML. Programmable Search Engine הזה רכיבים מורכבים מרכיבים שמעובדים על סמך ההגדרות שמאוחסנות על ידי שרת Programmable Search, יחד עם כל התאמה אישית שתבצעו.

כל JavaScript נטען באופן אסינכרוני, מה שמאפשר לדף האינטרנט שלך ממשיכים להיטען בזמן שהדפדפן מאחזר את ה-JavaScript של Programmable Search Engine.

מבוא

המסמך הזה מספק מודל בסיסי להוספת Programmable Search Engine לדף האינטרנט שלכם, יחד עם הסברים על רכיבים שניתנים להגדרה ו-API גמיש של JavaScript.

היקף

מסמך זה מתאר כיצד להשתמש בפונקציות ובמאפיינים שספציפיים ל Programmable Search Engine Control API.

תאימות דפדפן

ניתן למצוא את רשימת הדפדפנים שנתמכים על ידי Programmable Search Engine כאן.

קהל

המסמך הזה מיועד למפתחים שרוצים להוסיף את האפשרות Google Programmable פונקציונליות חיפוש בדפים שלהם.

רכיבי חיפוש ניתנים לתכנות

אפשר להשתמש בתגי עיצוב של HTML כדי להוסיף לדף Programmable Search Element. כל אחד הוא מורכב מרכיב אחד לפחות: תיבת חיפוש, בלוק של חיפוש תוצאות, או את שניהם. תיבת החיפוש מקבלת קלט של משתמשים בכל אחד מהקריטריונים הבאים דרכים:

• שאילתת חיפוש שהוקלדה בשדה להזנת טקסט
• מחרוזת שאילתה שמוטמעת בכתובת URL
• ביצוע פרוגרמטי

בנוסף, בלוק תוצאות החיפוש מקבל קלט בדרכים הבאות:

• מחרוזת שאילתה שמוטמעת בכתובת URL
• ביצוע פרוגרמטי

אלה סוגי הרכיבים הזמינים ב-Programmable Search Elements:

ניתן להוסיף לדף האינטרנט כמה רכיבי חיפוש חוקיים שרוצים. לשתי עמודות את כל הרכיבים הדרושים (תיבת חיפוש ).

הנה דוגמה לרכיב חיפוש פשוט:

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

יצירת אפשרויות פריסה שונות באמצעות רכיבי Programmable Search

אפשרויות הפריסה הבאות זמינות בדף 'מראה ותחושה' שבלוח הבקרה של Programmable Search Engine. לפניכם כמה הנחיות כלליות לגבי כתיבת אפשרויות פריסה באמצעות Programmable Search Elements. כדי לראות הדגמה של אחת מהאפשרויות האלה, לוחצים על הקישור.

מידע נוסף על אפשרויות הפריסה.

התאמה אישית של רכיבי Programmable Search

כדי להתאים אישית את הצבעים, הגופן או סגנון הקישורים, עוברים אל הדף 'מראה ותחושה' של מנוע החיפוש שניתן לתכנות.

אפשר להשתמש במאפיינים אופציונליים כדי להחליף הגדרות שנוצרו Programmable Search Engine לוח הבקרה. כך אפשר ליצור חוויית חיפוש ספציפית לדף. לדוגמה: הקוד הבא יוצר תיבת חיפוש שפותחת דף תוצאות (http://www.example.com?search=lady+gaga) בחלון חדש. הערך של המאפיין queryParameterName, יחד עם מחרוזת השאילתה של המשתמש, הוא ששימש ליצירת כתובת ה-URL של התוצאות.

חשוב לשים לב שהתחילית של המאפיין queryParameterName היא data-. הקידומת הזו נדרשת לכל המאפיינים.

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

אם השתמשתם בלוח הבקרה של Programmable Search Engine כדי להפעיל תכונות כמו השלמה אוטומטית או חידודים, תוכלו להשתמש במאפיינים כדי להתאים אישית את התכונות האלה. התאמות אישיות שתציינו באמצעות המאפיינים האלה תבטל את ההגדרות שנקבעו בלוח הבקרה. הדוגמה הבאה יוצרת רכיב חיפוש בן שתי עמודות עם התכונות הבאות:

• ניהול ההיסטוריה מופעל
• מוגדר המספר המקסימלי של השלמות אוטומטיות שמוצגות
• חידודים מוצגים כקישורים.

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

מאפיינים נתמכים

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

התקשרות חזרה

קריאות חוזרות (callback) תומכות בבקרה מפורטת על האתחול של רכיב החיפוש ועל תהליכי החיפוש. הם רשומים ב-JavaScript של רכיב החיפוש דרך __gcse הגלובלי לאובייקט. האפשרות רישום קריאות חוזרות (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) של האתחול

הקריאה החוזרת של האתחול מופעלת לפני ש-JavaScript של רכיב החיפוש מעבד את החיפוש ב-DOM. אם parsetags מוגדר כ-explicit ב- __gcse, רכיב החיפוש JavaScript משאיר את עיבוד רכיבי החיפוש קריאה חוזרת (callback) של אתחול (כפי שמוצג בקטע רישום התקשרות חזרה). משמש לבחירת רכיבים לעיבוד, או לדחייה של רכיבי רינדור עד שהם הדרושים. הוא יכול גם לשנות את המאפיינים של הרכיבים; למשל, הוא יכול להפוך תיבת חיפוש שמוגדרת באמצעות מאפייני 'לוח הבקרה' או 'HTML' כברירת מחדל של 'אינטרנט' לחפש בתיבת חיפוש באמצעות תמונות, או לציין ששאילתות שנשלחות באמצעות טופס של Programmable Search Engine הן בוצעה ברכיב Searchresults בלבד. להדגמה.

התפקיד של הקריאה החוזרת (callback) של האתחול נשלט על ידי הערך של parsetags של __gcse.

• אם הערך הוא onload, רכיב החיפוש JavaScript מעבד את כל רכיבי החיפוש בדף באופן אוטומטי. הקריאה החוזרת של האתחול היא עדיין פעיל, אבל הוא לא אחראי לעיבוד רכיבי החיפוש.
• אם הערך הוא explicit, ה-JavaScript של רכיב החיפוש לא יעובד רכיבי חיפוש. הקריאה החוזרת עשויה לגרום להם באופן סלקטיבי באמצעות הפונקציה render(), או לעבד את כל רכיבי החיפוש באמצעות הפונקציה go()

הקוד הבא מדגים איך לעבד תיבת חיפוש ביחד עם תוצאות חיפוש, div, באמצעות ניתוח הנתונים explicit וקריאה חוזרת (callback) של אתחול:

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

חיפוש התקשרות חזרה

ה-JavaScript של רכיב החיפוש תומך בשש קריאות חוזרות (callback) שפועלות בניהול של תהליך החיפוש. הקריאות החוזרות לחיפוש מגיעות בזוגות, קריאה חוזרת (callback) בחיפוש באינטרנט וקריאה חוזרת (callback) תואמת לחיפוש באמצעות תמונות:

• החיפוש מתחיל
  • לחיפוש תמונות
  • לחיפוש באינטרנט
• התוצאות מוכנות
  • לחיפוש תמונות
  • לחיפוש באינטרנט
• התוצאות מוצגות
  • לחיפוש תמונות
  • לחיפוש באינטרנט

בדומה לקריאה חוזרת (callback) של אתחול,הקריאות החוזרות של החיפוש הוגדרו באמצעות ערכים באובייקט __gcse. זה קורה בתור רכיב החיפוש JavaScript מתחיל. המערכת תתעלם משינויים שבוצעו ב-__gcse לאחר ההפעלה.

כל אחת מהקריאות החוזרות האלה מועברת אל gName עבור רכיב החיפוש כארגומנט. gname מועיל אם דף מכיל יותר מחיפוש אחד. הוספת חיפוש רכיב ערך gname באמצעות המאפיין data-gname:

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

אם ה-HTML לא מזהה את שם ה-gname, ה-JavaScript של רכיב החיפוש יוצר ערך נשארות עקביות עד שה-HTML ישתנה.

קריאה חוזרת (callback) של תמונה/חיפוש באינטרנט

הקריאות החוזרות (callback) המתחילות בחיפוש מופעלות מיד לפני בקשות JavaScript של רכיב החיפוש תוצאות החיפוש מהשרת שלו. דוגמה לדוגמה: שימוש בשעה המקומית ביום לשלוט בשינויים שבוצעו בשאילתה.

searchStartingCallback(gname, query)

gname

המחרוזת המזהה של רכיב החיפוש

query

הערך שהוזן על ידי המשתמש (ייתכן שהשתנה על ידי החיפוש JavaScript.)

הקריאה החוזרת מחזירה את הערך שיש להשתמש בו כשאילתה של החיפוש הזה. אם היא מחזירה מחרוזת ריקה, המערכת מתעלמת מהערך המוחזר והמתקשר משתמש בשאילתה שלא שונתה.

לחלופין, אפשר להוסיף את פונקציית הקריאה החוזרת לאובייקט __gcse, או הוספה דינמית של הקריאה החוזרת לאובייקט באמצעות JavaScript:

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

חיפוש לדוגמה של קריאה חוזרת (callback)

חיפוש לדוגמה שמתחיל ב- קריאה חוזרת לדוגמה בחיפוש Google מוסיפה morning או afternoon לשאילתה, בהתאם לשעה ביום.

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

התקנת הקריאה החוזרת (callback) הזו ב-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>

התקשרות חזרה לתוצאות החיפוש באינטרנט או בתמונה

הקריאות החוזרות האלה מופעלות מיד לפני שרכיב ה-JavaScript של רכיב החיפוש מעבד קידומי מכירות תוצאות. דוגמה לתרחיש לדוגמה היא קריאה חוזרת (callback) שמבצעת עיבוד של קידומי מכירות ומובילה בסגנון אין אפשרות לציין התאמה אישית רגילה.

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

gname

המחרוזת המזהה של רכיב החיפוש

query

השאילתה שהפיקה את התוצאות האלה

promos

מערך אובייקטים של קידום מכירות שתואמים לקריטריונים מבצעים השאילתה של המשתמש. עיינו בהגדרה של אובייקט קידום.

results

מערך אובייקטים של תוצאות. לצפייה הגדרת אובייקט התוצאה.

div

קטע div של HTML ממוקם ב-DOM שבו רכיב החיפוש בדרך כלל מבצעים של מקומות ותוצאות חיפוש. בדרך כלל, רכיב החיפוש JavaScript יטפל מתבצע אכלוס של ה-div הזה, אבל הקריאה החוזרת הזו עשויה להפסיק את הרינדור האוטומטי של התוצאות ולהשתמש בdiv כדי להציג את התוצאות עצמן.

אם הקריאה החוזרת (callback) הזו מחזירה ערך של true, רכיב ה-JavaScript של רכיב החיפוש ידלג בכותרת התחתונה של הדף.

דוגמה לתוצאות מוכנות להתקשרות חזרה

דוגמה לקריאה חוזרת (callback) של resultsReady ב- קריאה חוזרת לתוצאות מוכנות לדוגמה מבטלת את מצגת ברירת המחדל של מבצעים ותוצאות עם תחליף מאוד פשוט.

    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) לאחר הצגה של תוצאות חיפוש תמונה או חיפוש באינטרנט

הקריאות החוזרות האלה מופעלות מיד לפני ש-JavaScript של רכיב החיפוש מעבד את הדף כותרת תחתונה. תרחישים לדוגמה כוללים קריאה חוזרת (callback) שמוסיפה תוכן של תוצאות שהחיפוש לא מוצג בהם רכיב, כמו תיבת הסימון Save this או מידע מעובדת באופן אוטומטי, או קריאה חוזרת (callback) שמוסיפה לחצני למידע נוסף.

אם לקריאה חוזרת (callback) שעבר רינדור נדרש מידע שהיה בpromos results של הקריאה החוזרת (callback) של התוצאות, היא יכולה להעביר ביניהם, באופן הבא:

callback(gname, query, promoElts, resultElts);

gname

המחרוזת המזהה של רכיב החיפוש

query

מחרוזת חיפוש.

promoElts

מערך של רכיבי ה-DOM שמכילים קידומי מכירות.

resultElts

מערך של רכיבי ה-DOM שמכילים תוצאות.

אין ערך מוחזר.

קריאה חוזרת לדוגמה של תוצאות שעובדו

דוגמה לקריאה חוזרת (callback) של resultsRendered ב- קריאה חוזרת (callback) של תוצאות לדוגמה שמוסיפה Keep דמה בתיבת הסימון לצד כל קידום מכירות ותוצאה.

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>

אם צריך לעבד את הקריאה החוזרת (callback) מידע שהועבר לקריאה חוזרת (callback) של תוצאות מוכנות, והוא יכול להעביר את הנתונים האלה הקריאות החוזרות (callback). בדוגמה הבאה מוצגת אחת מהדרכים רבות להעביר ערך דירוג מ- richSnippet מהתוצאות המוכנות להתקשרות חזרה אל התוצאות שעברו רינדור קריאה חוזרת.

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>

דוגמאות נוספות להתקשרות חזרה

דוגמאות נוספות לקריאה חוזרת (callback) זמינות בקטע מסמך דוגמאות נוספות להתקשרות חזרה.

מאפייני קידום ותוצאה

באמצעות סימון JSDoc, המאפיינים האלה הם באובייקטים של promotion ותוצאה. כאן אנחנו מפרטים את כל המאפיינים שעשויים להיות קיימים. הנוכחות של הרבה נכסים תלויים בפרטים של קידום המכירות או של תוצאת החיפוש.

{
  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 בתוצאות מכילה את הסוג החופשי של מערך אובייקטים. ערכי הערכים במערך הזה נשלטים על ידי נתונים מובְנים שנמצא בדף האינטרנט של כל תוצאת חיפוש. לדוגמה, אתר ביקורות עשוי לכלול נתונים מובְנים שמוסיפים את רשומת המערך הזו ל-richSnippet:

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

Programmable Search Element Control API (V2)

האובייקט google.search.cse.element מפרסם את הפרטים הבאים פונקציות סטטיות:

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