البدء السريع لإضافات Meet

يوضّح هذا الدليل كيفية إعداد وتشغيل نموذج إضافة Google Meet من خلال إنشاء مساحة عرض رئيسية ولوحة جانبية. تتوفّر أيضًا أمثلة "Hello World" الواردة في هذه الصفحة على GitHub كإضافات كاملة في Meet تم إنشاؤها باستخدام JavaScript الأساسية أو Next.js TypeScript.

المرحلة الرئيسية واللوحة الجانبية لحزمة تطوير البرامج (SDK) لإضافات Meet
المرحلة الرئيسية واللوحة الجانبية في إضافة Meet على الويب

تثبيت حزمة تطوير البرامج (SDK) واستيرادها

يمكنك الوصول إلى حزمة تطوير البرامج (SDK) باستخدام npm أو gstatic.

إذا كان مشروعك يستخدم npm، يمكنك اتّباع التعليمات الخاصة بحزمة npm الخاصة بحزمة تطوير برامج إضافات Meet.

أولاً، ثبِّت حزمة npm:

npm install @googleworkspace/meet-addons

بعد ذلك، تصبح حزمة تطوير البرامج (SDK) الخاصة بإضافات Meet متاحة من خلال استيراد واجهة MeetAddonExport:

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

بالنسبة إلى مستخدمي TypeScript، يتم تجميع تعريفات TypeScript مع الوحدة. على مستخدمي TypeScript ضبط moduleResolution على "bundler" ضمن tsconfig.json في المشروع، وذلك لكي يتيح مواصفات "عمليات التصدير" في package.json استيراد عملية تصدير حزمة مشاركة الشاشة.

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.

إنشاء صفحة في اللوحة الجانبية

تعرض اللوحة الجانبية الإضافات المثبَّتة التي يمكنك اختيارها واستخدامها. بعد اختيار الإضافة، سيتم تحميل عنوان URL للوحة الجانبية الذي تحدّده في بيان الإضافة ضمن iframe. يجب أن تكون هذه النقطة هي نقطة الدخول إلى تطبيقك، ويجب أن تنفّذ على الأقل ما يلي:

  1. تشير إلى اكتمال تحميل الإضافة. يعرض Meet شاشة تحميل أثناء تحميل الإضافة. عندما يتم إنشاء جلسة الإضافة من خلال استدعاء الطريقة createAddonSession()، يتعامل Meet مع ذلك كإشارة من الإضافة بأنّ التحميل قد انتهى، وأنّه يمكن للمستخدم التفاعل مع المحتوى التابع لجهة خارجية. يجب ألا يستدعي التطبيق الإضافي الطريقة createAddonSession() إلا بعد انتهاء تحميل المحتوى.

  2. أنشئ عميل اللوحة الجانبية. للوصول إلى حزمة تطوير البرامج (SDK) الخاصة بإضافات Meet في اللوحة الجانبية، يجب إنشاء مثيل لواجهة MeetSidePanelClient. يتيح لك ذلك التحكّم في تجربة حزمة تطوير البرامج (SDK) الرئيسية لإضافات Meet.

  3. ابدأ النشاط. يتيح ذلك للمستخدمين الآخرين الانضمام إلى الإضافة ويفتحها بشكل اختياري في المسرح الرئيسي.

يوضّح نموذج الرمز التالي كيف تنشئ الجلسة عميل لوحة جانبية، وكيف يبدأ عميل اللوحة الجانبية نشاطًا في المرحلة الرئيسية:

Basic 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>

عليك أيضًا تجميع حزمة تطوير البرامج الخاصة بإضافات 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!":

Basic 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.

تشغيل العيّنة

لتشغيلها محليًا، اتّبِع الخطوات التالية:

Basic 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

يتضمّن نشر إضافة خطوتَين:

  1. أولاً، يجب نشر الرمز من هذا الدليل السريع على موقع إلكتروني تملكه، باستخدام أي حلّ نشر تفضّله. يتم نشر الإضافات الرسمية لـ Google Meet على GitHub باستخدام سير عمل GitHub إلى صفحات GitHub، ولكن يمكنك أيضًا استخدام أدوات مثل Firebase Hosting.

  2. بعد نشر تطبيقك، عليك إعداد عملية نشر الإضافة باتّباع التعليمات الواردة في نشر إضافة Meet. يؤدي اتّباع دليل النشر هذا إلى إنشاء إضافة Meet النهائية التي تكون عبارة عن إطار iframe ضمن Meet للتطبيق الذي نشرته في الخطوة الأولى.

تشغيل العيّنة

  1. انتقِل إلى Meet.

  2. انقر على زر أدوات الاجتماع رمز أدوات الاجتماع.

  3. في قسم الإضافات، من المفترض أن تظهر لك الإضافة. انقر على الإضافة لتشغيلها.

إضافة المزيد من الميزات

بعد أن أصبح لديك لوحة جانبية أساسية ومرحلة رئيسية، يمكنك البدء بإضافة ميزات أخرى إلى الإضافة:

ننصحك باستخدام نماذج إضافات Meet على GitHub كمراجع لإنشاء هذه الميزات.