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

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

قبل از اینکه شروع کنی

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

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

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

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

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

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

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

ابزارهای توسعه 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 را اجرا کنید:

    گیت‌هاب 

    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

    در فراخوانی فرمان خود، موارد زیر را مشخص می‌کنید:

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

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

    این دستور از شما اطلاعات بیشتری را درخواست می‌کند:

    • اگر از گیت‌هاب آپلود می‌کنید:

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

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

      • دایرکتوری موجود در مخزن که افزونه شما در آن قرار دارد.

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

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

      مراحل 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) : کاربران می‌توانند با ارسال رشته شناسه افزونه به دستور ext:install افزونه را نصب کنند:

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

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

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

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

  1. اختیاری : کد خود را در یک مخزن عمومی گیت قرار دهید.

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

    گیت‌هاب 

    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. کد خود را در یک مخزن عمومی گیت قرار دهید. (برای انتشار عمومی لازم است.)

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

    firebase ext:dev:upload your_publisher_id/your_extension_id

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

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

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

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

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

مدیریت افزونه‌های آپلود شده و منتشر شده

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

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

داشبورد ناشر

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

رابط خط فرمان فایربیس

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

firebase ext:dev:list your_publisher_id

مشاهده میزان استفاده از افزونه‌های آپلود شده

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

داشبورد ناشر

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

رابط خط فرمان فایربیس

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

firebase ext:dev:usage your_publisher_id

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

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

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

داشبورد ناشر

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

رابط خط فرمان فایربیس

دستور 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. مخزن گیت‌هاب شما را کلون می‌کند و مرجع منبع مشخص‌شده را بررسی می‌کند.

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

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

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

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

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

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

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