صفحات اصلی

صفحه‌های اصلی ویژگی برافزاهای Google Workspace است که امکان تعریف یک یا چند کارت غیرزمینه‌ای را فراهم می‌کند. کارت‌های غیرزمینه‌ای وقتی کاربر خارج از زمینه خاصی باشد، مثلاً وقتی صندوق ورودی Gmail خود را بدون پیام یا پیش‌نویس باز مشاهده می‌کند، رابط کاربری کاربر را نمایش می‌دهند.

صفحه‌های اصلی به شما امکان می‌دهند محتوای غیرزمینه‌ای را، مشابه برنامه‌های Google در پانل کناری دسترسی سریع (Google Keep، «تقویم Google»، و Google Tasks)، نمایش دهید. صفحه‌های اصلی همچنین می‌توانند وقتی کاربر برای اولین‌بار برافزای شما را باز می‌کند، جای شروع اولیه را فراهم کنند و برای آموزش نحوه تعامل کاربران جدید با برافزای شما مفید هستند.

با مشخص کردن صفحه اصلی در مانیفست پروژه و پیاده‌سازی یک یا چند homepageTrigger تابع، صفحه اصلی برافزایتان را تعریف کنید (به پیکربندی صفحه اصلی مراجعه کنید). اگر برافزایتان Google Chat را گسترش می‌دهد، صفحه اصلی آن در برگه صفحه اصلی پیام مستقیم ۱ به ۱ با برنامه Chat نشان داده می‌شود و در کنسول Google Cloud به‌جای مانیفست پیکربندی می‌شود (به پیکربندی صفحه اصلی برای Chat مراجعه کنید).

می‌توانید چندین صفحه اصلی داشته باشید، یکی برای هر برنامه میزبانی که برافزایتان آن را گسترش می‌دهد. همچنین می‌توانید یک صفحه اصلی پیش‌فرض مشترک تعریف کنید که در میزبان‌هایی که صفحه اصلی سفارشی مشخص نکرده‌اید استفاده شود.

صفحه اصلی برافزای شما در این موارد نمایش داده می‌شود:

  • وقتی برافزا برای اولین‌بار در میزبان باز می‌شود (پس‌از صدور مجوز)، یا وقتی کاربر در پیام مستقیم 1:1 با برنامه Chat شما در Chat زبانه صفحه اصلی را باز می‌کند.
  • وقتی کاربر درحالی‌که برافزا باز است از بافتاری به بافت غیربافتاری عوض می‌کند. برای مثال، از ویرایش رویداد «تقویم» به «تقویم» اصلی.
  • وقتی کاربر به تعداد کافی روی دکمه برگشت کلیک می‌کند تا هر کارت دیگری را از پشته‌های داخلی خارج کند.
  • وقتی تعامل با رابط کاربری در کارت غیرزمینه‌ای منجر به Navigation.popToRoot تماس شود.

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

پیکربندی صفحه اصلی

برافزاهای Google Workspace از فیلد addOns.common.homepageTrigger برای پیکربندی صفحه اصلی پیش‌فرض (غیرزمینه‌ای) محتوای برافزا برای برنامه‌های میزبان در مانیفست برافزا استفاده می‌کنند:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

  • ‫runFunction: نام تابع Google Apps Script که چارچوب برافزاهای Google Workspace برای پرداز کردن کارت‌های برافزای صفحه اصلی فرا می‌خواند. این تابع تابع راه‌انداز صفحه اصلی است. این تابع باید آرایه‌ای از اشیاء Card سازنده واسط کاربر صفحه اصلی را بسازد و برگرداند. اگر بیش‌از یک کارت برگردانده شود، کاربرد میزبان سرصفحه‌های کارت را در فهرستی نشان می‌دهد که کاربر می‌تواند از آن انتخاب کند (به برگرداندن چند کارت مراجعه کنید).

  • enabled: آیا کارت‌های صفحه اصلی باید برای این محدوده فعال شوند یا نه. این فیلد اختیاری است و به‌طور پیش‌فرض روی true تنظیم می‌شود. تنظیم این مورد روی false باعث می‌شود کارت‌های صفحه اصلی برای همه میزبان‌ها غیرفعال شود (مگر اینکه برای آن میزبان لغو شده باشد؛ به پیکربندی ویژه میزبان مراجعه کنید).

برای اینکه میزبان از صفحه اصلی مشترک استفاده کند، هم addOns.common.homepageTrigger و هم منبع سطح بالای میزبان باید در مانیفست برافزا وجود داشته باشند. برای مثال، اگر addOns.gmail در مانیفست وجود نداشته باشد، برافزا برای Gmail غیرفعال می‌شود و صفحه اصلی یا عملکرد دیگری در آن میزبان نشان نمی‌دهد.

علاوه‌بر پیکربندی مشترک، جایگزین‌های ساختار یکسان برای هر میزبان در پیکربندی هر برنامه میزبان در addOns.gmail.homepageTrigger، addOns.calendar.homepageTrigger، و دیگر راه‌اندازهای مختص میزبان دردسترس است.

نمونه زیر مانیفستی را نشان می‌دهد که در آن یک راه‌انداز صفحه اصلی مشترک تعریف شده است اما با توابع سفارشی برای «تقویم» و Drive ملغی شده است و برای Gmail غیرفعال شده است. در این پیکربندی، تابع مشترک buildHomePage هرگز اجرا نمی‌شود زیرا یا جایگزین شده است یا میزبان غیرفعال است.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

گزیده مانیفست زیر معادل مثال قبلی است، حتی اگر homepageTrigger پیش‌فرض و پیکربندی Gmail حذف شده باشد:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

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

نموداری که جریان اجرای عملکرد راه‌انداز صفحه اصلی برافزا را نشان می‌دهد

پیکربندی صفحه اصلی برای Chat

برخلاف دیگر برنامه‌های میزبان Google Workspace، افزونه‌هایی که Chat را گسترش می‌دهند صفحه اصلی را در پانل دسترسی سریع سمت چپ نمایش نمی‌دهند و از addOns.common.homepageTrigger در مانیفست استفاده نمی‌کنند. درعوض، Chat صفحه اصلی شما را به‌عنوان کارتی در برگه صفحه اصلی پیام مستقیم ۱ به ۱ با برنامه Chat نمایش می‌دهد.

برای فعال کردن و پیکربندی کردن راه‌انداز «صفحه اصلی برنامه» برای برافزای Chat در «کنسول Google Cloud»:

  1. در کنسول Google Cloud، به منو > میاناهای برنامه‌سازی کاربردی و سرویس‌ها > میاناهای برنامه‌سازی کاربردی و سرویس‌های فعال > میانای برنامه‌سازی کاربردی Google Chat > پیکربندی بروید.

    رفتن به «پیکربندی Google Chat API»

  2. در بخش ویژگی‌های تعاملی، مطمئن شوید که فعال کردن ویژگی‌های تعاملی روشن باشد، و سپس چارگوش پشتیبانی از صفحه اصلی برنامه را انتخاب کنید.

  3. در بخش تنظیمات اتصال > راه‌اندازها، کنترل‌کننده «صفحه اصلی برنامه» را در فیلد صفحه اصلی برنامه براساس معماری برافزایتان مشخص کنید:

    • HTTP: نشانی وب نقطه پایان HTTPS را که درخواست‌های «صفحه اصلی برنامه» را مدیریت می‌کند وارد کنید (یا آن را خالی بگذارید تا نشانی وب نقطه پایان HTTP مشترک شما همه رویدادها را دریافت کند).
    • Google Apps Script: نام تابع تماس برگشتی Google Apps Script را که کارت صفحه اصلی شما را می‌سازد و برمی‌گرداند وارد کنید (به‌طور پیش‌فرض روی onAppHome تنظیم شده است).

  4. روی ذخیره کلیک کنید.

وقتی کاربری برگه صفحه اصلی پیام مستقیمی را با برنامه Chat شما باز می‌کند، Chat رویداد راه‌انداز صفحه اصلی برنامه را به نقطه پایانی یا تابع شما ارسال می‌کند. برای پرداز کردن صفحه اصلی، RenderActions شیئی با کنش پیمایش pushCard برگردانید (یا هنگام به‌روزرسانی صفحه اصلی در پاسخ به کلیک کردن روی دکمه‌ای در کارت صفحه اصلی، از updateCard استفاده کنید):

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

برای جزئیات بیشتر درباره مدیریت کردن راه‌اندازهای Chat، کنش‌های برگشتی، و ساختن کارت «صفحه اصلی برنامه»، به ارسال و به‌روزرسانی کارت «صفحه اصلی برنامه» و دریافت و پاسخ دادن به تعاملات کاربر مراجعه کنید.

اشیای رویداد صفحه اصلی

وقتی تابع راه‌انداز صفحه اصلی (runFunction) یا نقطه پایانی «صفحه اصلی برنامه» که قبلاً توضیح داده شد فراخوانی می‌شود، شیء رویدادی حاوی داده‌های بافت فراخوانی به آن منتقل می‌شود.

اشیاء رویداد صفحه اصلی شامل اطلاعات ابزارک یا زمینه‌ای نمی‌شود. اطلاعاتی که منتقل می‌شود شامل فیلدهای شیء رویداد مشترک زیر است:

در Chat، شیء رویداد «صفحه اصلی برنامه» همچنین شامل فیلد chat با اطلاعاتی درباره کاربر و زمان تعامل است:

  • chat.user: کاربر Chat که زبانه صفحه اصلی را باز کرده است.
  • ‫chat.eventTime: مُهر زمان وقتی کاربر زبانه صفحه اصلی را باز کرد.

برای جزئیات بیشتر، شیء رویداد را ببینید.

کارت‌های غیرزمینه‌ای دیگر

میانای کاربر برافزای شما می‌تواند حاوی کارت‌های غیرزمینه‌ای اضافی باشد که صفحه اصلی نیستند. برای مثال، صفحه اصلی شما ممکن است دکمه‌ای داشته باشد که کارت «تنظیمات» را برای تنظیم تنظیمات برافزا باز می‌کند (چنین تنظیماتی معمولاً مستقل از زمینه هستند).

کارت‌های غیرزمینه‌ای مانند هر کارت دیگری ساخته می‌شوند؛ تنها تفاوت در این است که چه کنش یا رویدادی کارت را تولید و نمایش می‌دهد. برای جزئیات نحوه ایجاد گذار بین کارت‌ها، روش‌های پیمایش را ببینید.