מדריך למתחילים בנושא תוספים ל-Meet

במדריך הזה נסביר איך מגדירים ומפעילים תוסף לדוגמה ב-Google Meet על ידי יצירת שלב ראשי וחלונית צדדית. הדוגמאות של 'Hello World' שבדף הזה זמינות גם ב-GitHub בתור תוספים מלאים ל-Meet שנוצרו באמצעות JavaScript בסיסי או Next.js TypeScript.

החלונית הצדדית והשלב הראשי של SDK של תוספים ל-Meet.
הבמה הראשית והחלונית הצדדית בתוסף האינטרנט של Meet.

התקנה וייבוא של ה-SDK

אפשר לגשת ל-SDK באמצעות npm או באמצעות gstatic.

אם בפרויקט שלכם נעשה שימוש ב-npm, תוכלו לפעול לפי ההוראות ל חבילת ה-npm של SDK של תוספי Meet.

קודם כול, מתקינים את חבילת ה-npm:

npm install @googleworkspace/meet-addons

לאחר מכן, תוכלו לייבא את הממשק MeetAddonExport כדי להשתמש ב-SDK של התוספים של Meet:

import {meet} from '@googleworkspace/meet-addons/meet.addons';

למשתמשי TypeScript, ההגדרות של TypeScript נארזות עם המודול.

gstatic

ערכת ה-SDK של התוספים ל-Google Meet זמינה כחבילת JavaScript מ-gstatic, דומיין שמציג תוכן סטטי.

כדי להשתמש ב-SDK של התוספים של Meet, מוסיפים לאפליקציה את תג הסקריפט הבא:

<script src="https://www.gstatic.com/meetjs/addons/1.1.0/meet.addons.js"></script>

ערכת ה-SDK של תוספי Meet זמינה דרך הממשק MeetAddon בקטע window.meet.addon.

יצירת דף בלוח הצדדי

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

  1. סימון שהטעינה של התוסף הושלמה. בזמן הטעינה של התוסף יוצג מסך טעינה ב-Meet. כשסשן התוסף נוצר על ידי קריאה ל-method‏ createAddonSession()‎, מערכת Meet מתייחסת לכך כאות מהתוסף שהטעינה הסתיימה והמשתמש יכול לקיים אינטראקציה עם התוכן של הצד השלישי. אסור להפעיל את השיטה createAddonSession() בתוסף עד שהתוכן ייטען.

  2. יוצרים את הלקוח של החלונית הצדדית. כדי לגשת ל-SDK של התוספים של Meet בחלונית הצדדית, צריך ליצור מופע של ממשק MeetSidePanelClient. כך תוכלו לשלוט בחוויית השימוש העיקרית ב-SDK של התוספים ל-Meet.

  3. מתחילים את הפעילות. כך אנשים אחרים יוכלו להצטרף לתוסף, ואם רוצים, התוסף ייפתח בשלב הראשי.

בדוגמת הקוד הבאה אפשר לראות איך הסשן יוצר לקוח של חלונית צדדית, ואיך לקוח החלונית הצדדית מתחיל פעילות בחלונית הראשית:

JS בסיסי + Webpack

בקובץ חדש בשם main.js, מגדירים פונקציה שיוצרת סשן של התוסף, את הלקוח של החלונית הצדדית ומתחילה את הפעילות כשלוחצים על לחצן עם המזהה 'start-activity':

import { meet } from '@googleworkspace/meet-addons/meet.addons';

const CLOUD_PROJECT_NUMBER = 'CLOUD_PROJECT_NUMBER';
const MAIN_STAGE_URL = 'MAIN_STAGE_URL';

/**
 * Prepares the Add-on Side Panel Client, and adds an event to launch the
 * activity in the main stage when the main button is clicked.
 */
export async function setUpAddon() {
    const session = await meet.addon.createAddonSession({
        cloudProjectNumber: CLOUD_PROJECT_NUMBER,
    });
    const sidePanelClient = await session.createSidePanelClient();
    document
        .getElementById('start-activity')
        .addEventListener('click', async () => {
            await sidePanelClient.startActivity({
                mainStageUrl: MAIN_STAGE_URL
            });
        });
}

בקובץ חדש בשם SidePanel.html, מגדירים את הלחצן שמפעיל את הפעילות, ומפעילים את הפונקציה מ-main.js בזמן טעינת המסמך:

<html>
<head>
    <title>Meet Add-on Side Panel</title>
    <script src="./main.js"></script>
</head>

<body style="width: 100%; height: 100%; margin: 0">
    <div>This is the Add-on Side Panel. Only you can see this.</div>
    <button id="start-activity">Launch Activity in Main Stage.</button>

    <script>
        document.body.onload = () => {
            // Library name (`helloWorld`) is defined in the webpack config.
            // The function (`setUpAddon`) is defined in main.js.
            helloWorld.setUpAddon();
        };
    </script>
</body>
</html>

בנוסף, תצטרכו לקבץ את ה-SDK של התוספים ל-Meet עם main.js ולהציג אותם בספרייה. מומלץ לעשות זאת על ידי התקנת webpack ושימוש באפשרות library בקובץ webpack.config.js:

module.exports = {
    entry: './main.js',
    output: {
        library: 'helloWorld',
        ...
    },
    ...
};

Next.js

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

'use client';

import { useEffect, useState } from 'react';
import {
    meet,
    MeetSidePanelClient,
} from '@googleworkspace/meet-addons/meet.addons';

export default function Page() {
    const [sidePanelClient, setSidePanelClient] = useState<MeetSidePanelClient>();

    // Launches the main stage when the main button is clicked.
    async function startActivity(e: unknown) {
        if (!sidePanelClient) {
            throw new Error('Side Panel is not yet initialized!');
        }
        await sidePanelClient.startActivity({
            mainStageUrl: 'MAIN_STAGE_URL'
        });
    }

    /**
     * Prepares the Add-on Side Panel Client.
     */
    useEffect(() => {
        (async () => {
            const session = await meet.addon.createAddonSession({
                cloudProjectNumber: 'CLOUD_PROJECT_NUMBER',
            });
            setSidePanelClient(await session.createSidePanelClient());
        })();
    }, []);

    return (
        <>
            <div>
                This is the Add-on Side Panel. Only you can see this.
            </div>
            <button onClick={startActivity}>
                Launch Activity in Main Stage.
            </button>
        </>
    );
}

מחליפים את מה שכתוב בשדות הבאים:

  • CLOUD_PROJECT_NUMBER: מספר הפרויקט ב-Google Cloud.

  • MAIN_STAGE_URL: כתובת ה-URL של הבמה הראשית שתיצרו בשלב הבא.

יצירת דף של במה ראשית

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

בדוגמת הקוד הבאה מוצגת דוגמה לדף של שלב ראשי שמרינדר את div בהתאמה אישית כדי להציג את ההודעה "Hello, world!":

JS בסיסי + Webpack

מוסיפים את הפונקציה הבאה לקובץ main.js שכבר יצרתם, כדי שהשלב הראשי יוכל לסמן שהטעינה הסתיימה:

/**
 * Prepares the Add-on Main Stage Client, which signals that the add-on has
 * successfully launched in the main stage.
 */
export async function initializeMainStage() {
    const session = await meet.addon.createAddonSession({
        cloudProjectNumber: CLOUD_PROJECT_NUMBER,
    });
    await session.createMainStageClient();
}

לאחר מכן, מוסיפים קובץ MainStage.html חדש שמפעיל את הפונקציה החדשה initializeMainStage ומציג תוכן בהתאמה אישית של 'hello, world':

<html>
<body style="width: 100%; height: 100%; margin: 0">
    <div>
        This is the Add-on Main Stage. Everyone in the call can see this.
    </div>
    <div>Hello, world!</div>

    <script>
        document.body.onload = () => {
            helloWorld.initializeMainStage();
        };
    </script>
</body>
</html>

Next.js

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

'use client';

import { useEffect } from 'react';
import { meet } from '@googleworkspace/meet-addons/meet.addons';

export default function Page() {
    /**
     * Prepares the Add-on Main Stage Client, which signals that the add-on
     * has successfully launched in the main stage.
     */
    useEffect(() => {
        (async () => {
            const session = await meet.addon.createAddonSession({
                cloudProjectNumber: 'CLOUD_PROJECT_NUMBER',
            });
            await session.createMainStageClient();
        })();
    }, []);

    return (
        <>
            <div>
                This is the Add-on Main Stage.
                Everyone in the call can see this.
            </div>
            <div>Hello, world!</div>
        </>
    );
}

מחליפים את CLOUD_PROJECT_NUMBER במספר הפרויקט ב-Google Cloud.

הרצת הדוגמה

כדי להריץ את הקוד באופן מקומי:

JS בסיסי + Webpack

מריצים את webpack כדי לארוז את הקובץ main.js יחד עם ה-SDK של התוספים של Meet:

npx webpack

פותחים את הקובץ SidePanel.html ואת הקובץ MainStage.html בכל דפדפן. זה אמור להיראות כמו הפריסה של הדוגמה הבסיסית ל-JS ב-GitHub לדפים SidePanel.html ו-MainStage.html ב-GitHub Pages.

Next.js

הפעלה של הקוד הבא:

next dev

עוברים אל http://localhost:3000/sidepanel או אל http://localhost:3000/mainstage. הם אמורים להיראות כמו הפריסה של הדוגמה ל-Next.js ב-GitHub לדפים SidePanel.html ו-MainStage.html ב-GitHub Pages.

פריסה של התוסף ל-Meet

מגדירים את הפריסה של התוסף לפי ההוראות לפריסה של תוסף ל-Meet.

הרצת הדוגמה

  1. נכנסים ל-Meet.

  2. לוחצים על פעילויות הסמל של הפעילויות..

  3. התוסף אמור להופיע בקטע Your add-ons. בוחרים בו כדי להפעיל את התוסף.

הוספת תכונות

עכשיו, אחרי שיצרתם חלונית צדדית בסיסית ושלבים ראשיים, תוכלו להתחיל להוסיף תכונות אחרות לתוסף:

מומלץ להשתמש בתוספים לדוגמה ל-Meet ב-GitHub בתור מקור מידע לפיתוח התכונות האלה.