หน้าแรก

หน้าแรกเป็นฟีเจอร์ของส่วนเสริม Google Workspace ที่ช่วยให้คุณกำหนดการ์ดที่ไม่ขึ้นกับบริบทอย่างน้อย 1 รายการได้ การ์ดที่ไม่ใช่บริบทจะแสดงอินเทอร์เฟซผู้ใช้เมื่อผู้ใช้อยู่นอกบริบทที่เฉพาะเจาะจง เช่น เมื่อดู กล่องจดหมาย Gmail โดยไม่มีข้อความหรือฉบับร่างที่เปิดอยู่

หน้าแรกช่วยให้คุณแสดงเนื้อหาที่ไม่ขึ้นกับบริบทได้ ซึ่งคล้ายกับแอป Google ในแผงด้านข้างสำหรับการเข้าถึงด่วน (Google Keep, Google ปฏิทิน และ Google Tasks) หน้าแรกยังเป็นจุดเริ่มต้นเมื่อผู้ใช้เปิดส่วนเสริมเป็นครั้งแรก และมีประโยชน์ในการสอนผู้ใช้ใหม่ๆ เกี่ยวกับวิธีโต้ตอบกับส่วนเสริม

กำหนดหน้าแรกสำหรับส่วนเสริมโดยระบุใน ไฟล์ Manifest ของโปรเจ็กต์และใช้ฟังก์ชันอย่างน้อย 1 รายการhomepageTrigger (ดูการกำหนดค่าหน้าแรก) หากส่วนเสริมขยาย Google Chat หน้าแรกของส่วนเสริมจะปรากฏในแท็บหน้าแรกของข้อความส่วนตัวแบบ 1:1 กับแอป Chat และได้รับการกำหนดค่าในคอนโซล Google Cloud แทนที่จะเป็นไฟล์ Manifest (ดูกำหนดค่าหน้าแรกสำหรับ Chat)

คุณมีหน้าแรกได้หลายหน้า โดยหน้าแรกหนึ่งหน้าสำหรับแต่ละแอปพลิเคชันโฮสต์ที่ส่วนเสริมขยาย นอกจากนี้ คุณยังกำหนดหน้าแรกเริ่มต้นทั่วไปหน้าเดียวที่ใช้ในโฮสต์ซึ่งคุณไม่ได้ระบุหน้าแรกที่กำหนดเองได้ด้วย

หน้าแรกของส่วนเสริมจะแสดงในกรณีต่อไปนี้

• เมื่อเปิดส่วนเสริมในโฮสต์เป็นครั้งแรก (หลังจากให้สิทธิ์) หรือเมื่อผู้ใช้เปิดแท็บหน้าแรกในข้อความโดยตรงแบบ 1:1 กับแอป Chat ของคุณใน Chat
• เมื่อผู้ใช้เปลี่ยนจากบริบทตามบริบทเป็นบริบทที่ไม่ใช่บริบท ขณะที่เปิดส่วนเสริมอยู่ เช่น จากการ แก้ไขกิจกรรมในปฏิทินไปยังปฏิทิน หลัก
• เมื่อผู้ใช้คลิกปุ่มย้อนกลับหลายครั้งจนการ์ดทุกใบสลับกัน หลุดออกจากกองซ้อนภายใน
• เมื่อการโต้ตอบ UI ในการ์ดที่ไม่ใช่บริบทส่งผลให้เกิดการเรียกใช้ Navigation.popToRoot

เราขอแนะนำให้ออกแบบหน้าแรก หากคุณไม่ได้กำหนดการ์ดใดไว้ ระบบจะใช้การ์ดทั่วไป ที่มีชื่อส่วนเสริมของคุณทุกครั้งที่ผู้ใช้ ไปยังหน้าแรก

การกำหนดค่าหน้าแรก

ส่วนเสริมของ Google Workspace ใช้ฟิลด์ addOns.common.homepageTrigger เพื่อ กำหนดค่าเนื้อหาส่วนเสริมของหน้าแรกเริ่มต้น (ไม่ใช่ตามบริบท) สำหรับแอปพลิเคชันโฮสต์ในไฟล์ Manifest ของส่วนเสริม

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

• runFunction: ชื่อฟังก์ชัน Google Apps Script ที่เฟรมเวิร์กส่วนเสริมของ Google Workspace เรียกใช้เพื่อแสดงการ์ดส่วนเสริมของหน้าแรก ฟังก์ชันนี้คือฟังก์ชันทริกเกอร์หน้าแรก ฟังก์ชันนี้ต้องสร้าง และแสดงผลอาร์เรย์ของออบเจ็กต์ Card ที่ประกอบกันเป็น UI ของหน้าแรก หากมีการ์ดมากกว่า 1 ใบ ระบบจะแสดงส่วนหัวของการ์ดในรายการที่ผู้ใช้เลือกได้ (ดูการส่งคืนการ์ดหลายใบ)

• enabled: ควรกำหนดให้การ์ดหน้าแรกเปิดใช้สำหรับขอบเขตนี้หรือไม่ ฟิลด์นี้เป็นฟิลด์ที่ไม่บังคับ และค่าเริ่มต้นคือ true การตั้งค่านี้เป็น false จะทําให้ระบบปิดใช้การ์ดหน้าแรกสําหรับโฮสต์ทั้งหมด (เว้นแต่จะมีการลบล้างสําหรับโฮสต์นั้น ดูการกําหนดค่าเฉพาะโฮสต์)

หากต้องการให้โฮสต์ใช้หน้าแรกทั่วไป ทั้ง addOns.common.homepageTrigger และทรัพยากรระดับบนสุดของโฮสต์ต้องอยู่ในไฟล์ Manifest ของส่วนเสริม ตัวอย่างเช่น หากไม่มี addOns.gmail ในไฟล์ Manifest ระบบจะปิดใช้ส่วนเสริม สำหรับ Gmail และจะไม่แสดงหน้าแรกหรือฟังก์ชันอื่นๆ ในโฮสต์นั้น

นอกจากการกำหนดค่าทั่วไปแล้ว การลบล้างต่อโฮสต์ที่มีโครงสร้างเหมือนกัน จะพร้อมใช้งานในการกำหนดค่าของแอปพลิเคชันโฮสต์แต่ละรายการที่ addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger และทริกเกอร์อื่นๆ ที่เฉพาะเจาะจงโฮสต์

ตัวอย่างต่อไปนี้แสดงไฟล์ Manifest ที่มีการกําหนดทริกเกอร์หน้าแรกทั่วไป แต่มีการลบล้างด้วยฟังก์ชันที่กําหนดเองสําหรับปฏิทินและไดรฟ์ และปิดใช้สําหรับ Gmail ในการกำหนดค่านี้ ฟังก์ชัน buildHomePage ทั่วไปจะไม่ทำงานเนื่องจากมีการลบล้างหรือปิดใช้โฮสต์

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

ข้อมูลต่อไปนี้จากไฟล์ Manifest เทียบเท่ากับตัวอย่างก่อนหน้า แม้ว่าจะไม่มีhomepageTriggerเริ่มต้นและการกำหนดค่า Gmail ก็ตาม

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

คุณไม่จำเป็นต้องกรอกข้อมูลในส่วนhomepageTrigger UI ที่แสดงสำหรับ ส่วนเสริมในผลิตภัณฑ์โฮสต์จะขึ้นอยู่กับฟิลด์ Manifest ที่เกี่ยวข้องและมีhomepageTriggerที่เชื่อมโยงกันหรือไม่ ตัวอย่างต่อไปนี้แสดงฟังก์ชันทริกเกอร์ของส่วนเสริมที่จะเรียกใช้เพื่อสร้าง UI หน้าแรกสำหรับการกำหนดค่าไฟล์ Manifest ที่แตกต่างกัน

กำหนดค่าหน้าแรกสำหรับ Chat

ส่วนเสริมที่ขยาย Chat จะไม่แสดงหน้าแรกในแผงเข้าถึงด่วนทางด้านขวาและจะไม่ใช้ addOns.common.homepageTrigger ในไฟล์ Manifest ซึ่งแตกต่างจากแอปพลิเคชันโฮสต์อื่นๆ ของ Google Workspace แต่ Chat จะแสดงหน้าแรกเป็นการ์ดในแท็บหน้าแรก ของข้อความส่วนตัวแบบ 1:1 กับแอป Chat

วิธีเปิดใช้และกำหนดค่าทริกเกอร์หน้าแรกของแอปสำหรับส่วนเสริม Chat ในคอนโซล Google Cloud

1. ในคอนโซล Google Cloud ให้ไปที่เมนู > API และบริการ > API และบริการที่เปิดใช้ > Google Chat API > การกำหนดค่า

   ไปที่การกำหนดค่า Google Chat API

2. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้ตรวจสอบว่าได้เปิดเปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟแล้ว จากนั้นเลือกช่องทำเครื่องหมายรองรับหน้าแรกของแอป

3. ในส่วนการตั้งค่าการเชื่อมต่อ > ทริกเกอร์ ให้ระบุตัวแฮนเดิลหน้าแรกของแอปในช่องหน้าแรกของแอปตามสถาปัตยกรรมของส่วนเสริม

   • HTTP: ป้อน URL ของปลายทาง HTTPS ที่จัดการคำขอหน้าแรกของแอป (หรือปล่อยว่างเพื่อให้ URL ของปลายทาง HTTP ทั่วไปรับเหตุการณ์ทั้งหมด)
   • Google Apps Script: ป้อนชื่อฟังก์ชัน Callback ของ Google Apps Script ที่สร้างและแสดงการ์ดหน้าแรก (ค่าเริ่มต้นคือ onAppHome)

4. คลิกบันทึก

เมื่อผู้ใช้เปิดแท็บหน้าแรกของข้อความส่วนตัวที่มีแอป Chat ของคุณ Chat จะส่งเหตุการณ์ทริกเกอร์หน้าแรกของแอป ไปยังปลายทางหรือฟังก์ชันของคุณ หากต้องการแสดงหน้าแรก ให้ส่งคืนออบเจ็กต์ RenderActions ที่มีการดำเนินการนำทาง pushCard (หรือใช้ updateCard เมื่ออัปเดต หน้าแรกเพื่อตอบสนองต่อการคลิกปุ่มในการ์ดหน้าแรก)

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการจัดการทริกเกอร์ของ Chat และการดำเนินการที่ส่งกลับ ได้ที่รับและตอบสนองต่อการโต้ตอบของผู้ใช้

ออบเจ็กต์เหตุการณ์ในหน้าแรก

เมื่อมีการเรียกใช้ ฟังก์ชันทริกเกอร์หน้าแรก (runFunction) หรือปลายทางหน้าแรกของแอป ที่อธิบายไว้ก่อนหน้านี้จะได้รับ ออบเจ็กต์เหตุการณ์ที่มีข้อมูลจาก บริบทการเรียกใช้

ออบเจ็กต์เหตุการณ์ในหน้าแรกไม่มีวิดเจ็ตหรือข้อมูลตามบริบท ข้อมูลที่ส่งประกอบด้วยฟิลด์ ออบเจ็กต์เหตุการณ์ทั่วไป ต่อไปนี้

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale และ commonEventObject.userTimezone (ดูข้อมูลข้อจำกัดได้ที่ การเข้าถึงภาษาและเขตเวลาของผู้ใช้ )

ใน Chat ออบเจ็กต์เหตุการณ์หน้าแรกของแอปจะมีฟิลด์ chat พร้อมข้อมูลเกี่ยวกับผู้ใช้และเวลาโต้ตอบด้วย

• chat.user: ผู้ใช้ Chat ที่เปิดแท็บหน้าแรก
• chat.eventTime: การประทับเวลาเมื่อผู้ใช้เปิดแท็บหน้าแรก

ดูรายละเอียดเพิ่มเติมได้ที่ออบเจ็กต์เหตุการณ์

การ์ดอื่นๆ ที่ไม่มีบริบท

UI ของส่วนเสริมอาจมี การ์ดเพิ่มเติมที่ไม่มีบริบทซึ่งไม่ใช่หน้าแรก เช่น หน้าแรกอาจมีปุ่ม ที่เปิดการ์ด "การตั้งค่า" เพื่อปรับการตั้งค่า ส่วนเสริม (โดยปกติแล้วการตั้งค่าดังกล่าวจะไม่ขึ้นอยู่กับบริบท)

การ์ดที่ไม่ใช่บริบทจะสร้างขึ้นเหมือนกับการ์ดอื่นๆ ความแตกต่างเพียงอย่างเดียวคือ การดำเนินการหรือเหตุการณ์ที่สร้างและแสดงการ์ด ดูรายละเอียดเกี่ยวกับวิธีสร้างการเปลี่ยนระหว่างการ์ดได้ที่วิธีการนำทาง