پسوند خود را منتشر کنید

این صفحه توضیح می دهد که چگونه می توانید یک برنامه افزودنی را در Extensions Hub منتشر کنید.

قبل از شروع

برای انتشار یک برنامه افزودنی، ابتدا باید به عنوان ناشر برنامه های افزودنی ثبت نام کنید .

منابع قابل تایید

همه برنامه‌های افزودنی منتشر شده در Extensions Hub باید دارای منبع قابل تأیید عمومی باشند. به جای اینکه کد منبع برنامه افزودنی خود را مستقیماً در Extensions Hub آپلود کنید، در عوض مکان منبع را مشخص می کنید و Extension Hub آن را دانلود کرده و از آنجا می سازد.

در حال حاضر، این به این معنی است که کد منبع برنامه افزودنی خود را در یک مخزن عمومی GitHub در دسترس قرار دهید.

آپلود از یک منبع قابل تایید چندین مزیت دارد:

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

چرخه توسعه توصیه شده

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

این قابلیت یک چرخه توسعه مانند موارد زیر را ممکن می کند:

  1. برنامه افزودنی خود را با استفاده از Firebase Emulator Suite توسعه دهید و به سرعت آن را تکرار کنید.

  2. برنامه افزودنی خود را در یک پروژه واقعی با نصب آن از منبع محلی آزمایش کنید:

    firebase ext:install /path/to/extension
firebase deploy --only extensions

  3. یک نسخه پیش از انتشار را در Extensions Hub آپلود کنید (به زیر مراجعه کنید). پیوند نصب را برای آزمایش گسترده‌تر توزیع کنید و در صورت لزوم با آپلود نسخه‌های قبل از انتشار بیشتر، آن را تکرار کنید.

  4. نسخه نهایی و پایدار را در Extensions Hub آپلود کنید (به زیر مراجعه کنید) و آن را برای بررسی ارسال کنید. اگر برنامه افزودنی مورد بررسی قرار گیرد، در Extension Hub منتشر خواهد شد.

  5. شماره نسخه را در extension.yaml افزایش دهید و این چرخه را برای نسخه بعدی برنامه افزودنی خود تکرار کنید.

یک پسوند جدید آپلود کنید

برای بارگذاری یک برنامه افزودنی برای اولین بار:

  1. اختیاری : کد خود را به یک مخزن عمومی GitHub اختصاص دهید.

  2. دستور ext:dev:upload Firebase CLI را اجرا کنید:

    GitHub 

    firebase ext:dev:upload your_publisher_id/your_extension_id

    منبع محلی

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

    در فراخوانی دستور خود موارد زیر را مشخص می کنید:

    • شناسه ناشر که ثبت کردید .

    • یک رشته ID که پسوند را شناسایی می کند. برنامه های افزودنی خود را با فرمت زیر نام گذاری کنید: firebase-product - description-of-tasks-performed . به عنوان مثال: firestore-bigquery-export

    این دستور از شما اطلاعات اضافی را می خواهد:

    • اگر از GitHub آپلود می کنید:

      • URL به مخزن برنامه افزودنی در GitHub. توجه داشته باشید که یک مخزن می‌تواند دارای چندین پسوند باشد تا زمانی که هر پسوند یک ریشه منحصر به فرد داشته باشد.

        هنگامی که برای اولین بار یک برنامه افزودنی جدید را آپلود می کنید، مخزن به عنوان منبع متعارف افزونه شما ثبت می شود.

      • دایرکتوری موجود در مخزن که حاوی پسوند شما است.

      • مرجع Git commitی که می خواهید منبع نسخه افزونه خود را از آن بسازید. این می تواند یک هش commit، تگ یا نام شاخه باشد.

    • مرحله انتشار نسخه ای که آپلود می کنید.

      مراحل alpha ، beta و rc (نامزد انتشار) برای آپلود نسخه‌های پیش از انتشار برای آزمایش‌کنندگان است تا نصب کنند. از یکی از این مراحل برای آپلود اولیه یک افزونه جدید استفاده کنید.

      مرحله stable برای انتشار عمومی برای انتشار در Extensions Hub استفاده می شود. بارگذاری یک نسخه stable به طور خودکار بازبینی را آغاز می کند و در صورت تصویب، افزونه را منتشر می کند.

    توجه داشته باشید که شماره نسخه ای را مشخص نمی کنید - این مقدار از فایل extension.yaml می آید. هنگامی که یک نسخه پسوند پیش از انتشار را آپلود می کنید، شماره مرحله و آپلود به نسخه اضافه می شود. به عنوان مثال، اگر extension.yaml نسخه 1.0.1 را مشخص کند و شما یک نامزد انتشار را آپلود کنید، منجر به نسخه 1.0.1-rc.0 می شود. آپلود یک نامزد انتشار دیگر از همان نسخه، به طور خودکار تعداد را افزایش می دهد، که منجر به 1.0.1-rc.1 و غیره می شود.

اکنون که نسخه پیش از انتشار برنامه افزودنی را بارگذاری کرده اید، می توانید آن را برای آزمایش با دیگران به اشتراک بگذارید. کاربران می توانند افزونه شما را به یکی از دو روش نصب کنند:

  • با کنسول : کاربران می توانند با کلیک کردن روی پیوندی با فرمت زیر، افزونه را نصب کنند:

    https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

    می توانید پیوند مستقیم را با آزمایش کنندگان خود به اشتراک بگذارید.

  • با CLI : کاربران می‌توانند با ارسال رشته ID افزونه به دستور ext:install ، افزونه را نصب کنند: 

    firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id

یک نسخه به روز شده را آپلود کنید

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

برای آپلود به روز رسانی:

  1. اختیاری : کد خود را به یک مخزن عمومی Git اختصاص دهید.

  2. دستور ext:dev:upload Firebase CLI را اجرا کنید:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    این بار از شما خواسته نمی شود که مخزن GitHub یا دایرکتوری ریشه برنامه افزودنی را مشخص کنید زیرا قبلاً برای برنامه افزودنی شما پیکربندی شده اند. اگر از آن زمان ساختار مخزن خود را بازسازی کرده اید یا به یک مخزن جدید مهاجرت کرده اید، می توانید آنها را با آرگومان های دستوری --root و --repo تغییر دهید.

    منبع محلی 

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

پسوند را برای انتشار ارسال کنید

وقتی آماده انتشار عمومی برنامه افزودنی خود هستید:

  1. کد خود را به یک مخزن عمومی Git اختصاص دهید. (برای انتشار عمومی لازم است.)

  2. دستور ext:dev:upload Firebase CLI را اجرا کنید و stable به عنوان مرحله انتشار مشخص کنید:

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. اگر قبلاً نسخه‌ای از برنامه افزودنی خود را منتشر کرده‌اید، آپلود نسخه پایدار جدید به‌طور خودکار افزونه را برای بررسی ارسال می‌کند.

    اگر اولین نسخه پایدار برنامه افزودنی را آپلود کردید، برنامه افزودنی را در داشبورد ناشر خود پیدا کنید و روی انتشار در مرکز برنامه افزودنی کلیک کنید.

پس از ارسال، بررسی ممکن است چند روز طول بکشد. در صورت پذیرش، برنامه افزودنی در Extensions Hub منتشر خواهد شد. اگر رد شد، پیامی دریافت خواهید کرد که دلیل آن را توضیح می دهد. سپس می توانید به مشکلات گزارش شده رسیدگی کنید و مجددا برای بررسی ارسال کنید.

برای تسریع در بررسی و افزایش شانس قبولی در اولین تلاش، قبل از ارسال، موارد زیر را دوباره بررسی کنید:

  • شما برنامه افزودنی و فرآیند نصب خود را به طور کامل آزمایش کرده اید.
  • مستندات شما کامل و صحیح است و در کنسول Firebase به خوبی ارائه می شود.
  • نام و نام تجاری ناشر شما به طور واضح و دقیق شما را به عنوان ناشر معرفی می کند.
  • نام، توضیحات و نماد برنامه افزودنی شما به طور واضح و دقیق هدف برنامه افزودنی شما را نشان می دهد.
  • شما برچسب های مفید و دقیقی را اعمال کرده اید.
  • شما در extension.yaml همه APIهای Google و غیر Google را که استفاده می کنید و همه انواع رویدادهایی که برنامه افزودنی شما منتشر می کند، اعلام کرده اید.
  • شما فقط به نقش های لازم برای عملکرد برنامه افزودنی درخواست دسترسی دارید و به طور واضح به کاربران توضیح داده اید که چرا به چنین دسترسی نیاز دارید.
  • فایل های منبع شما به وضوح تحت مجوز Apache-2.0 هستند.

پسوندهای آپلود شده و منتشر شده را مدیریت کنید

پسوندهای آپلود شده خود را فهرست کنید

برای فهرست کردن برنامه‌های افزودنی که در شناسه ناشر خود آپلود کرده‌اید، یکی از موارد زیر را انجام دهید:

داشبورد ناشر

آنها را در داشبورد ناشر مشاهده کنید.

Firebase CLI

دستور ext:dev:list را اجرا کنید: 

firebase ext:dev:list your_publisher_id

استفاده از برنامه های افزودنی آپلود شده خود را مشاهده کنید

برای مشاهده میزان استفاده از افزونه هایی که تحت شناسه ناشر خود آپلود کرده اید، یکی از موارد زیر را انجام دهید:

داشبورد ناشر

داشبورد ناشر دارای معیارهای استفاده تجمعی برای همه برنامه‌های افزودنی شما و معیارهای فردی برای هر برنامه افزودنی است.

Firebase CLI

دستور ext:dev:usage را اجرا کنید: 

firebase ext:dev:usage your_publisher_id

نسخه یک برنامه افزودنی را منسوخ کنید

در برخی مواقع، ممکن است بخواهید نسخه قدیمی برنامه افزودنی خود را منسوخ کنید. به عنوان مثال، اگر نسخه جدیدی را منتشر می کنید که یک باگ مهم را برطرف می کند یا یک وابستگی را با یک به روز رسانی امنیتی مهم به روز می کند، مهم است که از نصب نسخه قدیمی توسط کاربران جدید جلوگیری کنید و کاربران فعلی را به ارتقاء تشویق کنید.

برای منسوخ کردن نسخه یک برنامه افزودنی، یکی از موارد زیر را انجام دهید:

داشبورد ناشر

  1. در داشبورد ناشر ، روی افزونه کلیک کنید تا نمای جزئیات آن باز شود.
  2. نسخه ای را که می خواهید منسوخ کنید انتخاب کنید.
  3. روی Deprecate version کلیک کنید.

Firebase CLI

دستور ext:dev:deprecate را اجرا کنید:

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

شما می توانید یک نسخه یا محدوده ای از نسخه ها را مشخص کنید. مثال ها:

  • 1.0.2
  • 1.1.0-1.1.7
  • <1.2.0
  • 1.1.*

نسخه‌های منسوخ شده یک برنامه افزودنی در Extensions Hub فهرست نشده‌اند و نمی‌توان آنها را نصب کرد. کاربرانی که پروژه‌هایشان نسخه قدیمی نصب شده است، پیامی را مشاهده می‌کنند که آنها را تشویق به ارتقاء می‌کند. آنها هنوز هم می توانند از برنامه افزودنی استفاده کرده و مجدداً در این مدت پیکربندی کنند.

اگر هر نسخه از یک برنامه افزودنی منسوخ شود، برنامه افزودنی منسوخ در نظر گرفته می شود و از فهرست Extensions Hub حذف می شود. بارگذاری یک نسخه جدید از یک برنامه افزودنی منسوخ شده به طور خودکار بازبینی را آغاز می کند و پس از پذیرش، آن را یک بار دیگر در Extensions Hub منتشر می کند.

برای معکوس کردن یک منسوخ، از داشبورد ناشر استفاده کنید یا دستور ext:dev:undeprecate Firebase CLI را اجرا کنید: 

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

ضمیمه: عیب یابی خطاهای ساخت

هنگامی که برنامه افزودنی خود را آپلود می کنید، باطن ابتدا کد منبع شما را با استفاده از فرآیند زیر می سازد:

  1. مخزن GitHub شما را کلون می کند و منبع منبع مشخص شده را بررسی می کند.

  2. وابستگی های NPM را با اجرای npm clean-install در هر دایرکتوری منبع تابع مشخص شده در extension.yaml نصب می کند (به sourceDirectory در منابع تابع Cloud مراجعه کنید).

    به موارد زیر توجه کنید:

    • هر فایل package.json باید یک فایل package-lock.json مربوطه داشته باشد. برای اطلاعات بیشتر، npm-ci را ببینید.

    • اسکریپت های پس از نصب در طول نصب وابستگی اجرا نمی شوند. اگر ساخت کد منبع شما به اسکریپت های پس از نصب متکی است، قبل از آپلود آن را اصلاح کنید.

  3. کد شما را با اجرای npm run build در هر دایرکتوری منبع تابع مشخص شده در extension.yaml می سازد.

فقط دایرکتوری ریشه برنامه افزودنی شما در بسته برنامه افزودنی نهایی که به اشتراک گذاشته می شود ذخیره می شود.

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