پیش‌نمایش پیوندها در پیام‌های چت Google

برای جلوگیری از تغییر بافت زمانی که کاربران پیوندی را در چت Google به اشتراک می‌گذارند، برنامه چت شما می‌تواند با پیوست کردن کارتی به پیام آنها پیوند را پیش‌نمایش کند که اطلاعات بیشتری را ارائه می‌دهد و به افراد امکان می‌دهد مستقیماً از چت Google اقدام کنند.

در Google Chat، افزونه‌ها به عنوان برنامه‌های Google Chat برای کاربران ظاهر می‌شوند. برای کسب اطلاعات بیشتر، به نمای کلی Extend Google Chat مراجعه کنید.

به عنوان مثال، یک فضای چت Google را تصور کنید که شامل تمام نمایندگان خدمات مشتری یک شرکت به علاوه یک برنامه چت به نام Case-y است. نمایندگان اغلب پیوندهایی را به پرونده های خدمات مشتری در فضای چت به اشتراک می گذارند، و هر بار که این کار را انجام می دهند، همکارانشان باید پیوند پرونده را باز کنند تا جزئیاتی مانند گیرنده، وضعیت و موضوع را ببینند. به همین ترتیب، اگر کسی بخواهد مالکیت یک پرونده را در اختیار بگیرد یا وضعیت را تغییر دهد، باید پیوند را باز کند.

پیش‌نمایش پیوند، برنامه چت ساکن در فضا، Case-y، را قادر می‌سازد تا هر زمان که شخصی پیوند موردی را به اشتراک می‌گذارد، کارتی را که مأمور، وضعیت و موضوع را نشان می‌دهد، ضمیمه کند. دکمه های روی کارت به نمایندگان اجازه می دهد تا مالکیت پرونده را در دست بگیرند و وضعیت را مستقیماً از جریان چت تغییر دهند.

هنگامی که شخصی پیوندی را به پیام خود اضافه می‌کند، تراشه‌ای ظاهر می‌شود که به او اطلاع می‌دهد که برنامه چت ممکن است پیوند را پیش‌نمایش کند.

تراشه ای که نشان می دهد برنامه چت ممکن است یک پیوند را پیش نمایش کند

پس از ارسال پیام، لینک به برنامه چت ارسال می شود که سپس کارت را تولید کرده و به پیام کاربر متصل می کند.

برنامه چت در حال پیش‌نمایش پیوند با پیوست کردن کارتی به پیام

در کنار پیوند، کارت اطلاعات اضافی درباره پیوند، از جمله عناصر تعاملی مانند دکمه‌ها، ارائه می‌کند. برنامه گپ شما می تواند کارت پیوست شده را در پاسخ به تعاملات کاربر، مانند کلیک روی دکمه، به روز کند.

اگر کسی نمی‌خواهد برنامه چت پیوند او را با پیوست کردن کارتی به پیامش پیش‌نمایش کند، می‌تواند با کلیک روی روی تراشه پیش‌نمایش، از پیش‌نمایش جلوگیری کند. کاربران می توانند کارت پیوست شده را در هر زمان با کلیک بر روی حذف پیش نمایش حذف کنند.

پیش نیازها

Node.js

یک افزونه Google Workspace که گپ Google را گسترش می‌دهد. برای ایجاد یک، شروع سریع HTTP را تکمیل کنید.

اسکریپت برنامه ها

یک افزونه Google Workspace که گپ Google را گسترش می‌دهد. برای ایجاد یکی، شروع سریع Apps Script را تکمیل کنید.

پیوندهای خاص - مانند example.com ، support.example.com و support.example.com/cases/ - را به عنوان الگوهای URL در صفحه پیکربندی برنامه Chat خود در کنسول Google Cloud ثبت کنید تا برنامه Chat شما بتواند آنها را پیش نمایش کند.

منوی پیکربندی پیش نمایش پیوند

  1. کنسول Google Cloud را باز کنید.
  2. در کنار «Google Cloud»، روی پیکان رو به پایین کلیک کنید و پروژه برنامه چت خود را باز کنید.
  3. در قسمت جستجو، Google Chat API تایپ کنید و Google Chat API را کلیک کنید.
  4. روی Manage > Configuration کلیک کنید.
  5. در بخش پیش‌نمایش‌های پیوند، یک الگوی URL را اضافه یا ویرایش کنید.
    1. برای پیکربندی پیش‌نمایش پیوندها برای الگوی URL جدید، روی افزودن الگوی URL کلیک کنید.
    2. برای ویرایش پیکربندی الگوی URL موجود، روی پیکان رو به پایین کلیک کنید.

  6. در قسمت Host pattern ، دامنه الگوی URL را وارد کنید. برنامه چت پیوندهای این دامنه را پیش‌نمایش خواهد کرد.

    برای داشتن پیوندهای پیش‌نمایش برنامه گپ برای یک زیر دامنه خاص، مانند subdomain.example.com ، زیردامنه را نیز اضافه کنید.

    برای داشتن پیوندهای پیش‌نمایش برنامه چت برای کل دامنه، یک کاراکتر عام با ستاره (*) را به عنوان زیر دامنه مشخص کنید. برای مثال، *.example.com با subdomain.example.com و any.number.of.subdomains.example.com مطابقت دارد.

  7. در قسمت پیشوند مسیر ، مسیری را وارد کنید تا به دامنه الگوی میزبان اضافه شود.

    برای مطابقت با همه URL ها در دامنه الگوی میزبان، پیشوند مسیر را خالی بگذارید.

    به عنوان مثال، اگر الگوی میزبان support.example.com باشد، برای مطابقت با نشانی‌های وب برای موارد میزبانی شده در support.example.com/cases/ ، cases/ وارد کنید.

  8. روی Done کلیک کنید.

  9. روی ذخیره کلیک کنید.

اکنون، هر زمان که فردی پیوندی را وارد کند که با الگوی URL پیش‌نمایش پیوند با پیامی در فضای چت که شامل برنامه چت شما است مطابقت دارد، برنامه شما پیوند را پیش‌نمایش می‌کند.

پس از پیکربندی پیش‌نمایش پیوند برای یک پیوند معین، برنامه چت شما می‌تواند پیوند را با پیوست کردن اطلاعات بیشتر به آن شناسایی و پیش‌نمایش کند.

در داخل فضاهای گپ که شامل برنامه چت شما می‌شود، وقتی پیام شخصی حاوی پیوندی است که با الگوی URL پیش‌نمایش پیوند مطابقت دارد، برنامه Chat شما یک شی رویداد را با یک MessagePayload دریافت می‌کند. در payload، شی message.matchedUrl حاوی پیوندی است که کاربر در پیام قرار داده است:

JSON

message: {
  matchedUrl: {
    url: "https://support.example.com/cases/case123"
  },
  ... // other message attributes redacted
}

با بررسی وجود فیلد matchedUrl در محموله رویداد MESSAGE ، برنامه چت شما می‌تواند اطلاعاتی را با پیوند پیش‌نمایش‌شده به پیام اضافه کند. برنامه چت شما می‌تواند با یک پیام متنی ساده پاسخ دهد یا کارتی را پیوست کند.

با پیامک پاسخ دهید

برای پاسخ‌های اولیه، برنامه چت شما می‌تواند با پاسخ دادن پیام متنی به پیوند، پیش‌نمایش پیوند را مشاهده کند. این مثال پیامی را ضمیمه می‌کند که URL پیوند را تکرار می‌کند که با الگوی URL پیش‌نمایش پیوند مطابقت دارد.

Node.js 

/**
 * Google Cloud Function that handles messages that have links whose
 * URLs match URL patterns configured for link previewing.
 *
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.previewLinks = function previewLinks(req, res) {
  const chatEvent = req.body.chat;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handlePreviewLink(chatEvent.messagePayload.message));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    return res.send(handleCardClick(chatEvent.buttonClickedPayload.message));
  }
};

/**
 * Respond to messages that have links whose URLs match URL patterns configured
 * for link previewing.
 *
 * @param {Object} chatMessage The chat message object from Google Workspace Add On event.
 * @return {Object} Response to send back depending on the matched URL.
 */
function handlePreviewLink(chatMessage) {
  // If the Chat app does not detect a link preview URL pattern, reply
  // with a text message that says so.
  if (!chatMessage.matchedUrl) {
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'No matchedUrl detected.'
    }}}}};
  }

  // Reply with a text message for URLs of the subdomain "text"
  if (chatMessage.matchedUrl.url.includes("text.example.com")) {
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'event.chat.messagePayload.message.matchedUrl.url: ' + chatMessage.matchedUrl.url
    }}}}};
  }
}

اسکریپت برنامه ها 

/**
 * Reply to messages that have links whose URLs match the pattern
 * "text.example.com" configured for link previewing.
 *
 * @param {Object} event The event object from Google Workspace Add-on.
 *
 * @return {Object} The action response.
 */
function onMessage(event) {
  // Stores the Google Chat event as a variable.
  const chatMessage = event.chat.messagePayload.message;

  // If the Chat app doesn't detect a link preview URL pattern, reply
  // with a text message that says so.
  if (!chatMessage.matchedUrl) {
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'No matchedUrl detected.'
    }}}}};
  }

  // Reply with a text message for URLs of the subdomain "text".
  if (chatMessage.matchedUrl.url.includes("text.example.com")) {
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'event.chat.messagePayload.message.matchedUrl.url: ' + chatMessage.matchedUrl.url
    }}}}};
  }
}

برای پیوست کردن کارت به پیوند پیش‌نمایش‌شده، اقدام DataActions را با شی ChatDataActionMarkup از نوع UpdateInlinePreviewAction برگردانید.

در مثال زیر، یک برنامه Chat یک کارت پیش‌نمایش به پیام‌هایی که حاوی الگوی URL support.example.com هستند اضافه می‌کند.

برنامه چت در حال پیش‌نمایش پیوند با پیوست کردن کارتی به پیام

Node.js 

/**
 * Google Cloud Function that handles messages that have links whose
 * URLs match URL patterns configured for link previewing.
 *
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.previewLinks = function previewLinks(req, res) {
  const chatEvent = req.body.chat;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handlePreviewLink(chatEvent.messagePayload.message));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    return res.send(handleCardClick(chatEvent.buttonClickedPayload.message));
  }
};

/**
 * Respond to messages that have links whose URLs match URL patterns configured
 * for link previewing.
 *
 * @param {Object} chatMessage The chat message object from Google Workspace Add On event.
 * @return {Object} Response to send back depending on the matched URL.
 */
function handlePreviewLink(chatMessage) {
  // Attach a card to the message for URLs of the subdomain "support"
  if (chatMessage.matchedUrl.url.includes("support.example.com")) {
    // A hard-coded card is used in this example. In a real-life scenario,
    // the case information would be fetched and used to build the card.
    return { hostAppDataAction: { chatDataAction: { updateInlinePreviewAction: { cardsV2: [{
      cardId: 'attachCard',
      card: {
        header: {
          title: 'Example Customer Service Case',
          subtitle: 'Case basics',
        },
        sections: [{ widgets: [
        { decoratedText: { topLabel: 'Case ID', text: 'case123'}},
        { decoratedText: { topLabel: 'Assignee', text: 'Charlie'}},
        { decoratedText: { topLabel: 'Status', text: 'Open'}},
        { decoratedText: { topLabel: 'Subject', text: 'It won\'t turn on...' }},
        { buttonList: { buttons: [{
          text: 'OPEN CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123'
          }},
        }, {
          text: 'RESOLVE CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123?resolved=y',
          }},
        }, {
          text: 'ASSIGN TO ME',
          // Use runtime environment variable set with self URL
          onClick: { action: { function: process.env.BASE_URL }}
        }]}}
        ]}]
      }
    }]}}}};
  }
}

اسکریپت برنامه ها

این مثال با برگرداندن کارت JSON یک پیام کارت ارسال می کند. همچنین می‌توانید از سرویس کارت برنامه‌های اسکریپت استفاده کنید. 

/**
 * Attach a card to messages that have links whose URLs match the pattern
 * "support.example.com" configured for link previewing.
 *
 * @param {Object} event The event object from Google Workspace Add-on.
 *
 * @return {Object} The action response.
 */
function onMessage(event) {
  // Stores the Google Chat event as a variable.
  const chatMessage = event.chat.messagePayload.message;

  // Attach a card to the message for URLs of the subdomain "support".
  if (chatMessage.matchedUrl.url.includes("support.example.com")) {
    // A hard-coded card is used in this example. In a real-life scenario,
    // the case information would be fetched and used to build the card.
    return { hostAppDataAction: { chatDataAction: { updateInlinePreviewAction: { cardsV2: [{
      cardId: 'attachCard',
      card: {
        header: {
          title: 'Example Customer Service Case',
          subtitle: 'Case summary',
        },
        sections: [{ widgets: [
        { decoratedText: { topLabel: 'Case ID', text: 'case123'}},
        { decoratedText: { topLabel: 'Assignee', text: 'Charlie'}},
        { decoratedText: { topLabel: 'Status', text: 'Open'}},
        { decoratedText: { topLabel: 'Subject', text: 'It won\'t turn on...' }},
        { buttonList: { buttons: [{
          text: 'OPEN CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123'
          }},
        }, {
          text: 'RESOLVE CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123?resolved=y',
          }},
        }, {
          text: 'ASSIGN TO ME',
          // Clicking this button triggers the execution of the function
          // "assign" from the Apps Script project.
          onClick: { action: { function: 'assign'}}
        }]}}
        ]}]
      }
    }]}}}};
  }
}

برنامه چت شما می‌تواند یک کارت پیش‌نمایش پیوند را هنگامی که کاربران با آن تعامل دارند، مانند کلیک کردن روی دکمه روی کارت، به‌روزرسانی کند.

برای به‌روزرسانی کارت، برنامه Chat شما باید اقدام DataActions را با یکی از اشیاء ChatDataActionMarkup زیر برگرداند:

  • اگر کاربری پیام را فرستاد، یک شی UpdateMessageAction را برگردانید.
  • اگر برنامه چت پیام را ارسال کرد، یک شی UpdateInlinePreviewAction را برگردانید.

برای تعیین اینکه چه کسی پیام را ارسال کرده است، از بار رویداد ( buttonClickedPayload ) استفاده کنید تا بررسی کنید فرستنده ( message.sender.type ) روی HUMAN (کاربر) یا BOT (برنامه چت) تنظیم شده است.

مثال زیر نشان می‌دهد که چگونه یک برنامه چت با به‌روزرسانی فیلد Assignee کارت و غیرفعال کردن دکمه، پیش‌نمایش پیوند را هر زمان که کاربر روی دکمه Assign to Me کلیک می‌کند، به‌روزرسانی می‌کند.

برنامه چت در حال پیش‌نمایش پیوند با نسخه به‌روزشده کارت متصل به پیام

Node.js 

/**
 * Google Cloud Function that handles messages that have links whose
 * URLs match URL patterns configured for link previewing.
 *
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.previewLinks = function previewLinks(req, res) {
  const chatEvent = req.body.chat;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handlePreviewLink(chatEvent.messagePayload.message));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    return res.send(handleCardClick(chatEvent.buttonClickedPayload.message));
  }
};

/**
 * Respond to clicks by assigning user and updating the card that was attached to a
 * message with a previewed link.
 *
 * @param {Object} chatMessage The chat message object from Google Workspace Add On event.
 * @return {Object} Action response depending on the original message.
 */
function handleCardClick(chatMessage) {
  // Creates the updated card that displays "You" for the assignee
  // and that disables the button.
  //
  // A hard-coded card is used in this example. In a real-life scenario,
  // an actual assign action would be performed before building the card.
  const message = { cardsV2: [{
    cardId: 'attachCard',
    card: {
      header: {
        title: 'Example Customer Service Case',
        subtitle: 'Case basics',
      },
      sections: [{ widgets: [
        { decoratedText: { topLabel: 'Case ID', text: 'case123'}},
        // The assignee is now "You"
        { decoratedText: { topLabel: 'Assignee', text: 'You'}},
        { decoratedText: { topLabel: 'Status', text: 'Open'}},
        { decoratedText: { topLabel: 'Subject', text: 'It won\'t turn on...' }},
        { buttonList: { buttons: [{
          text: 'OPEN CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123'
          }},
        }, {
          text: 'RESOLVE CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123?resolved=y',
          }},
        }, {
          text: 'ASSIGN TO ME',
          // The button is now disabled
          disabled: true,
          // Use runtime environment variable set with self URL
          onClick: { action: { function: process.env.BASE_URL }}
        }]}}
      ]}]
    }
  }]};

  // Checks whether the message event originated from a human or a Chat app
  // to return the adequate action response.
  if(chatMessage.sender.type === 'HUMAN') {
    return { hostAppDataAction: { chatDataAction: { updateInlinePreviewAction: message }}};
  } else {
    return { hostAppDataAction: { chatDataAction: { updateMessageAction: message }}};
  }
}

اسکریپت برنامه ها

این مثال با برگرداندن کارت JSON یک پیام کارت ارسال می کند. همچنین می‌توانید از سرویس کارت برنامه‌های اسکریپت استفاده کنید. 

/**
 * Assigns and updates the card that's attached to a message with a
 * previewed link of the pattern "support.example.com".
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 *
 * @return {Object} Action response depending on the message author.
 */
function assign(event) {
  // Creates the updated card that displays "You" for the assignee
  // and that disables the button.
  //
  // A hard-coded card is used in this example. In a real-life scenario,
  // an actual assign action would be performed before building the card.
  const message = { cardsV2: [{
    cardId: 'attachCard',
    card: {
      header: {
        title: 'Example Customer Service Case',
        subtitle: 'Case summary',
      },
      sections: [{ widgets: [
        { decoratedText: { topLabel: 'Case ID', text: 'case123'}},
        // The assignee is now "You"
        { decoratedText: { topLabel: 'Assignee', text: 'You'}},
        { decoratedText: { topLabel: 'Status', text: 'Open'}},
        { decoratedText: { topLabel: 'Subject', text: 'It won\'t turn on...' }},
        { buttonList: { buttons: [{
          text: 'OPEN CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123'
          }},
        }, {
          text: 'RESOLVE CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123?resolved=y',
          }},
        }, {
          text: 'ASSIGN TO ME',
          // The button is now disabled
          disabled: true,
          onClick: { action: { function: 'assign'}}
        }]}}
      ]}]
    }
  }]};

  // Use the adequate action response type. It depends on whether the message
  // the preview link card is attached to was created by a human or a Chat app.
  if(event.chat.buttonClickedPayload.message.sender.type === 'HUMAN') {
    return { hostAppDataAction: { chatDataAction: { updateInlinePreviewAction: message }}};
  } else {
    return { hostAppDataAction: { chatDataAction: { updateMessageAction: message }}};
  }
}

محدودیت ها و ملاحظات

همانطور که پیش نمایش پیوندها را برای برنامه چت خود پیکربندی می کنید، به این محدودیت ها و ملاحظات توجه کنید:

  • هر برنامه چت از پیش نمایش پیوند برای حداکثر 5 الگوی URL پشتیبانی می کند.
  • برنامه‌های چت یک پیوند را در هر پیام پیش‌نمایش می‌کنند. اگر چندین پیوند قابل پیش‌نمایش در یک پیام وجود داشته باشد، تنها اولین پیوند قابل پیش‌نمایش پیش‌نمایش می‌شود.
  • برنامه‌های چت فقط پیوندهایی را پیش‌نمایش می‌کنند که با https:// شروع می‌شوند، بنابراین https://support.example.com/cases/ پیش‌نمایش می‌کند، اما support.example.com/cases/ این کار را نمی‌کند.
  • مگر اینکه پیام حاوی اطلاعات دیگری باشد که به برنامه چت ارسال می‌شود، مانند دستور اسلش ، فقط URL پیوند با پیش‌نمایش پیوند به برنامه چت ارسال می‌شود.
  • اگر کاربری پیوند را پست کند، برنامه چت تنها در صورتی می‌تواند کارت پیش‌نمایش پیوند را به‌روزرسانی کند که کاربران با کارت تعامل داشته باشند، مثلاً با کلیک دکمه. نمی‌توانید برای به‌روزرسانی پیام کاربر به‌صورت ناهمزمان، روش Chat API's update() در منبع Message فراخوانی کنید.
  • برنامه‌های چت باید پیوندها را برای همه افراد موجود در فضا پیش‌نمایش کنند، بنابراین پیام باید قسمت privateMessageViewer را حذف کند.

همانطور که پیش‌نمایش پیوندها را پیاده‌سازی می‌کنید، ممکن است لازم باشد برنامه چت خود را با خواندن گزارش‌های برنامه اشکال‌زدایی کنید. برای خواندن گزارش‌ها، از Logs Explorer در کنسول Google Cloud دیدن کنید.