دليل FITLD

هناك طريقتان لإضافة FITLD، وكلتاهما تضع زر اعرف مقاسي نفسه في صفحات منتجاتك.

تستخدم التطبيق؟ انتقل إلى التثبيت بتطبيق Shopify. أما بالسكربت فباختصار:

1. 1أنشئ حساب علامة تجارية على fitld.com/signup
2. 2افتح التثبيت في لوحة التحكم وانسخ الشيفرة (تتضمّن معرّف الأداة)
3. 3Shopify: المتجر الإلكتروني ← السمات ← ⋯ ← تعديل الشيفرة ← افتح layout/theme.liquid والصق قبل </body>. موقع مخصّص: الصق قبل </body> في صفحات المنتجات.
4. 4عُد إلى لوحة التحكم، وفي التثبيت ← تحقّق من أنه يعمل الصق عنوان صفحة منتج للتأكد من أن الأداة ومعرّفها وجدول المقاسات في مكانها.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-mode="product">
</script>

مع data-mode="product" تضع الأداة الزر تحت محدّد المقاس، في صفحات المنتجات فقط، ثم تختار المقاس المؤكَّد في محدّدك. وبدون هذه السمة يُحمَّل السكربت دون أن يعرض شيئاً، فاستخدم أحد الأوضاع أدناه لتضع الزر بنفسك.

نحو 5 دقائق، دون برمجة. يضيف التطبيق زر «اعرف مقاسي» عبر تضمينات التطبيقات في قالبك، ويرسل طلباتك واستردّاداتك إلى FITLD تلقائياً، وتُضاف خطتك إلى فاتورة Shopify.

1. ثبّت التطبيق

1. 1في متجر تطبيقات Shopify افتح FITLD Size Finder واضغط تثبيت. يعرض Shopify ما يمكن لـ FITLD رؤيته: وافق عليه.
2. 2اختر خطة، وستُضاف إلى فاتورة Shopify.
3. 3لديك حساب FITLD؟ إن كان بريد متجرك في Shopify هو نفسه الذي تستخدمه على fitld.com، يطلب منك التطبيق تسجيل الدخول والربط. تبقى جداول المقاسات والنتائج في حساب واحد، وتستمر الخطة التي تدفعها على fitld.com.

2. اتبع الخطوات الثلاث في الصفحة الرئيسية

يُفتح التطبيق على إعداد FITLD. تُبيّن كل خطوة أين تضغط بالترتيب، وتُعلَّم تلقائياً حين تكتمل.

1. 1فعّل زر «اعرف مقاسي». اضغط افتح محرّر القالب: FITLD مفعّل مسبقاً ضمن تضمينات التطبيقات. اضغط حفظ، ثم تم الحفظ في التطبيق.
2. 2أضف جدول مقاسات لمنتجاتك. اضغط أضف جداول المقاسات، وحدّد منتجاتك، ثم اضغط أضف جدول مقاسات. اختر جدولاً قياسياً، أو استخدم استورد جدول مقاسات ليقرأ جدولك الحالي.
3. 3جرّبه في متجرك. افتح منتجاً، واضغط اعرف مقاسي وأدخل بعض القياسات. ثم عُد إلى التطبيق واضغط تحقّق مجدداً.

3. اطّلع على نتائجك

حين يعمل الزر، تعرض الصفحة الرئيسية عدد المتسوّقين الذين حصلوا على مقاس، والطلبات التي أجروها، وكم منها استُرد. ويفتح لوحة التحكم الكاملة موقع fitld.com مع تقارير حسب المنتج والمقاس.

مراجعة خطوة أو إعادتها

اضغط دليل الإعداد في الصفحة الرئيسية لتفتح الخطوات الثلاث من جديد، مثلاً بعد تغيير القالب أو إضافة منتجات. وإن أُوقف الزر في قالبك، أو لم يعد لأي منتج جدول مقاسات، تعود الصفحة الرئيسية إلى خطوات الإعداد تلقائياً.

تفضّل الدفع على fitld.com، أو لا تريد تثبيت تطبيق؟ الصق السكربت بدلاً من ذلك. إن كان متجرك يستخدم تطبيق FITLD فتجاوز هذا الجزء، وإلا ظهر الزر مرتين. نحو 15 دقيقة. تحتاج إلى معرّف أداة FITLD (لوحة التحكم، التثبيت) وصلاحية الوصول إلى إدارة Shopify.

1. أضف الأداة إلى سمتك

1. 1في إدارة Shopify افتح المتجر الإلكتروني ← السمات. وبجانب السمة الحالية اختر ⋯ ← تعديل الشيفرة.
2. 2افتح layout/theme.liquid.
3. 3الصق الشيفرة أدناه قبل وسم </body> مباشرة، واستبدل wgt_YOUR_WIDGET_ID بمعرّفك، ثم اضغط حفظ.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-mode="product"
  async>
</script>

لا تضع في سمتك إلا معرّف الأداة. يبقى مفتاح API السري (fit_sk_…) في لوحة التحكم وعلى خادمك فقط.

2. اربط منتجاتك

يجد FITLD جدول المقاسات الصحيح من صفحة المنتج. إن كانت معرّفات منتجاتك في FITLD هي رموز SKU في Shopify فلا شيء عليك. وإلا فاستخدم المنتجات ← اربط المنتجات في لوحة التحكم لربط كل منتج بصفحته.

3. اربط الطلبات والاستردادات

هذا ما يتيح لـ FITLD أن يُريك هل اشترى المتسوّقون المقاس الموصى به، وكم مرة استُردّت تلك الطلبات.

1. 1في لوحة تحكم FITLD افتح التثبيت ← اربط طلباتك. أدخل عنوان your-store.myshopify.com وانسخ عنوان الـ webhook.
2. 2في إدارة Shopify افتح الإعدادات ← الإشعارات ← Webhooks واضغط إنشاء webhook. الحدث: دفع الطلب. الصيغة: JSON. الرابط: الذي نسخته. ثم احفظ.
3. 3أنشئ webhook ثانياً بالحدث إنشاء استرداد، بصيغة JSON، وبالرابط نفسه.
4. 4يعرض Shopify مفتاح توقيع تحت قائمة الـ webhooks («سيتم توقيع webhooks الخاصة بك بـ…»). انسخه والصقه في لوحة تحكم FITLD.
5. 5اضغط إرسال إشعار تجريبي في Shopify، أو نفّذ طلباً تجريبياً. تُظهر لوحة التحكم وقت وصول آخر طلب.

4. تحقّق من صفحة منتج

افتح أي منتج في متجرك. سيظهر زر اعثر على مقاسي تحت محدّد المقاس. ويمكنك أيضاً استخدام التثبيت ← تحقّق من أنه يعمل لفحص السكربت ومعرّف الأداة وجدول المقاسات دفعة واحدة.

قبل أن تساعد الأداة متسوّقيك، يتحقق FITLD من أن متجرك متاح وأن صفحات منتجاتك مرتبطة بجدول مقاسات. يُجري فحص صفحة التثبيت ذلك مرة واحدة، دون أن تخمّن هل الشيفرة في مكانها.

1. 1افتح التثبيت ← تحقّق من أنه يعمل والصق عنوان صفحة منتج منشورة (مثل https://your-store.com/products/classic-tee).
2. 2يجلب FITLD الصفحة، ويتعرّف على منصتك، ويحاول مطابقتها مع منتج في كتالوجك.
3. 3راجع الفحوصات أدناه، ويتحوّل كل منها إلى الأخضر عند نجاحه.

المتاجر المحمية بكلمة مرور

إن كان متجرك (أو هذه الصفحة فقط) محمياً بكلمة مرور Shopify، اختر متجري يتطلّب كلمة مرور وأدخلها. يستخدمها FITLD لهذا الفحص فقط، ولا تُحفظ أبداً. المتجر الذي ما زال محمياً لا يراه المتسوّقون، لذا لا يمكن للأداة الظهور فيه بعد.

أربع طرق لوضع زر «اعثر على مقاسي». اختر واحدة لكل متجر.

تلقائي في صفحات المنتجات (موصى به)

أضف data-mode="product". يظهر الزر تحت محدّد المقاس، في صفحات المنتجات فقط، ولا يظهر أبداً في الصفحة الرئيسية أو المجموعات.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-mode="product">
</script>

التثبيت عند محدّد

أضف data-attach-to يشير إلى محدّد المقاس. يظهر الزر بعده مباشرة. استخدمه حين لا يتعرّف الاكتشاف التلقائي على شيفرتك.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-attach-to=".product-size-selector">
</script>

عدة منتجات

أضف أزرارك الخاصة بسمات data-pid، وتربطها الأداة تلقائياً.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID">
</script>

<button class="my-size-btn" data-pid="SKU001">Find My Size</button>
<button class="my-size-btn" data-pid="SKU002">Find My Size</button>

<script>
  document.querySelectorAll('.my-size-btn').forEach(function(btn) {
    btn.addEventListener('click', function() {
      FitAPI.setProduct(this.dataset.pid);
      FitAPI.open();
    });
  });
</script>

زر عائم (اختياري)

أضف data-mode="fab" لزر عائم في الزاوية السفلية.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-mode="fab">
</script>

الاختيار التلقائي للمقاس

حين يؤكّد المتسوّق مقاساً، تتحقق الأداة من المخزون وتختاره في محدّدك: سواء كان <select> أو أزرار اختيار أو بطاقات. الاكتشاف تلقائي، وثبّت المحدّد إن كانت شيفرتك غير مألوفة.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-fitld-size-target="#size-picker">
</script>

أضف بضعة منتجات يدوياً، أو استورد كتالوجاً كاملاً دفعة واحدة. يقبل الاستيراد ملف Excel منسّقاً (.xlsx) أو CSV.

نزّل القالب

من المنتجات ← استيراد ملف نزّل قالب FITLD. وهو ملف .xlsx منسّق بخمس أوراق: Products وSize chart (بياناتك)، إضافة إلى Instructions وCategories وFields Guide.

املأه

يفحص الاستيراد أعلى كل ورقة ويجد سطر العناوين تلقائياً، فيمكنك إبقاء العنوان وعبارات REQUIRED والتسميات وأسطر الأمثلة الرمادية أو حذفها. وأسطر الأمثلة مُتحقَّق منها أيضاً، فإن كتبت فوق أحدها تبقى القوائم المنسدلة فعّالة.

Products: سطر لكل منتج، مع unit القياسات (cm أو in). Size chart: سطر لكل مقاس (لكل مقاس قياساته). اختر SKU المنتج من القائمة في أول سطر مقاس، ثم اترك SKU فارغاً في الأسطر التالية: فالـ SKU الفارغ يأخذ قيمة السطر الذي فوقه، فقميص من S إلى XXL لا يتطلّب إدخال SKU إلا مرة واحدة. ويمكن أن يكون اسم المقاس أي شيء (M، 42، 6-12M، 34/36).

لا تريد التعامل مع أسطر المقاسات في Excel؟ بعد الرفع تتيح لك المعاينة تعديل جدول مقاسات كل منتج في المتصفح: انقر عدد المقاسات في أي سطر، واضبط Number of sizes (اكتب 4 فتظهر أربعة أسطر، واكتب 3 فيختفي واحد)، واختر unit، واملأ المقاسات والقياسات مع تحقّق فوري. الـ SKU مُعبّأ مسبقاً لكل سطر، فلا تعيد كتابته أبداً.

الوحدة مرتبطة بالمنتج لا بسطر المقاس، فيمكنك المزج بحرّية. المنتج 1 بـ cm والمنتج 2 بـ in: يُقرأ كل منتج بوحدته ويحوّل FITLD داخلياً، دون أي أثر في الحساب.

يتحقق FITLD من كل سطر أولاً ويشير إلى الأسطر الفاشلة مع السبب، لتصحّحها وتعيد رفع الملف. وتصبح الأسطر الصالحة منتجات في الكتالوج بجداول مقاساتها. احفظ بصيغة .xlsx: فملف CSV لا يحفظ إلا الورقة الأولى، فيعتمد على الصيغة القديمة ذات الورقة الواحدة.

طريقتان لإظهار شعارك واسمك وألوانك داخل الأداة. الخيار 1 هو الأسهل: يكفي إضافة سمات إلى وسم السكربت.

الخيار 1 — وسم السكربت (موصى به)

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-brand-logo="https://your-site.com/logo.svg"
  data-brand-name="Your Brand"
  data-accent-color="#b08a52">
</script>

توصيات الشعار

PNG شفاف أو SVG · شعار أفقي · رابط HTTPS عام · أي أبعاد (يُعرض بارتفاع ثابت وعرض تلقائي) · يجب أن يبقى واضحاً في المظهرين الفاتح والداكن.

الخيار 2 — JavaScript

<script>
  FitAPI.init({
    brandLogo: "https://your-site.com/logo.svg",
    brandAccent: "#b08a52",
    brandName: "Your Brand"
  });
</script>

تظهر التغييرات فور إعادة التحميل، دون أي إعداد في لوحة التحكم.

طرق متقدّمة للتكاملات المخصّصة.

وصول مباشر إلى الواجهة للتكاملات المخصّصة. تُرجع كل النقاط JSON.

Base URL: https://api.fitld.com/v1. Everything under /v1 keeps its request and response shape; a breaking change would come as a new version, and /v1 would keep working. Older integrations that call /api/… keep working too. Every field, error code and webhook payload is in the API reference.

Test mode

Every account also has a test widget ID (wgt_test_…) and a test secret key (fit_sk_test_…), under Settings → Test mode. Use them on a staging store or during development: sizes come from your real charts, but nothing counts toward your plan or appears in Results. Test responses include "livemode": false and the header FITLD-Mode: test.

Test credentials work only with the endpoints on this page, never with account data, and allow 1,000 requests a day. Switch to your live widget ID and API key before your store goes live.

POST /v1/widget/recommend

نقطة عامة تستخدمها الأداة. تقبل قياسات الزائر أو رموز المتسوّق المسجّل.

{
  "widgetId": "wgt_YOUR_WIDGET_ID",
  "productId": "SKU001",
  "measurements": {
    "unit": "cm",
    "chest": 96,
    "waist": 80,
    "hips": 98
  }
}

{
  "recommended_size": "M",
  "confidence": 0.87,
  "fit_quality": "great",
  "measurement_gap_cm": 1.2,
  "category": "Tops",
  "guest": true
}

POST /v1/recommend-size/guest

حساب المقاس من خادم إلى خادم بمفتاح API السري. تُرفض الطلبات المرسلة من متصفح على موقع آخر، فاستخدم معرّف الأداة في شيفرة المتجر.

POST https://api.fitld.com/v1/recommend-size/guest
Headers: x-api-key: fit_sk_YOUR_API_KEY

{
  "productId": "SKU001",
  "measurements": { "chest": 96, "waist": 80 }
}

POST /v1/products/resolve

يجد منتجاً عبر SKU أو الرابط أو المعرّف الخارجي.

{
  "widgetId": "wgt_YOUR_WIDGET_ID",
  "productId": "SKU001"
}

{
  "productId": "SKU001",
  "productName": "Classic Oxford",
  "category": "Tops"
}

Errors and request IDs

Every response has an X-Request-Id header. Errors also return it in the body, with a message you can show and a code your code can check. Messages may be reworded; codes don’t change. Quote the request ID when you email contact@fitld.com and we can find that exact request. Every code is listed under Error codes.

{
  "error": "Authentication required. Provide x-api-key or widgetId.",
  "code": "authentication_required",
  "requestId": "req_8fK2xQm1Lw0aZt7c"
}

يربط FITLD المقاس الذي أكّده المتسوّق بالطلب الذي ينفّذه، لترى أي الطلبات تأثّرت بتوصياتك.

حين يؤكّد المتسوّق مقاساً، تَسِم الأداة سلّته بالجلسة. وتكتب القيم معاً بوصفها note_attributes لسلة Shopify وخصائص مخفية للسطر:

خصائص السطر مهمّة لأن «اشترِ الآن» والدفع السريع يتجاهلان سمات السلة؛ أما الخصائص فتبقى مع السطر وتصمد.

كيف تُطابَق الطلبات

في Shopify يرسل webhook orders/paid كل طلب مدفوع إلى FITLD. يسجّل FITLD كل سطر، ويربطه بجلسة FITLD للمتسوّق إن وُجدت، ويسجّل هل طابق المقاس المشترى التوصية. تظهر المجاميع في صفحة النتائج بلوحة التحكم. الإعداد: التثبيت على Shopify.

لا تُحتسب طلبات بعد FITLD إلا الأسطر المشتراة في جلسة استخدم فيها المتسوّق FITLD. وتُعرض مبيعات المنتجات التي لها جدول مقاسات في FITLD فحسب بشكل منفصل، للسياق.

الاستردادات

بعد ربط webhook refunds/create (بالرابط نفسه) يسجّل FITLD الوحدات المستردّة لكل سطر ويقارن معدّلات الاسترداد: متسوّقون استخدموا FITLD أو لم يستخدموه، ومتسوّقون اشتروا المقاس الموصى به أو غيره. تظهر المعدّلات حين تبلغ المجموعة 30 وحدة على الأقل.

أوقف وسم السلة لمتجر ما بـ data-fitld-cart-attrs="false".

FITLD can call your server when something happens. Add an endpoint under Settings → Webhooks, choose the events, and FITLD sends each one as a signed POST with a JSON body. Answer with any 2xx status within 10 seconds.

Events never contain shopper measurements or who the shopper is. Order, refund and return events need the Shopify connection; the others work on any store.

{
  "id": "evt_Q2xmN0VtZ3pDbFh0",
  "type": "order.attributed",
  "created": "2026-11-10T14:02:11.402Z",
  "livemode": true,
  "api_version": "v1",
  "data": {
    "order_id": "5890112340",
    "order_name": "#1042",
    "currency": "EUR",
    "paid_at": "2026-11-10T14:01:58.000Z",
    "lines": [{
      "product_id": "OXFORD-SHIRT",
      "sku": "OXF-BLU-M",
      "product_name": "Classic Oxford",
      "size": "M",
      "recommended_size": "M",
      "size_matched": true,
      "quantity": 1
    }]
  }
}

Check the signature

Every call has a FITLD-Signature header: t=<unix seconds>,v1=<signature>. The signature is the hex HMAC-SHA256 of t, a dot, and the raw body, made with your endpoint’s signing secret (whsec_…, shown once when you add the endpoint). Refuse calls that don’t match or are older than 5 minutes.

const crypto = require("crypto");

// Use the raw request body, exactly as received (before JSON parsing).
function verifyFitld(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false; // older than 5 minutes
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

app.post("/fitld/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyFitld(req.body.toString("utf8"), req.get("FITLD-Signature") || "", process.env.FITLD_WEBHOOK_SECRET)) {
    return res.status(400).end();
  }
  const event = JSON.parse(req.body);
  // Answer quickly, then do the work: FITLD waits 10 seconds at most.
  res.status(200).end();
  handle(event); // e.g. event.type === "order.attributed"
});

Retries

If your server doesn’t answer with a 2xx, FITLD tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours. Every attempt carries the same event id (also in the FITLD-Event-Id header), so you can ignore one you’ve already handled. An endpoint failing for 3 days is turned off; turn it back on in Settings. Recent calls, their answers and a Resend button are on the endpoint’s page.

تتضمّن كل خطة عدداً شهرياً من توصيات المقاس. تُحتسب توصية في كل مرة يحصل فيها متسوّق على مقاس من الأداة أو يستدعي خادمك الواجهة.

التجاوز لا يعطّل متجرك. تستمر الأداة في خدمة المتسوّقين حتى ضعف حجمك الشهري، ونراسلك عند 80٪ و100٪. ولا تُرجع الواجهة خطأ HTTP 429 مع "code": "quota_exceeded" إلا بعد تجاوز الضعف.

لحماية الخدمة، يمكن لكل جلسة متسوّق طلب حتى 120 توصية في الساعة، مع حدّ أعلى لكل شبكة كي لا يُحظر المتسوّقون الذين يتشاركون اتصال جوّال. وتُحدّ استدعاءات الواجهة بالمفتاح السري بـ 100 في الدقيقة.

Each error has an HTTP status and a code. Check the code in your integration: it stays the same even when the message is reworded.

مشكلات شائعة وحلولها.

1. 1الأداة لا تظهر: استخدم التثبيت ← تحقّق من أنه يعمل؛ فهو يفحص السكربت ومعرّف الأداة وجدول المقاسات في صفحتك المنشورة. ويمكنك أيضاً فتح وحدة تحكم المتصفح (F12) والتأكد من أن رابط السكربت يُحمَّل دون أخطاء.
2. 2«هذا المنتج غير مرتبط بجدول مقاسات FITLD بعد»: لم يتمكّن FITLD من ربط الصفحة بمنتج. مع تطبيق Shopify، افتح Size charts وتأكّد أن للمنتج جدولاً. لا يُربط المنتج إلا إذا كانت مقاساته موجودة في الجدول، فإن ظهر كمتجاوَز، اختر جدولاً يضمّ مقاساته. ومع السطر البرمجي، يجب أن يكون معرّف المنتج في FITLD هو handle صفحته (آخر عنوانها) أو رمز SKU أو عنوان الصفحة.
3. 3«لا يناسب أيّ مقاس في هذا المنتج»: مقاسات المتسوّق خارج كل مقاسات الجدول. يقول FITLD ذلك بدل التوصية بأقرب مقاس. وإن تكرّر الأمر، أضف المقاسات الناقصة إلى الجدول.
4. 4مقاس خاطئ موصى به: تأكد من اكتمال جداول المقاسات في المنتجات. القياسات الناقصة تقلّل الدقة.
5. 5Your site sets a Content-Security-Policy: allow FITLD's two addresses: script-src https://fitld.com, connect-src https://api.fitld.com https://fitld.com and font-src https://fitld.com. The widget loads its size window from fitld.com and asks api.fitld.com for sizes; it calls nothing else.
6. 6متجر محمي بكلمة مرور: يصل المتسوّقون إلى صفحة كلمة المرور بدل منتجك، فلا يمكن للأداة التحميل لهم. أزل كلمة المرور لنشر المتجر؛ ويظل التحقق قادراً على قراءة الصفحة إن أعطيته كلمة المرور.
7. 7صفحة مكافحة الروبوتات: إن أبلغ التحقق عن فحص للروبوتات، فالمتجر متاح للزوّار الحقيقيين لكنه يمنع الفحوص الآلية. تحقّق من الأداة بصرياً في المتصفح.
8. 8«Secret API keys can't be used from a website»: استخدمت data-api-key أو أرسلت x-api-key من متجر. استخدم data-widget-id بدلاً منه، وأعد إنشاء المفتاح من الإعدادات إن كان قد نُشر.
9. 9تواصل مع الدعم: ما زلت عالقاً؟ راسل contact@fitld.com.