مستندات فروشگاه

پرو مجازی را به سایت خود وصل کنید

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

فروشگاه باید دقیقاً چه کار کند

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

فروشگاه وردپرسی دارید؟ تب . پرستاشاپ: . میکسین: .

  1. ۱
    حساب بسازید با شماره موبایل ایرانی وارد شوید و فروشگاه را ثبت کنید (نام، آدرس سایت، نام مالک).
  2. ۲
    کلید عمومی را بردارید فقط pk_live_... داخل سایت فروشگاه می‌رود. کلید محرمانه (sk_live_...) را هیچ‌وقت در HTML نگذارید.
  3. ۳
    دامنه سایت را مجاز کنید اگر فروشگاه روی shop.ir است، همان دامنه باید در داشبورد باشد. وگرنه مودال باز می‌شود ولی API رد می‌کند.
  4. ۴
    یک‌بار SDK را در سایت لود کنید معمولاً در <head> یا قبل از </body>.
  5. ۵
    روی هر محصول دکمه پرو بگذارید سه چیز لازم است: شناسه محصول، لینک مستقیم عکس لباس، نام محصول.
  6. ۶
    با گوشی واقعی تست کنید از دامنه خودتان دکمه را بزنید، عکس تمام‌قد بدهید، نتیجه باید داخل همان مودال بیاید.

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

۱. ساخت حساب و فروشگاه

  1. به ثبت‌نام بروید.
  2. شماره موبایل را به شکل 0912... وارد کنید و کد را تأیید کنید.
  3. نام فروشگاه، آدرس وب‌سایت (با https://) و نام مالک را بدهید.
  4. کلیدها نمایش داده می‌شوند. کلید محرمانه فقط همین یک‌بار کامل دیده می‌شود.

اگر قبلاً ثبت‌نام کرده‌اید، از ورود با همان شماره وارد داشبورد شوید. حساب باقی می‌ماند.

۲. کلید API

دو کلید ساخته می‌شود:

کلیدشکلکجا استفاده شود
عمومی pk_live_... فقط همین را در فرانت فروشگاه، داخل Pooshino.init بگذارید.
محرمانه sk_live_... سرور شما. در مرورگر، گیت، قالب وردپرس یا فایل عمومی نگذارید.

کلید عمومی فعلی شما در داشبورد، صفحه کلیدهای API است.

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

۳. دامنه مجاز

وقتی فروشگاه را می‌سازید، دامنه وب‌سایت شما (با و بدون www) خودکار ثبت می‌شود. مودال پرو فقط از همان دامنه‌ها به API وصل می‌شود.

  • سایت روی https://myshop.ir است → دامنه myshop.ir باید فعال باشد.
  • اگر فروشگاه را روی زیردامنه مثل shop.myshop.ir باز می‌کنید، همان را هم اضافه کنید.
  • تست روی دامنه پوشینو (pooshinoai.ir) از محدودیت دامنه فروشگاه مستثنی است.

دامنه‌ها را در داشبورد → دامنه‌ها ببینید. اگر خطای «Origin is not allowed» دیدید، دامنه صفحه فروشگاه با لیست مجاز یکی نیست.

۴. نصب SDK

این دو خط را یک‌بار در تمام صفحات محصول بگذارید (ترجیحاً قبل از </body>). apiKey را با کلید عمومی خودتان عوض کنید.


        

baseUrl را وقتی لازم دارید که فایل sdk.js را از سرور خودتان سرو کنید. اگر اسکریپت را مستقیم از پوشینو لود کنید، آدرس سرویس خودکار تشخیص داده می‌شود.

۵. افزودن دکمه پرو روی محصول

روی کارت یا صفحه محصول، یک دکمه با این سه ویژگی بگذارید. SDK بعد از init کلیک را خودش گوش می‌دهد.

ویژگیالزامیمعنی
data-pooshino-tryon بله این دکمه پرو است.
data-product-id بله شناسه محصول شما (SKU یا id در فروشگاه).
data-product-image بله لینک مستقیم و عمومی عکس لباس. باید با http یا https شروع شود. صفحه HTML یا لینک اینستاگرام قبول نیست.
data-product-name خیر نام لباس؛ در مودال نمایش داده می‌شود.
data-size خیر متن آزاد سایز محصول، اگر می‌خواهید در مودال دیده شود.
<button
  type="button"
  data-pooshino-tryon
  data-product-id="tee-white-001"
  data-product-image="https://myshop.ir/images/tee-white.jpg"
  data-product-name="تیشرت سفید">
  پرو کن
</button>

عکس لباس باید از اینترنت قابل دریافت باشد. هوش مصنوعی همان فایل را می‌خواند. اگر عکس پشت لاگین، watermark اسکریپت، یا مسیر نسبی مثل /img/tee.jpg بدون دامنه باشد، ساخت تصویر شکست می‌خورد.

در پرستاشاپ اگر چند تصویر برای محصول دارید، نباید فقط کاور پیش‌فرض را ثابت بگذارید — هنگام کلیک «پرو مجازی» باید همان تصویری که الان در باکس بزرگ گالری دیده می‌شود ارسال شود. جزئیات در تب ، بخش «تصویر انتخاب‌شده گالری».

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

در داشبورد پوشینو یک سوییچ «دکمه پرو در سایت مشتری» دارید. وقتی خاموش باشد، دکمه پرو در فروشگاه شما (چه با SDK و چه با افزونه وردپرس) نمایش داده نمی‌شود.

  • پیش‌فرض: فعال — دکمه برای مشتریان دیده می‌شود.
  • با خاموش کردن سوییچ، SDK بعد از init وضعیت را از GET /api/v1/try-on/widget-config می‌خواند و دکمه‌های data-pooshino-tryon را مخفی می‌کند.
  • اگر کسی مستقیم openTryOn را صدا بزند یا API پرو را فراخوانی کند، پاسخ WIDGET_DISABLED برمی‌گردد.
  • تغییر در داشبورد معمولاً ظرف یک دقیقه در سایت اعمال می‌شود (کش کوتاه SDK و افزونه وردپرس).

اتاق پرو در سایت پوشینو (استودیو) از این سوییچ جدا است و برای آزمایش داخلی شماست.

۶. آزمایش اتصال

  1. سایت فروشگاه را روی دامنه واقعی (یا دمو پوشینو) باز کنید.
  2. روی «پرو کن» بزنید. مودال سفید پوشینو باید باز شود.
  3. عکس تمام‌قد، با نور کافی، بدون برش سر یا پا آپلود کنید — یا از دوربین استفاده کنید.
  4. «پرو کن» داخل مودال را بزنید. مراحل تحلیل عکس / درک لباس / ساخت فیت را می‌بینید.
  5. نتیجه در همان مودال می‌ماند. بستن مودال با «بستن» است، نه با تمام شدن هوش مصنوعی.

برای تست سریع بدون سایت خودتان:

نمونه کامل یک صفحه محصول

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


        

نمونه JavaScript (کنترل دستی)

اگر دکمه را خودتان می‌سازید یا در React / Vue هستید، به‌جای data-attribute مستقیم openTryOn را صدا بزنید.


        

openTryOn یک Promise برمی‌گرداند. وقتی نتیجه آماده شد resolve می‌شود. اگر کاربر مودال را ببندد، reject می‌شود با پیام لغو. مودال بعد از نتیجه خودش بسته نمی‌شود؛ مشتری می‌تواند تصویر را ببیند و دانلود کند.

فروشگاه وردپرسی؟ تب را ببینید.

مشتری در مودال چه می‌بیند

مودال فروشگاه همان مودال سایت پوشینو است. در حالت اتاق پرو جریان این است:

  1. عکس: انتخاب از گالری یا دوربین؛ هنگام جایگزینی عکس، لودینگ روی کادر تصویر می‌آید.
  2. آیتم‌های پرو: تا پنج محصول در «این موارد روی شما پرو می‌شود»؛ در موبایل اسکرول افقی و در دسکتاپ دکمه‌های جابه‌جایی.
  3. موارد اخیر: پیشنهادهای اخیر برای تکمیل استایل.
  4. ساخت تصویر پرو: انیمیشن پرو؛ بعد از آماده‌شدن نتیجه، بزرگنمایی خودکار باز می‌شود.
  5. نتیجه: جابه‌جایی «تصویر قبلی / تصویر الان»، دانلود، و در صورت فعال بودن پل سبد «افزودن به سبد خرید».

دوربین نیاز به اجازه مرورگر دارد. در iframe، سایت شما باید allow="camera" را مسدود نکرده باشد. SDK این مجوز را روی iframe خودش می‌گذارد.

خطاهای رایج

علامتعلتکار فروشگاه
مودال باز نمی‌شود sdk.js لود نشده یا init صدا زده نشده در Network ببینید اسکریپت ۲۰۰ می‌دهد. Pooshino.init باید قبل از کلیک اجرا شده باشد.
Origin is not allowed دامنه صفحه فروشگاه در لیست مجاز نیست hostname دقیق (مثلاً www.shop.ir) را در دامنه‌ها اضافه کنید.
API key is required / invalid کلید خالی، اشتباه، یا باطل همان pk_live_ داشبورد را بدون فاصله بگذارید.
ساخت تصویر ناموفق عکس کاربر نامناسب، یا لینک لباس غیرقابل دریافت عکس تمام‌قد؛ لینک لباس را در تب جدید باز کنید و مطمئن شوید خودِ فایل تصویر است.
دکمه پرو دیده نمی‌شود سوییچ «دکمه پرو در سایت مشتری» در داشبورد خاموش است در داشبورد سوییچ را روشن کنید و یک دقیقه صبر کنید.
WIDGET_DISABLED دکمه پرو از داشبورد غیرفعال شده سوییچ را در داشبورد فعال کنید یا عمداً برای توقف موقت ویجت خاموش نگه دارید.
Try-on timed out بیش از ۳ دقیقه طول کشیده دوباره تلاش کنید. اگر تکرار شد با تیم فنی پوشینو تماس بگیرید:
دوربین باز نمی‌شود HTTPS نیست، یا کاربر اجازه نداده سایت را روی HTTPS سرو کنید. آپلود فایل همیشه جایگزین است.

پشتیبانی فنی در کنار شما

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

با شماره‌های وایت‌لیست پشتیبانی تماس بگیرید. این شماره‌ها برای هماهنگی اجرای پرو مجازی روی وب‌سایت شما در دسترس هستند.

هر بار که گیر کردید — از کلید API تا دکمه محصول — کافی است تماس بگیرید تا مرحله را با هم جلو ببریم.

مرجع کامل SDK

فایل /sdk.js شیء سراسری Pooshino را می‌سازد. اسکریپت را یک‌بار در صفحه بگذارید، init را صدا بزنید، و یا دکمه data-pooshino-tryon بگذارید یا خودتان openTryOn را فراخوانی کنید.

نصب

<script src="https://pooshinoai.ir/sdk.js"></script>
<script>
  Pooshino.init({ apiKey: "pk_live_..." });
</script>

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

Pooshino.init(options)

فیلدنوعتوضیح
apiKeystring، الزامیکلید عمومی pk_live_. کلید محرمانه را اینجا نگذارید.
baseUrlstringریشه API، مثلاً https://pooshinoai.ir.

بعد از init، SDK GET /api/v1/try-on/widget-config را با هدر X-Api-Key و X-Parent-Origin می‌خواند و حالت اتاق پرو، پیشنهاد، ست، استایلیست و سبد را اعمال می‌کند. اگر دکمه در داشبورد خاموش باشد، دکمه‌های data-pooshino-tryon مخفی می‌شوند.

دکمه اعلانی

ویژگیالزاممعنی
data-pooshino-tryonبلهاین عنصر دکمه پرو است.
data-product-idبلهشناسه قابل‌خرید در فروشگاه. در ووکامرس با انتخاب تنوع، شناسه تنوع می‌شود.
data-product-imageبلهURL مطلق و عمومی تصویر محصول.
data-product-nameخیرنام نمایشی.
data-typeخیردسته پرو: tops، bottoms، dress، eyewear و مانند آن.
data-sizeخیرمتن سایز.
data-catalog-external-idخیرشناسه والد در کاتالوگ. اگر خالی باشد از data-product-parent-id یا data-product-id استفاده می‌شود.
data-product-parent-idخیرشناسه محصول والد (ووکامرس).
data-product-variantخیرشناسه تنوع برای سبد خرید.

Pooshino.openTryOn(options) → Promise

فیلدنوعتوضیح
productIdstring، الزامیشناسه محصول فروشگاه.
productImageUrlstring، الزامیURL مطلق تصویر.
productNamestringنام.
typestringدسته محصول.
sizestringسایز.
catalogExternalIdstringشناسه والد کاتالوگ.
variantIdstringشناسه تنوع.

Promise وقتی نتیجه آماده شد با { jobId, resultUrl } حل می‌شود. بستن مودال آن را با خطای لغو رد می‌کند. مودال بعد از نتیجه خودش بسته نمی‌شود.

پنجره پرو

  • دسکتاپ: کشوی حدود ۳۹۰px کنار صفحه؛ سایت پشت آن می‌ماند.
  • موبایل: تمام‌صفحه.
  • اتاق پرو: عکس مشتری، آیتم‌های پرو، موارد اخیر، ساخت تصویر پرو، بزرگنمایی خودکار نتیجه، دانلود، و افزودن به سبد.
  • بعد از نتیجه می‌توان «تصویر قبلی» و «تصویر الان» را عوض کرد.
  • کوچک‌کردن: دکمه داخل هدر مودال، پنجره را به دکمه شناور گوشه صفحه جمع می‌کند. بازگشت با همان دکمه است.
  • بستن: ضربدر هدر یا Pooshino.close().

سبد خرید

اگر پل سبد در داشبورد فعال باشد، بعد از نتیجه دکمه «افزودن به سبد خرید» محصولات پرو‌شده را به سبد می‌فرستد. iframe پیام POOSHINO_CART_ADD_REQUEST می‌فرستد؛ فروشگاه باید window.PooshinoCartAdapter.addItems را داشته باشد (و در صورت نیاز getCart / openCart). افزونه ووکامرس ۱.۴.۴+ این آداپتر و مسیر REST pooshino/v1/cart/add را خودش می‌سازد.

هر قلم باید productId عددی ووکامرس داشته باشد؛ برای متغیرها variantId جدا از شناسه والد ارسال شود.

GET /api/v1/try-on/widget-config

{
  "tryOnButtonEnabled": true,
  "tryOnMode": "dressing_room",
  "modeVersion": 1,
  "effectiveDressingRoomEnabled": true,
  "effectiveRecommendationsEnabled": true,
  "effectiveOutfitTryOnEnabled": true,
  "effectiveCartBridgeEnabled": true,
  "effectiveStylistEnabled": false
}

tryOnMode فقط وقتی dressing_room است که مجوز اتاق پرو برای فروشگاه مؤثر باشد. در غیر این صورت basic می‌ماند.

Pooshino.close()

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

ساخت فروشگاه دموی مشتری