البدء السريع لإضافات 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

بعد ذلك، تتوفّر حزمة تطوير البرامج (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.

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

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

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

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

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

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

JavaScript الأساسي + 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!"‎:

JavaScript الأساسي + 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.

تشغيل النموذج

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

JavaScript الأساسي + Webpack

شغِّل webpack لتجميع ملف main.js مع حزمة تطوير البرامج (SDK) لإضافات Meet:

npx webpack

افتح ملفَي SidePanel.html وMainStage.html في أي متصفّح. MainStage.html

Next.js

شغِّل Next:

next dev

انتقِل إلى http://localhost:3000/sidepanel أو http://localhost:3000/mainstage. يجب أن يبدو ذلك تمامًا مثل عملية نشر نموذج Next.js على GitHub إلى SidePanel.html وMainStage.html على GitHub Pages.

نشر إضافة Meet

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

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

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

تشغيل النموذج

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

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

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

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

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

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