תצוגה מקדימה של הקישורים

כדי למנוע שינוי של ההקשר כשמשתמשים משתפים קישור ב-Google Chat, אפליקציית Chat יכולה להציג את הקישור בתצוגה מקדימה. לשם כך, אפשר לצרף להודעה כרטיס שמספק מידע נוסף ומאפשר לאנשים לבצע פעולות ישירות מ-Google Chat.

למשל, נניח שיש לכם מרחב משותף ב-Google Chat שכולל את כל נציגי שירות הלקוחות של החברה, וגם אפליקציית Chat בשם "Case-y". נציגים משתפים לעתים קרובות קישורים לבקשות שירות לקוחות במרחב המשותף ב-Chat, ובכל פעם שהעמיתים שלהם לעבודה צריכים לפתוח את הקישור לפנייה לתמיכה, כדי לראות פרטים כמו מקבל ההקצאה, הסטטוס והנושא. בדומה לכך, אם מישהו רוצה לקבל בעלות על פנייה או לשנות את הסטטוס שלה, הוא צריך לפתוח את הקישור.

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

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

צ'יפ שמציין שייתכן שאפליקציית Chat עשויה לראות קישור בתצוגה מקדימה

אחרי שליחת ההודעה, הקישור נשלח לאפליקציית Chat, והכרטיס יישלח להודעה של המשתמש ויצטרף אליה.

אפליקציית Chat מציגה תצוגה מקדימה של קישור באמצעות צירוף כרטיס להודעה

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

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

אפשר לרשום קישורים ספציפיים, כמו example.com, support.example.com ו-support.example.com/cases/, כתבניות של כתובות URL בדף ההגדרות של אפליקציית Chat במסוף Google Cloud, כדי שאפליקציית Chat תוכל לראות אותם בתצוגה מקדימה.

תפריט ההגדרות של תצוגות מקדימות לקישורים

  1. פותחים את מסוף Google Cloud.
  2. ליד Google Cloud, לוחצים על החץ למטה ופותחים את הפרויקט של אפליקציית Chat.
  3. בשדה החיפוש מקלידים Google Chat API ולוחצים על Google Chat API.
  4. לוחצים על ניהול > תצורה.
  5. בקטע 'תצוגות מקדימות של קישורים', אפשר להוסיף או לערוך תבנית של כתובת URL.
    1. כדי להגדיר תצוגות מקדימות לקישורים עבור תבנית כתובת אתר חדשה, לוחצים על הוספת תבנית כתובת אתר.
    2. כדי לערוך את התצורה של תבנית כתובת URL קיימת, לוחצים על החץ למטה .
  6. בשדה תבנית מארח, הזן את הדומיין של תבנית כתובת האתר. אפליקציית Chat תציג תצוגה מקדימה של קישורים לדומיין הזה.

    כדי להציג את הקישורים לתצוגה מקדימה של אפליקציית Chat לתת-דומיין ספציפי, כמו subdomain.example.com, צריך לכלול את תת-הדומיין.

    כדי להציג את הקישורים בתצוגה מקדימה של אפליקציית Chat לכל הדומיין, צריך לציין תו כללי לחיפוש עם כוכבית (*) בתור תת-הדומיין. לדוגמה, *.example.com תואם עם subdomain.example.com ועם any.number.of.subdomains.example.com.

  7. בשדה קידומת נתיב, מזינים נתיב לצירוף לדומיין של דפוס המארח.

    כדי להתאים לכל כתובות ה-URL בדומיין של תבנית המארח, משאירים את השדה קידומת נתיב ריק.

    לדוגמה, אם דפוס המארח הוא support.example.com, כדי להתאים לכתובות URL במקרים שמתארחים ב-support.example.com/cases/, מזינים cases/.

  8. לוחצים על סיום.

  9. לוחצים על שמירה.

מעכשיו, בכל פעם שמישהו יכלול קישור שתואם לתבנית של כתובת URL של תצוגה מקדימה של קישור בהודעה במרחב משותף ב-Chat שכולל את אפליקציית Chat, האפליקציה תציג אותו בתצוגה מקדימה.

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

במרחבים משותפים ב-Chat שכוללים את אפליקציית Chat, אם בהודעה של מישהו יש קישור שמתאים לתבנית URL של תצוגה מקדימה של קישור, אפליקציית Chat מקבלת אירוע אינטראקציה של MESSAGE. המטען הייעודי (payload) של JSON של אירוע האינטראקציה מכיל את השדה matchedUrl:

JSON

message {

  . . . // other message attributes redacted

  "matchedUrl": {
     "url": "https://support.example.com/cases/case123"
   },

  . . . // other message attributes redacted

}

בודקים אם השדה matchedUrl קיים במטען הייעודי (payload) של האירוע MESSAGE, כדי לאפשר לאפליקציית Chat להוסיף מידע להודעה באמצעות הקישור בתצוגה המקדימה. אתם יכולים לצרף לאפליקציית Chat הודעת טקסט פשוטה או לצרף כרטיס.

תשובה באמצעות הודעת טקסט

כדי לתת תשובות פשוטות, אפליקציית Chat יכולה להציג קישור בתצוגה מקדימה על ידי שליחת הודעת טקסט פשוטה לקישור. הדוגמה הזו מצורפת הודעה שחוזרת על כתובת ה-URL של הקישור, שתואמת לדפוס כתובת ה-URL של התצוגה המקדימה של הקישור.

Node.js

node/preview-link/simple-text-message.js
/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    return res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Checks for the presence of event.message.matchedUrl and responds with a
  // text message if present
  if (req.body.message.matchedUrl) {
    return res.json({
      'text': 'req.body.message.matchedUrl.url: ' +
        req.body.message.matchedUrl.url,
    });
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return res.json({'text': 'No matchedUrl detected.'});
};

Apps Script

apps-script/preview-link/simple-text-message.gs
/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} event The event object from Chat API.
 *
 * @return {Object} Response from the Chat app attached to the message with
 * the previewed link.
 */
function onMessage(event) {
  // Checks for the presence of event.message.matchedUrl and responds with a
  // text message if present
  if (event.message.matchedUrl) {
    return {
      'text': 'event.message.matchedUrl.url: ' + event.message.matchedUrl.url,
    };
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return {'text': 'No matchedUrl detected.'};
}

צירוף כרטיס

כדי לצרף כרטיס לקישור בתצוגה מקדימה, עליך להחזיר ActionResponse מסוג UPDATE_USER_MESSAGE_CARDS. בדוגמה הזו מצורף כרטיס פשוט.

אפליקציית Chat מציגה תצוגה מקדימה של קישור באמצעות צירוף כרטיס להודעה

Node.js

node/preview-link/attach-card.js
/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    return res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Checks for the presence of event.message.matchedUrl and attaches a card
  // if present
  if (req.body.message.matchedUrl) {
    return res.json({
      'actionResponse': {'type': 'UPDATE_USER_MESSAGE_CARDS'},
      'cardsV2': [
        {
          'cardId': 'attachCard',
          'card': {
            'header': {
              'title': 'Example Customer Service Case',
              'subtitle': 'Case basics',
            },
            'sections': [
              {
                'widgets': [
                  {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
                  {'keyValue': {'topLabel': 'Assignee', 'content': 'Charlie'}},
                  {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
                  {
                    'keyValue': {
                      'topLabel': 'Subject', 'content': 'It won"t turn on...',
                    }
                  },
                ],
              },
              {
                'widgets': [
                  {
                    'buttons': [
                      {
                        'textButton': {
                          'text': 'OPEN CASE',
                          'onClick': {
                            'openLink': {
                              'url': 'https://support.example.com/orders/case123',
                            },
                          },
                        },
                      },
                      {
                        'textButton': {
                          'text': 'RESOLVE CASE',
                          'onClick': {
                            'openLink': {
                              'url': 'https://support.example.com/orders/case123?resolved=y',
                            },
                          },
                        },
                      },
                      {
                        'textButton': {
                          'text': 'ASSIGN TO ME',
                          'onClick': {
                            'action': {
                              'actionMethodName': 'assign',
                            },
                          },
                        },
                      },
                    ],
                  },
                ],
              },
            ],
          },
        },
      ],
    });
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return res.json({'text': 'No matchedUrl detected.'});
};

Apps Script

apps-script/preview-link/attach-card.gs
/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app attached to the message with
 * the previewed link.
 */
function onMessage(event) {
  // Checks for the presence of event.message.matchedUrl and attaches a card
  // if present
  if (event.message.matchedUrl) {
    return {
      'actionResponse': {
        'type': 'UPDATE_USER_MESSAGE_CARDS',
      },
      'cardsV2': [{
        'cardId': 'attachCard',
        'card': {
          'header': {
            'title': 'Example Customer Service Case',
            'subtitle': 'Case basics',
          },
          'sections': [{
            'widgets': [
              {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
              {'keyValue': {'topLabel': 'Assignee', 'content': 'Charlie'}},
              {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
              {
                'keyValue': {
                  'topLabel': 'Subject', 'content': 'It won\'t turn on...',
                },
              },
            ],
          },
          {
            'widgets': [{
              'buttons': [
                {
                  'textButton': {
                    'text': 'OPEN CASE',
                    'onClick': {
                      'openLink': {
                        'url': 'https://support.example.com/orders/case123',
                      },
                    },
                  },
                },
                {
                  'textButton': {
                    'text': 'RESOLVE CASE',
                    'onClick': {
                      'openLink': {
                        'url': 'https://support.example.com/orders/case123?resolved=y',
                      },
                    },
                  },
                },
                {
                  'textButton': {
                    'text': 'ASSIGN TO ME',
                    'onClick': {'action': {'actionMethodName': 'assign'}},
                  },
                },
              ],
            }],
          }],
        },
      }],
    };
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return {'text': 'No matchedUrl detected.'};
}

עדכון כרטיס

כדי לעדכן את הכרטיס שמצורף לקישור בתצוגה מקדימה, צריך להחזיר ActionResponse מסוג UPDATE_USER_MESSAGE_CARDS. אפליקציות Chat יכולות לעדכן רק כרטיסים שמציגים קישורים בתצוגה מקדימה כתגובה לאירוע אינטראקציה עם אפליקציית Chat. אפליקציות Chat לא יכולות לעדכן את הכרטיסים האלה באמצעות קריאה אסינכרונית ל-Chat API.

תצוגה מקדימה של קישור לא תומכת בהחזרת ActionResponse מסוג UPDATE_MESSAGE. בגלל ש-UPDATE_MESSAGE מעדכנת את כל ההודעה, ולא רק את הכרטיס, היא פועלת רק אם ההודעה המקורית נוצרה באפליקציית Chat. בתצוגה המקדימה של הקישור מצורף כרטיס להודעה שנוצרה על ידי משתמש, ולכן לאפליקציית Chat אין הרשאה לעדכן את ההודעה.

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

  • אם משתמש מסוים יצר את ההודעה, מגדירים את ActionResponse לערך UPDATE_USER_MESSAGE_CARDS.
  • אם ההודעה נוצרה על ידי אפליקציה של Chat, צריך להגדיר את ActionResponse לערך UPDATE_MESSAGE.

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

אפשרות 1: חיפוש actionMethodName

כדי להשתמש ב-actionMethodName כדי לטפל כראוי באירועי אינטראקציה של CARD_CLICKED בכרטיסים שמוצגים בתצוגה מקדימה, צריך להגדיר actionMethodName בהתאמה אישית כחלק מהמאפיין onclick של הכרטיס המצורף:

JSON

. . . // Preview card details
{
  "textButton": {
    "text": "ASSIGN TO ME",
    "onClick": {

      // actionMethodName identifies the button to help determine the
      // appropriate ActionResponse.
      "action": {
        "actionMethodName": "assign",
      }
    }
  }
}
. . . // Preview card details

כאשר "actionMethodName": "assign" מזהה את הלחצן כחלק מהתצוגה המקדימה של הקישור, אפשר להחזיר באופן דינמי את ה-ActionResponse הנכון על ידי חיפוש actionMethodName תואם:

Node.js

node/preview-link/update-card.js
/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    return res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Respond to button clicks on attached cards
  if (req.body.type === 'CARD_CLICKED') {
    // Checks for the presence of "actionMethodName": "assign" and sets
    // actionResponse.type to "UPDATE_USER"MESSAGE_CARDS" if present or
    // "UPDATE_MESSAGE" if absent.
    const actionResponseType = req.body.action.actionMethodName === 'assign' ?
      'UPDATE_USER_MESSAGE_CARDS' :
      'UPDATE_MESSAGE';

    if (req.body.action.actionMethodName === 'assign') {
      return res.json({
        'actionResponse': {

          // Dynamically returns the correct actionResponse type.
          'type': actionResponseType,
        },

        // Preview card details
        'cardsV2': [{}],
      });
    }
  }
};

Apps Script

apps-script/preview-link/update-card.gs
/**
 * Updates a card that was attached to a message with a previewed link.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. Either a new card attached to
 * the message with the previewed link, or an update to an existing card.
 */
function onCardClick(event) {
  // Checks for the presence of "actionMethodName": "assign" and sets
  // actionResponse.type to "UPDATE_USER"MESSAGE_CARDS" if present or
  // "UPDATE_MESSAGE" if absent.
  const actionResponseType = event.action.actionMethodName === 'assign' ?
    'UPDATE_USER_MESSAGE_CARDS' :
    'UPDATE_MESSAGE';

  if (event.action.actionMethodName === 'assign') {
    return assignCase(actionResponseType);
  }
}

/**
 * Updates a card to say that "You" are the assignee after clicking the Assign
 * to Me button.
 *
 * @param {String} actionResponseType Which actionResponse the Chat app should
 * use to update the attached card based on who created the message.
 * @return {Object} Response from the Chat app. Updates the card attached to
 * the message with the previewed link.
 */
function assignCase(actionResponseType) {
  return {
    'actionResponse': {

      // Dynamically returns the correct actionResponse type.
      'type': actionResponseType,
    },
    // Preview card details
    'cardsV2': [{}],
  };
}

אפשרות 2: בודקים את סוג השולח

צריך לבדוק אם message.sender.type הוא HUMAN או BOT. אם HUMAN, מגדירים את ActionResponse כ-UPDATE_USER_MESSAGE_CARDS. אם לא, מגדירים את ActionResponse כ-UPDATE_MESSAGE. לשם כך:

Node.js

node/preview-link/sender-type.js
/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    return res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Respond to button clicks on attached cards
  if (req.body.type === 'CARD_CLICKED') {
    // Checks whether the message event originated from a human or a Chat app
    // and sets actionResponse.type to "UPDATE_USER_MESSAGE_CARDS if human or
    // "UPDATE_MESSAGE" if Chat app.
    const actionResponseType = req.body.action.actionMethodName === 'HUMAN' ?
      'UPDATE_USER_MESSAGE_CARDS' :
      'UPDATE_MESSAGE';

    return res.json({
      'actionResponse': {

        // Dynamically returns the correct actionResponse type.
        'type': actionResponseType,
      },

      // Preview card details
      'cardsV2': [{}],
    });
  }
};

Apps Script

apps-script/preview-link/sender-type.gs
/**
 * Updates a card that was attached to a message with a previewed link.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. Either a new card attached to
 * the message with the previewed link, or an update to an existing card.
 */
function onCardClick(event) {
  // Checks whether the message event originated from a human or a Chat app
  // and sets actionResponse.type to "UPDATE_USER_MESSAGE_CARDS if human or
  // "UPDATE_MESSAGE" if Chat app.
  const actionResponseType = event.message.sender.type === 'HUMAN' ?
    'UPDATE_USER_MESSAGE_CARDS' :
    'UPDATE_MESSAGE';

  return assignCase(actionResponseType);
}

/**
 * Updates a card to say that "You" are the assignee after clicking the Assign
 * to Me button.
 *
 * @param {String} actionResponseType Which actionResponse the Chat app should
 * use to update the attached card based on who created the message.
 * @return {Object} Response from the Chat app. Updates the card attached to
 * the message with the previewed link.
 */
function assignCase(actionResponseType) {
  return {
    'actionResponse': {

      // Dynamically returns the correct actionResponse type.
      'type': actionResponseType,
    },
    // Preview card details
    'cardsV2': [{}],
  };
}

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

דוגמה מלאה: בקשת תמיכה באפליקציית Chat של שירות הלקוחות

זהו הקוד המלא ל-Case-y, אפליקציה ב-Chat שמציגה תצוגה מקדימה של קישורים לבקשות תמיכה ששותפו במרחב משותף ב-Chat שבו נציגי שירות הלקוחות משתפים פעולה.

Node.js

node/preview-link/preview-link.js
/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    return res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Respond to button clicks on attached cards
  if (req.body.type === 'CARD_CLICKED') {
    // Checks whether the message event originated from a human or a Chat app
    // and sets actionResponse.type to "UPDATE_USER_MESSAGE_CARDS if human or
    // "UPDATE_MESSAGE" if Chat app.
    const actionResponseType = req.body.action.actionMethodName === 'HUMAN' ?
      'UPDATE_USER_MESSAGE_CARDS' :
      'UPDATE_MESSAGE';

    if (req.body.action.actionMethodName === 'assign') {
      return res.json(createMessage(actionResponseType, 'You'));
    }
  }

  // Checks for the presence of event.message.matchedUrl and attaches a card
  // if present
  if (req.body.message.matchedUrl) {
    return res.json(createMessage());
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return res.json({'text': 'No matchedUrl detected.'});
};

/**
 * Message to create a card with the correct response type and assignee.
 *
 * @param {string} actionResponseType
 * @param {string} assignee
 * @return {Object} a card with URL preview
 */
function createMessage(
  actionResponseType = 'UPDATE_USER_MESSAGE_CARDS',
  assignee = 'Charlie'
) {
  return {
    'actionResponse': {'type': actionResponseType},
    'cardsV2': [
      {
        'cardId': 'previewLink',
        'card': {
          'header': {
            'title': 'Example Customer Service Case',
            'subtitle': 'Case basics',
          },
          'sections': [
            {
              'widgets': [
                {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
                {'keyValue': {'topLabel': 'Assignee', 'content': assignee}},
                {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
                {
                  'keyValue': {
                    'topLabel': 'Subject', 'content': 'It won"t turn on...',
                  },
                },
              ],
            },
            {
              'widgets': [
                {
                  'buttons': [
                    {
                      'textButton': {
                        'text': 'OPEN CASE',
                        'onClick': {
                          'openLink': {
                            'url': 'https://support.example.com/orders/case123',
                          },
                        },
                      },
                    },
                    {
                      'textButton': {
                        'text': 'RESOLVE CASE',
                        'onClick': {
                          'openLink': {
                            'url': 'https://support.example.com/orders/case123?resolved=y',
                          },
                        },
                      },
                    },
                    {
                      'textButton': {
                        'text': 'ASSIGN TO ME',
                        'onClick': {
                          'action': {
                            'actionMethodName': 'assign',
                          },
                        },
                      },
                    },
                  ],
                },
              ],
            },
          ],
        }
      },
    ],
  };
}

Apps Script

apps-script/preview-link/preview-link.gs
/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previews.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app attached to the message with
 * the previewed link.
 */
function onMessage(event) {
  // Checks for the presence of event.message.matchedUrl and attaches a card
  // if present
  if (event.message.matchedUrl) {
    return {
      'actionResponse': {
        'type': 'UPDATE_USER_MESSAGE_CARDS',
      },
      'cardsV2': [{
        'cardId': 'previewLink',
        'card': {
          'header': {
            'title': 'Example Customer Service Case',
            'subtitle': 'Case basics',
          },
          'sections': [{
            'widgets': [
              {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
              {'keyValue': {'topLabel': 'Assignee', 'content': 'Charlie'}},
              {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
              {
                'keyValue': {
                  'topLabel': 'Subject', 'content': 'It won\'t turn on...',
                }
              },
            ],
          },
          {
            'widgets': [{
              'buttons': [
                {
                  'textButton': {
                    'text': 'OPEN CASE',
                    'onClick': {
                      'openLink': {
                        'url': 'https://support.example.com/orders/case123',
                      },
                    },
                  },
                },
                {
                  'textButton': {
                    'text': 'RESOLVE CASE',
                    'onClick': {
                      'openLink': {
                        'url': 'https://support.example.com/orders/case123?resolved=y',
                      },
                    },
                  },
                },
                {
                  'textButton': {
                    'text': 'ASSIGN TO ME',
                    'onClick': {'action': {'actionMethodName': 'assign'}}
                  },
                },
              ],
            }],
          }],
        },
      }],
    };
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return {'text': 'No matchedUrl detected.'};
}

/**
 * Updates a card that was attached to a message with a previewed link.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. Either a new card attached to
 * the message with the previewed link, or an update to an existing card.
 */
function onCardClick(event) {
  // Checks whether the message event originated from a human or a Chat app
  // and sets actionResponse to "UPDATE_USER_MESSAGE_CARDS if human or
  // "UPDATE_MESSAGE" if Chat app.
  const actionResponseType = event.message.sender.type === 'HUMAN' ?
    'UPDATE_USER_MESSAGE_CARDS' :
    'UPDATE_MESSAGE';

  // To respond to the correct button, checks the button's actionMethodName.
  if (event.action.actionMethodName === 'assign') {
    return assignCase(actionResponseType);
  }
}

/**
 * Updates a card to say that "You" are the assignee after clicking the Assign
 * to Me button.
 *
 * @param {String} actionResponseType Which actionResponse the Chat app should
 * use to update the attached card based on who created the message.
 * @return {Object} Response from the Chat app. Updates the card attached to
 * the message with the previewed link.
 */
function assignCase(actionResponseType) {
  return {
    'actionResponse': {

      // Dynamically returns the correct actionResponse type.
      'type': actionResponseType,
    },
    'cardsV2': [{
      'cardId': 'assignCase',
      'card': {
        'header': {
          'title': 'Example Customer Service Case',
          'subtitle': 'Case basics',
        },
        'sections': [{
          'widgets': [
            {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
            {'keyValue': {'topLabel': 'Assignee', 'content': 'You'}},
            {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
            {
              'keyValue': {
                'topLabel': 'Subject', 'content': 'It won\'t turn on...',
              }
            },
          ],
        },
        {
          'widgets': [{
            'buttons': [
              {
                'textButton': {
                  'text': 'OPEN CASE',
                  'onClick': {
                    'openLink': {
                      'url': 'https://support.example.com/orders/case123',
                    },
                  },
                },
              },
              {
                'textButton': {
                  'text': 'RESOLVE CASE',
                  'onClick': {
                    'openLink': {
                      'url': 'https://support.example.com/orders/case123?resolved=y',
                    },
                  },
                },
              },
              {
                'textButton': {
                  'text': 'ASSIGN TO ME',
                  'onClick': {'action': {'actionMethodName': 'assign'}},
                },
              },
            ],
          }],
        }],
      },
    }],
  };
}

מגבלות ושיקולים

כשמגדירים תצוגה מקדימה לקישורים באפליקציית Chat, חשוב להביא בחשבון את המגבלות והשיקולים הבאים:

  • בכל אפליקציית Chat יש תמיכה בתצוגה מקדימה של קישורים ב-5 תבניות URL לכל היותר.
  • אפליקציות צ'אט מוצגות בתצוגה מקדימה של קישור אחד לכל הודעה. אם בהודעה אחת יש כמה קישורים שאפשר להציג בתצוגה מקדימה, הם יופיעו רק בתצוגה המקדימה הראשונה של הקישורים.
  • באפליקציות צ'אט מוצגות תצוגה מקדימה רק של קישורים שמתחילים ב-https://, כך שב-https://support.example.com/cases/ תצוגות מקדימות, אבל ב-support.example.com/cases/ לא מוצגים קישורים כאלה.
  • אלא אם ההודעה כוללת מידע נוסף שנשלח לאפליקציית Chat, כמו פקודת לוכסן, רק כתובת ה-URL של הקישור נשלחת לאפליקציית Chat באמצעות תצוגה מקדימה של הקישורים.
  • כרטיסים שמצורפים לתצוגה מקדימה של קישורים תומכים רק ב-ActionResponse מסוג UPDATE_USER_MESSAGE_CARDS, ורק בתגובה לאירוע אינטראקציה עם אפליקציית Chat. התצוגה המקדימה של הקישורים לא תומכת ב-UPDATE_MESSAGE או בבקשות אסינכרוניות לעדכון כרטיסים שמצורפים לקישור שמוצג בתצוגה מקדימה דרך Chat API. מידע נוסף זמין במאמר עדכון כרטיס.

במהלך ההטמעה של תצוגות מקדימות לקישורים, יכול להיות שתצטרכו לקרוא את יומני האפליקציה כדי לנפות באגים באפליקציית Chat. כדי לקרוא את היומנים, צריך להיכנס ל-Logs Explorer במסוף Google Cloud.