1. Giới thiệu
Các ứng dụng trong Google Chat đưa các dịch vụ và tài nguyên vào ngay trong Chat, nơi người dùng có thể nhận thông tin và thực hiện hành động mà không cần rời khỏi cuộc trò chuyện.
Trong lớp học lập trình này, bạn sẽ tìm hiểu cách tạo một ứng dụng trong Chat – "Ứng dụng Chat về sự hiện diện" – ứng dụng này sẽ thiết lập tính năng trả lời tự động khi đi nghỉ trong Gmail và lên lịch các cuộc họp trong Lịch Google. Bằng cách xây dựng ứng dụng Chat về sự hiện diện trong Google Apps Script, bạn có thể dễ dàng truy cập vào các dịch vụ khác của Google như Drive, Gmail, Lịch, Tài liệu, Trang tính và nhiều dịch vụ khác.
Kiến thức bạn sẽ học được
- Cách thêm trình xử lý vào các sự kiện được tạo trong Chat
- Cách phân tích cú pháp các đối tượng sự kiện được gửi từ Chat
- Cách phản hồi lại Chat bằng các phản hồi ở định dạng thẻ
- Cách xác định và phản ứng với các hành động tuỳ chỉnh cho các lượt nhấp vào nút trong thẻ
Bạn cần có
- Quyền truy cập vào Internet và một trình duyệt web.
- Một tài khoản Google Workspace có quyền truy cập vào Google Chat.
- Các kỹ năng cơ bản về JavaScript – Google Apps Script chỉ hỗ trợ JavaScript.
2. Nhận mã mẫu
Bạn có thể tải tệp ZIP xuống hoặc sao chép kho lưu trữ GitHub để xem mã cho từng bước trong mẫu này.
Các thư mục step-NN trong apps-script/attendance-chat-app chứa trạng thái cuối cùng của từng bước trong lớp học lập trình này. Chúng được cung cấp để bạn tham khảo.
Tải mã xuống
Để tải mã xuống cho lớp học lập trình này, hãy nhấp vào nút sau:
Giải nén tệp ZIP đã tải xuống. Thao tác này sẽ giải nén một thư mục gốc (google-chat-samples), chứa một thư mục cho mỗi bước của lớp học lập trình này trong apps-script/attendance-chat-app.
Sao chép kho lưu trữ GitHub
Để sao chép kho lưu trữ GitHub cho lớp học lập trình này, hãy chạy lệnh sau:
git clone https://github.com/googleworkspace/google-chat-samples
3. Tạo trình xử lý cho các sự kiện trong Google Chat
Tạo dự án Apps Script
Để tạo dự án Apps Script, hãy làm theo các bước sau:
- Chuyển đến script.new.
- Nhấp vào Dự án chưa đặt tên.
- Đổi tên tập lệnh thành Ứng dụng Chat về sự hiện diện rồi nhấp vào Đổi tên.
Sự kiện trong Google Chat
Hầu hết các lượt tương tác của Apps Script với Chat đều dựa trên sự kiện. Lượt tương tác giữa người dùng, ứng dụng trong Chat và Chat thường tuân theo trình tự sau:
- Người dùng bắt đầu một hành động, chẳng hạn như thêm ứng dụng trong Chat vào một không gian, bắt đầu tin nhắn trực tiếp (DM) với một ứng dụng trong Chat hoặc xoá một ứng dụng trong Chat khỏi một không gian.
- Hành động này tạo ra một sự kiện nhắm đến ứng dụng trong Chat.
- Chat gọi trình xử lý sự kiện tương ứng được xác định trong tập lệnh của ứng dụng trong Chat.
Chat tạo ra 4 sự kiện mà ứng dụng của bạn có thể theo dõi:
ADDED_TO_SPACE: Sự kiện này xảy ra khi một người dùng thêm một ứng dụng trong Chat vào một không gian hoặc tin nhắn trực tiếp (DM). Trong Apps Script, bạn xác định hàmonAddToSpace()để xử lý sự kiện này.REMOVED_FROM_SPACE: Sự kiện này xảy ra khi người dùng xoá ứng dụng trong Chat khỏi một không gian hoặc DM. Sự kiện này không đăng phản hồi trở lại Chat. Trong Apps Script, bạn xác định hàmonRemoveFromSpace()để xử lý sự kiện này.MESSAGE: Sự kiện này xảy ra khi người dùng nhắn tin cho ứng dụng trong Chat, trực tiếp trong DM hoặc dưới dạng lượt đề cập bằng @trong một không gian. Trong Apps Script, bạn xác định hàmonMessage()để phản hồi sự kiện này.CARD_CLICKED: Sự kiện này xảy ra khi người dùng nhấp vào một nút có hành động tuỳ chỉnh được gán cho nút đó. Trong Apps Script, bạn xác định hàmonCardClick()để phản hồi sự kiện này.
Thay thế nội dung của tệp Code.gs bằng mã sau đây xác định trình xử lý cho các sự kiện ADDED_TO_SPACE và REMOVE_FROM_SPACE. (Bạn sẽ thêm trình xử lý cho các sự kiện MESSAGE và CARD_CLICKED sau trong lớp học lập trình này.)
Code.gs
/**
* Responds to an ADDED_TO_SPACE event in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onAddToSpace(event) {
console.info(event);
var message = 'Thank you for adding me to ';
if (event.space.type === 'DM') {
message += 'a DM, ' + event.user.displayName + '!';
} else {
message += event.space.displayName;
}
return { text: message };
}
/**
* Responds to a REMOVED_FROM_SPACE event in Google Chat.
* @param {object} event the event object from Google Chat
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onRemoveFromSpace(event) {
console.info(event);
console.log('Chat app removed from ', event.space.name);
}
4. Phát hành và kiểm thử ứng dụng trong Chat
Cập nhật tệp kê khai tập lệnh
Trước khi có thể phát hành ứng dụng lên Chat, bạn phải cập nhật tệp kê khai tập lệnh.
- Nhấp vào Cài đặt dự án
. - Chọn hộp kiểm Hiển thị tệp kê khai "appsscript.json" trong trình chỉnh sửa.
- Nhấp vào Trình chỉnh sửa
. - Nhấp vào tệp
appsscript.json. - Thêm dòng
"chat": {}vào tệp kê khai.
Tệp kê khai của bạn sẽ có dạng như ví dụ sau.
appsscript.json
{
"timeZone": "America/Los_Angeles",
"dependencies": {
},
"chat": {}
}
Tạo dự án trên Google Cloud
Trước khi có thể chạy và kiểm thử ứng dụng trong Chat, bạn phải tạo một dự án trên Google Cloud, bật và định cấu hình API Chat, đồng thời phát hành ứng dụng trong Chat lên tổ chức Google Workspace.
- Trong Google Cloud Console, hãy chuyển đến biểu tượng Trình đơn
> IAM và Quản trị viên > Tạo dự án. - Đối với Tên dự án, hãy nhập tên mô tả.
- Nếu được nhắc, hãy chọn Tổ chức và Tài khoản thanh toán.
- Nhấp vào Tạo.
- Khi quá trình tạo dự án hoàn tất, một thông báo sẽ xuất hiện ở phía trên bên phải của trang. Nhấp vào mục Tạo dự án: <Tên dự án> để mở dự án.
- Nhấp vào biểu tượng Trình đơn > API và Dịch vụ > Thông tin xác thực.
- Nhấp vào Màn hình đồng ý OAuth.
- Đối với Tên ứng dụng, hãy nhập Ứng dụng Chat về sự hiện diện.
- Nếu được nhắc, hãy nhập email hỗ trợ người dùng và thông tin liên hệ của nhà phát triển.
- Nhấp vào Lưu và tiếp tục.
- Nhấp vào biểu tượng Cài đặt và tiện ích
> Cài đặt dự án. - Sao chép Số dự án.
- Quay lại trình chỉnh sửa Tập lệnh ứng dụng, nhấp vào Cài đặt dự án .
- Trong phần Dự án trên Google Cloud Platform (GCP), hãy nhấp vào Thay đổi dự án.
- Nhấp vào Số dự án GCP rồi nhập số dự án.
- Nhấp vào Đặt dự án.
Phát hành ứng dụng lên Chat
Để phát hành ứng dụng trong Chat lên Google Chat, hãy làm như sau:
- Trong trình chỉnh sửa Apps Script, hãy nhấp vào Triển khai > Triển khai mới.
- Bên cạnh Chọn loại , hãy nhấp vào biểu tượng Bật các loại hoạt động triển khai .
- Chọn Tiện ích bổ sung rồi nhấp vào Triển khai.
- Sao chép Mã hoạt động triển khai rồi nhấp vào Xong.
- Trong Google Cloud Console, hãy chuyển đến biểu tượng Trình đơn > API và dịch vụ > Thư viện.
- Tìm API Google Chat. Chọn API trong danh sách kết quả.
- Trên trang API Google Chat, hãy nhấp vào Bật.
- Sau khi bật API, hãy nhấp vào Định cấu hình. Bỏ qua mọi thông báo yêu cầu bạn tạo thông tin xác thực.
- Trên trang Định cấu hình, hãy làm như sau:
- Xoá Xây dựng ứng dụng trong Chat này dưới dạng tiện ích bổ sung cho Workspace rồi nhấp vào TẮT để xác nhận.
- Đối với Tên ứng dụng, hãy nhập Ứng dụng Chat về sự hiện diện.
- Đối với URL hình đại diện, hãy nhập https://goo.gl/kv2ENA.
- Đối với Mô tả, hãy nhập Ứng dụng trong Chat của lớp học lập trình Apps Script.
- Trong phần Chức năng, hãy chọn Nhận tin nhắn riêng tư.
- Trong phần Cài đặt kết nối, hãy chọn Dự án Apps Script rồi dán Mã hoạt động triển khai của tập lệnh vào hộp văn bản.
- Trong phần Quyền, hãy chọn Những người và nhóm cụ thể trong miền của bạn. Trong hộp văn bản bên dưới trình đơn thả xuống, hãy nhập địa chỉ email được liên kết với tổ chức Google Workspace của bạn.
- Nhấp vào Lưu.
Sau khi lưu các thay đổi, hãy xác minh rằng trạng thái trên trang API Google Chat hiển thị Trạng thái ứng dụng là ĐANG HOẠT ĐỘNG – có sẵn cho người dùng.
Kiểm thử ứng dụng trong Chat
Để kiểm thử ứng dụng trong Google Chat, hãy làm như sau:
- Mở Google Chat.
- Gửi một tin nhắn trực tiếp mới đến ứng dụng trong Chat bằng cách nhấp vào biểu tượng Bắt đầu cuộc trò chuyện
> Tìm ứng dụng. - Trên trang Tìm ứng dụng, hãy tìm Ứng dụng Chat về sự hiện diện.
- Bên cạnh Ứng dụng Chat về sự hiện diện, hãy nhấp vào Thêm > Chat.
Khi chuỗi tin nhắn trực tiếp mở ra, bạn sẽ thấy một tin nhắn từ ứng dụng trong Chat cảm ơn bạn đã thêm ứng dụng đó vào một DM, như minh hoạ trong hình ảnh sau.
5. Xác định phản hồi ở định dạng thẻ
Trong bước trước, ứng dụng của bạn đã phản hồi các sự kiện trong Google Chat bằng một phản hồi văn bản đơn giản. Trong bước này, bạn sẽ cập nhật ứng dụng để phản hồi bằng thẻ.
Phản hồi bằng thẻ
Google Chat hỗ trợ việc sử dụng thẻ cho các phản hồi. Thẻ là các vùng chứa trực quan cho phép bạn nhóm các tập hợp tiện ích giao diện người dùng lại với nhau. Thẻ có thể hiển thị tiêu đề, đoạn văn bản, tập hợp nút, hình ảnh và văn bản khoá/giá trị. Ứng dụng của bạn có thể xác định một hoặc nhiều thẻ trong phản hồi JSON của ứng dụng đó đối với Google Chat. Sau đó, Google Chat sẽ dịch phản hồi của bạn thành các phần tử tương ứng trên giao diện người dùng.
Hình ảnh sau đây cho thấy một phản hồi bằng thẻ có 3 phần, bao gồm tiêu đề, tiện ích khoá/giá trị, tiện ích hình ảnh và nút văn bản.
Để phản hồi tin nhắn của người dùng bằng phản hồi bằng thẻ, hãy thêm mã sau vào tệp Code.gs của ứng dụng trong Chat.
Code.gs
const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
header: {
title : 'Attendance Chat app',
subtitle : 'Log your vacation time',
imageUrl : DEFAULT_IMAGE_URL
}
};
/**
* Creates a card-formatted response.
* @param {object} widgets the UI components to send
* @return {object} JSON-formatted response
*/
function createCardResponse(widgets) {
return {
cards: [HEADER, {
sections: [{
widgets: widgets
}]
}]
};
}
/**
* Responds to a MESSAGE event triggered
* in Google Chat.
*
* @param event the event object from Google Chat
* @return JSON-formatted response
*/
function onMessage(event) {
const userMessage = event.message.text;
const widgets = [{
"textParagraph": {
"text": "You said: " + userMessage
}
}];
return createCardResponse(widgets);
}
Hàm onMessage(), được thêm trong bước này, đọc tin nhắn gốc của người dùng và tạo phản hồi dưới dạng tiện ích TextParagragh đơn giản. Sau đó, hàm onMessage() gọi createCardResponse(), hàm này sẽ đặt tiện ích TextParagraph trong một phần của một thẻ. Ứng dụng trong Chat trả về đối tượng JavaScript được tạo bằng phản hồi bằng thẻ cho Google Chat.
Kiểm thử ứng dụng trong Chat
Để kiểm thử ứng dụng này, hãy quay lại tin nhắn trực tiếp của bạn với ứng dụng trong Google Chat rồi nhập một tin nhắn (bạn có thể nhập bất kỳ tin nhắn nào).
Xin lưu ý rằng trình xử lý sự kiện onMessage() phân tích cú pháp đối tượng sự kiện do Google Chat truyền đến để trích xuất tin nhắn gốc của người dùng. Bạn cũng có thể nhận được các loại thông tin khác về sự kiện, bao gồm tên của người dùng đã bắt đầu sự kiện, địa chỉ email của họ, tên của không gian mà sự kiện xảy ra và nhiều thông tin khác.
Để biết thêm thông tin về cấu trúc của các đối tượng sự kiện do Google Chat gửi, hãy xem tài liệu tham khảo về Định dạng sự kiện.
6. Phản ứng với các lượt nhấp vào nút trong thẻ
Trong bước trước, ứng dụng trong Chat của bạn đã phản hồi một tin nhắn của người dùng – sự kiện MESSAGE – bằng một thẻ đơn giản chứa tiện ích TextParagragh. Trong bước này, bạn sẽ tạo một phản hồi bao gồm các nút, trong đó mỗi nút có một hành động tuỳ chỉnh được xác định cho nút đó.
Thẻ tương tác
Phản hồi bằng thẻ có thể chứa một trong hai loại nút: tiện ích nút văn bản (hiển thị các nút chỉ có văn bản) và tiện ích ImageButton (hiển thị một nút có biểu tượng hoặc hình ảnh đơn giản mà không có văn bản). Cả tiện ích TextButton và ImageButton đều hỗ trợ một trong hai hành vi onClick (như được xác định trong phản hồi JSON được gửi lại cho Google Chat): openLink hoặc action. Như tên gọi, openLink sẽ mở một đường liên kết được chỉ định trong một thẻ trình duyệt mới.
Đối tượng action chỉ định một hành động tuỳ chỉnh để nút thực hiện. Bạn có thể chỉ định một số giá trị tuỳ ý trong đối tượng hành động, bao gồm actionMethodName duy nhất và một tập hợp các cặp tham số khoá / giá trị.
Việc chỉ định đối tượng action cho nút sẽ tạo ra một thẻ tương tác. Khi người dùng nhấp vào nút trong tin nhắn, Google Chat sẽ tạo ra một sự kiện CARD_CLICKED và gửi yêu cầu trở lại ứng dụng đã gửi tin nhắn gốc. Sau đó, ứng dụng cần xử lý sự kiện được tạo từ Google Chat và trả về phản hồi cho không gian.
Thay thế hàm onMessage() trong Code.gs bằng mã sau. Mã này tạo 2 nút, nút Đặt chế độ đi nghỉ trong Gmail và nút Chặn ngày trong Lịch trong thẻ được gửi đến Google Chat.
Code.gs
const REASON = {
SICK: 'Out sick',
OTHER: 'Out of office'
};
/**
* Responds to a MESSAGE event triggered in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
*/
function onMessage(event) {
console.info(event);
const reason = REASON.OTHER;
const name = event.user.displayName;
const userMessage = event.message.text;
// If the user said that they were 'sick', adjust the image in the
// header sent in response.
if (userMessage.indexOf('sick') > -1) {
// Hospital material icon
HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
reason = REASON.SICK;
} else if (userMessage.indexOf('vacation') > -1) {
// Spa material icon
HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
}
const widgets = [{
textParagraph: {
text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
}
}, {
buttons: [{
textButton: {
text: 'Set vacation in Gmail',
onClick: {
action: {
actionMethodName: 'turnOnAutoResponder',
parameters: [{
key: 'reason',
value: reason
}]
}
}
}
}, {
textButton: {
text: 'Block out day in Calendar',
onClick: {
action: {
actionMethodName: 'blockOutCalendar',
parameters: [{
key: 'reason',
value: reason
}]
}
}
}
}]
}];
return createCardResponse(widgets);
}
Để xử lý sự kiện CARD_CLICKED, bạn phải thêm hàm onCardClick() vào tập lệnh của ứng dụng trong Chat. Thêm mã sau đây xác định hàm onCardClick() Code.gs.
Code.gs
/**
* Responds to a CARD_CLICKED event triggered in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onCardClick(event) {
console.info(event);
let message = '';
const reason = event.action.parameters[0].value;
if (event.action.actionMethodName == 'turnOnAutoResponder') {
turnOnAutoResponder(reason);
message = 'Turned on vacation settings.';
} else if (event.action.actionMethodName == 'blockOutCalendar') {
blockOutCalendar(reason);
message = 'Blocked out your calendar for the day.';
} else {
message = "I'm sorry; I'm not sure which button you clicked.";
}
return { text: message };
}
Khi phản hồi các lượt nhấp của người dùng, ứng dụng trong Chat hiện thực hiện một trong hai việc: đặt chế độ trả lời tự động khi đi nghỉ của người dùng trong Gmail thành tin nhắn "không có mặt tại văn phòng"; hoặc lên lịch một cuộc họp kéo dài cả ngày trên Lịch của người dùng. Để hoàn thành các tác vụ này, ứng dụng sẽ gọi dịch vụ nâng cao của Gmail và dịch vụ Lịch.
Thêm mã sau vào tập lệnh để tích hợp ứng dụng trong Chat với Gmail và Lịch.
Code.gs
const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
* Turns on the user's vacation response for today in Gmail.
* @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
*/
function turnOnAutoResponder(reason) {
let currentTime = (new Date()).getTime();
Gmail.Users.Settings.updateVacation({
enableAutoReply: true,
responseSubject: reason,
responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
restrictToContacts: true,
restrictToDomain: true,
startTime: currentTime,
endTime: currentTime + ONE_DAY_MILLIS
}, 'me');
}
/**
* Places an all-day meeting on the user's Calendar.
* @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
*/
function blockOutCalendar(reason) {
CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}
Cuối cùng, bạn phải bật dịch vụ nâng cao của Gmail trong dự án. Để bật API Gmail, hãy làm như sau:
- Trong trình chỉnh sửa Apps Script, bên cạnh Dịch vụ, hãy nhấp vào biểu tượng Thêm dịch vụ .
- Chọn API Gmail.
- Nhấp vào Trang tổng quan API của Google Cloud Platform bên dưới để mở Google Cloud Console.
- Nhấp vào mục Bật API và dịch vụ.
- Tìm API Gmail rồi nhấp vào API Gmail.
- Trên trang API Gmail, hãy nhấp vào Bật.
Kiểm thử ứng dụng trong Chat
Để kiểm thử phiên bản này của ứng dụng trong Chat, hãy mở DM mà bạn đã bắt đầu trong các bước trước trong Google Chat rồi nhập Tôi sẽ đi nghỉ. Ứng dụng sẽ phản hồi bằng một thẻ tương tự như hình ảnh bên dưới.
Lưu ý: Nếu được yêu cầu cấp quyền truy cập vào ứng dụng, bạn có thể phải nhập tin nhắn lần thứ hai.
7. Xin chúc mừng!
Ứng dụng trong Chat của bạn hiện có thể phản hồi tin nhắn của người dùng, đặt chế độ trả lời tự động khi đi nghỉ trong Gmail và đặt một sự kiện kéo dài cả ngày trên Lịch của họ.
Nội dung đã đề cập
- Tạo và phát hành ứng dụng trong Google Chat bằng Apps Script
- Phản hồi tin nhắn của người dùng bằng một phản hồi đơn giản
- Tương tác với các dịch vụ khác của Google Workspace thay mặt người dùng thông qua ứng dụng trong Chat