با شروع سریع افزونه ها آشنا شوید

این راهنما نحوه راه‌اندازی و اجرای یک افزونه نمونه Google Meet را با ایجاد یک صحنه اصلی و یک پنل جانبی شرح می‌دهد. مثال‌های "Hello World" در این صفحه همچنین در GitHub به عنوان افزونه‌های کامل Meet که با جاوا اسکریپت پایه یا Next.js TypeScript ساخته شده‌اند، موجود است.

مرحله اصلی و پنل کناری SDK افزونه‌های Meet.
صحنه اصلی و پنل کناری افزونه Meet Web.

نصب و وارد کردن SDK

شما می‌توانید با استفاده از npm یا gstatic به SDK دسترسی پیدا کنید.

اگر پروژه شما از npm استفاده می‌کند، می‌توانید دستورالعمل‌های مربوط به بسته npm مربوط به SDK افزونه‌های Meet را دنبال کنید.

ابتدا، بسته npm را نصب کنید:

npm install @googleworkspace/meet-addons

سپس، SDK افزونه‌های Meet با وارد کردن رابط MeetAddonExport در دسترس قرار می‌گیرد:

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

برای کاربران TypeScript، تعاریف TypeScript به همراه ماژول بسته‌بندی می‌شوند. کاربران TypeScript باید moduleResolution در tsconfig.json پروژه روی "bundler" تنظیم کنند، به طوری که مشخصات "exports" در package.json امکان وارد کردن بسته اشتراک‌گذاری صفحه export را فراهم کند.

جی‌استاتیک

کیت توسعه نرم‌افزار (SDK) افزونه‌های گوگل میت به صورت یک بسته جاوا اسکریپت از 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، آدرس اینترنتی پنل کناری را که در مانیفست افزونه مشخص کرده‌اید، بارگذاری می‌کند. این باید نقطه ورود برنامه شما باشد و حداقل باید کارهای زیر را انجام دهد:

  1. نشان می‌دهد که بارگذاری افزونه کامل شده است. Meet هنگام بارگذاری افزونه، یک صفحه بارگذاری نشان می‌دهد. هنگامی که جلسه افزونه با فراخوانی متد createAddonSession () برقرار می‌شود، Meet این را به عنوان سیگنالی از افزونه مبنی بر پایان بارگذاری و اینکه کاربر می‌تواند با محتوای شخص ثالث تعامل داشته باشد، در نظر می‌گیرد. افزونه شما نباید تا زمانی که بارگذاری محتوای شما به پایان نرسیده است، متد createAddonSession() را فراخوانی کند.

  2. کلاینت پنل کناری را ایجاد کنید. برای دسترسی به SDK افزونه‌های Meet در پنل کناری، باید یک رابط MeetSidePanelClient نمونه‌سازی کنید. این کار کنترل بر تجربه SDK افزونه‌های Meet اصلی شما را فراهم می‌کند.

  3. فعالیت را شروع کنید. این به دیگران اجازه می‌دهد تا به افزونه شما بپیوندند و به صورت اختیاری افزونه شما را در مرحله اصلی باز می‌کند.

نمونه کد زیر نشان می‌دهد که چگونه جلسه یک کلاینت پنل جانبی ایجاد می‌کند و چگونه کلاینت پنل جانبی یک فعالیت را در مرحله اصلی شروع می‌کند:

جاوا اسکریپت پایه + وب‌پک

در یک فایل جدید به نام 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',
        ...
    },
    ...
};

بعدی.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 : شماره پروژه گوگل کلود شما.

  • MAIN_STAGE_URL : آدرس اینترنتی مرحله اصلی که در مرحله بعدی ایجاد می‌کنید.

ایجاد صفحه اصلی صحنه

مرحله اصلی، ناحیه تمرکز اصلی است که در صورت نیاز به فضای کاری بزرگتر، می‌توانید افزونه را در آنجا نمایش دهید. مرحله اصلی پس از شروع فعالیت باز می‌شود. برای دسترسی به ویژگی‌های SDK افزونه‌های Meet در مرحله اصلی، باید از رابط MeetMainStageClient استفاده کنید.

نمونه کد زیر نمونه‌ای از صفحه اصلی را نشان می‌دهد که یک div سفارشی را برای نمایش "سلام دنیا!" رندر می‌کند:

جاوا اسکریپت پایه + وب‌پک

تابع زیر را به فایل 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>

بعدی.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 خود جایگزین کنید.

نمونه را اجرا کنید

برای اجرای محلی، موارد زیر را انجام دهید:

جاوا اسکریپت پایه + وب‌پک

برای بسته‌بندی فایل main.js به همراه SDK افزونه‌های Meet، webpack را اجرا کنید: 

npx webpack

فایل SidePanel.html و فایل MainStage.html خود را در هر مرورگری باز کنید. این باید مشابه پیاده‌سازی نمونه Basic JS در GitHub به SidePanel.html و MainStage.html در صفحات GitHub باشد.

بعدی.js

اجرای بعدی: 

next dev

به آدرس http://localhost:3000/sidepanel یا http://localhost:3000/mainstage بروید. این آدرس‌ها باید مشابه آدرس‌های پیاده‌سازی نمونه Next.js در GitHub به SidePanel.html و MainStage.html در صفحات GitHub باشند.

افزونه Meet را راه‌اندازی کنید

نصب افزونه شامل دو مرحله است:

  1. ابتدا، باید کد این راهنمای سریع را با استفاده از هر راهکار استقراری که ترجیح می‌دهید، در وب‌سایتی که متعلق به شماست، مستقر کنید. افزونه‌های نمونه رسمی Google Meet در GitHub با استفاده از یک گردش کار GitHub در صفحات GitHub مستقر می‌شوند، اما می‌توانید از ابزارهایی مانند Firebase Hosting نیز استفاده کنید.

  2. پس از استقرار برنامه، باید با دنبال کردن دستورالعمل‌های استقرار افزونه Meet، استقرار افزونه را تنظیم کنید. با دنبال کردن این راهنمای استقرار، افزونه نهایی Meet ایجاد می‌شود که یک iframe درون Meet از برنامه‌ای است که در مرحله اول مستقر کرده‌اید.

نمونه را اجرا کنید

  1. به ملاقات بروید.

  2. روی دکمه ابزارهای جلسه کلیک کنید نماد ابزارهای جلسه. .

  3. در بخش افزونه‌های شما ، باید افزونه‌ی خود را ببینید. آن را برای اجرا انتخاب کنید.

اضافه کردن امکانات بیشتر

حالا که یک پنل کناری ساده و یک صحنه اصلی دارید، می‌توانید ویژگی‌های دیگری را به افزونه خود اضافه کنید:

توصیه می‌شود از افزونه‌های نمونه Meet در GitHub به عنوان مرجع برای ساخت این ویژگی‌ها استفاده کنید.