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

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

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

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

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

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

תחילה, מתקינים את חבילת ה-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 Add-ons.

  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.

Next.js

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

next dev

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

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

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

הרצת הדוגמה

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

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

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

הוספת תכונות

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

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