> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# الاستخدامات الشائعة لواجهة Upcart API

> تعرّف على كيفية تشغيل واجهة Upcart Public API بأمثلة عملية جاهزة للنسخ واللصق.

<div id="how-the-api-pattern-works">
  ## كيف يعمل نمط واجهة API
</div>

تتبع معظم سكربتات Upcart API النمط البسيط نفسه:

الاستماع لحدث سلة ← التحقق من شرط ← تنفيذ إجراء

على سبيل المثال: "عند تحميل السلة ← تحقق مما إذا كانت فارغة ← أخفِ الزر الثابت."

💡 **جديد على واجهات API؟** ابدأ بـ [ما هي واجهة API؟](/ar/upcart/what_is_an_api) قبل الخوض في الأمثلة أدناه.

***

<div id="where-to-add-your-scripts">
  ## أين تضيف سكربتاتك
</div>

توضع جميع السكربتات أدناه في:

**Cart Editor → Settings → Custom HTML → Scripts (before load)**

لفّ كل مقطع بوسوم `<script>...</script>` واحفظ. للاختبار، افتح وحدة تحكم أدوات المطورين في متصفحك (`F12`) وابحث عن أي رسائل `console.log`.

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## ملاحظة حول دوال رد النداء القديمة مقابل الحديثة
</div>

لدى Upcart طريقتان للاستماع إلى أحداث السلة:

| الأسلوب        | مثال                             | الحالة                                     |
| -------------- | -------------------------------- | ------------------------------------------ |
| حديث (موصى به) | `upcartSubscribeAddedToCart(fn)` | حالي                                       |
| قديم (مهمل)    | `upcartOnAddToCart = fn`         | لا يزال يعمل، يسجّل تحذيرًا في وحدة التحكم |

تستخدم جميع الأمثلة أدناه واجهة API الحديثة. ستستمر السكربتات الحالية التي تستخدم الأسلوب القديم في العمل.

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## المثال 1: إخفاء زر السلة الثابت عندما تكون السلة فارغة
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>
```

**كيف يعمل:** يُطلق `upcartSubscribeCartLoaded` في كل مرة يتم فيها تحميل السلة. تتلقى دالة رد النداء `event` يحتوي على كائن `cart` يتضمن مصفوفة `items`. نجمع `quantity` لكل عنصر لتحديد ما إذا كانت السلة فارغة.

⚠️ **هام:** ‏`event.cart` لا يحتوي على خاصية `item_count`. يجب عليك حساب الإجمالي عبر المرور على `event.cart.items`.

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## المثال 2: تسجيل رسالة عند إضافة عنصر إلى السلة
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>
```

**الخصائص المتاحة في `event.item`:**

| الخاصية                    | الوصف                                         |
| -------------------------- | --------------------------------------------- |
| `event.item.title`         | عنوان المنتج                                  |
| `event.item.quantityAdded` | عدد الوحدات المضافة في هذا الإجراء            |
| `event.item.quantity`      | إجمالي كمية هذا العنصر الموجودة الآن في السلة |
| `event.item.variantId`     | معرّف المتغير في Shopify                      |
| `event.item.handle`        | معرّف المنتج النصي (handle)                   |
| `event.item.productId`     | معرّف المنتج في Shopify                       |
| `event.item.finalPrice`    | السعر النهائي بعد الخصومات                    |
| `event.item.image`         | رابط صورة المنتج                              |

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## المثال 3: التكامل مع تطبيق تحليلات من طرف ثالث (مثل TripleWhale)
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>
```

> **ملاحظة:** كل تطبيق طرف ثالث مختلف. راجع فريق دعم تطبيقك لمعرفة تنسيق الحدث الصحيح.

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## المثال 4: فتح السلة تلقائيًا بعد إضافة منتج
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>
```

> **ملاحظة:** إذا كان خيار "Open cart drawer on add to cart" مفعّلًا بالفعل في **Cart Editor → Settings → Cart settings**، فلن تحتاج إلى هذا السكربت.

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## مرجع سريع: دوال الاشتراك (واجهة API الحديثة)
</div>

| الدالة                                                 | متى تُطلق                       | ما تتلقاه دالة رد النداء                                                                                     |
| ------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `upcartSubscribeCartLoaded(fn)`                        | تحميل بيانات السلة              | `{ cart }` - يحتوي cart على `.items[]` و`.total` و`.currency`                                                |
| `upcartSubscribeAddedToCart(fn)`                       | إضافة عنصر إلى السلة            | `{ item }` - يحتوي item على `.title` و`.variantId` و`.quantityAdded` و`.quantity`                            |
| `upcartSubscribeCartOpened(fn)`                        | فتح الدرج الجانبي لسلة التسوق   | `{}` (كائن فارغ)                                                                                             |
| `upcartSubscribeCartClosed(fn)`                        | إغلاق الدرج الجانبي لسلة التسوق | `{}` (كائن فارغ)                                                                                             |
| `upcartSubscribeCartUpdated(fn)`                       | تغيّر محتويات السلة             | `{ cart }`                                                                                                   |
| `upcartSubscribeItemRemoved(fn)`                       | إزالة عنصر                      | `{ item }`                                                                                                   |
| `upcartSubscribeCheckoutClicked(fn)`                   | النقر على زر الدفع              | `{ event }` - حدث MouseEvent من المتصفح                                                                      |
| `upcartSubscribeUpsellsAddedToCart(fn)`                | إضافة عنصر بيع إضافي            | `{ variant }` - يحتوي على `.id` و`.title`                                                                    |
| `upcartSubscribeUpsellsRendered(fn)`                   | عرض عروض البيع الإضافي في السلة | `{ item, element }` - ‏item هو المنتج، وelement هو عقدة DOM                                                  |
| `upcartSubscribeNotesTextChanged(fn)`                  | تحديث ملاحظات السلة             | `{ newNotesText, oldNotesText }` - نص الملاحظات الجديد والنص السابق                                          |
| `upcartSubscribeRewardsMilestonesCompletedChanged(fn)` | تغيّر حالة معلم المكافآت        | `{ numOfMilestonesCompleted, status }` - قيمة `status` هي `"promotion"` أو `"demotion"` أو `"initial-state"` |

***

<div id="direct-action-functions">
  ## دوال الإجراءات المباشرة
</div>

| الدالة                             | ما تفعله                                                        |
| ---------------------------------- | --------------------------------------------------------------- |
| `window.upcartOpenCart()`          | تفتح الدرج الجانبي لسلة التسوق                                  |
| `window.upcartCloseCart()`         | تغلق الدرج الجانبي لسلة التسوق                                  |
| `window.upcartRefreshCart()`       | تحدّث بيانات السلة                                              |
| `window.upcartGetCart()`           | تُعيد كائن السلة الحالي                                         |
| `window.upcartRegisterAddToCart()` | تسجّل الإضافة إلى السلة لمنشئي الصفحات (Replo وPageFly وغيرهما) |
| `window.upcartFormatMoney()`       | تنسّق سعرًا باستخدام تنسيق العملة الخاص بمتجرك                  |

للاطلاع على وثائق API الكاملة، راجع [وثائق Upcart Public API](https://rokt.notion.site/upcart-public-api).

***

<div id="troubleshooting">
  ## استكشاف الأخطاء وإصلاحها
</div>

* **السكربت لا يعمل؟** تحقق مرة أخرى من الموضع: يجب أن يكون في *Scripts (before load)*، وليس بعد التحميل.
* **لم يُعثر على العنصر؟** تأكد من أن المحدد (مثل `#upCartStickyButton`) يطابق معرّف العنصر الفعلي في سلتك.
* **حدث خلل ما؟** علّق سكربتك بإضافة `//` في بداية كل سطر، واحفظ، وحدّث الصفحة.
* **لا تزال عالقًا؟** راجع [الأسئلة الشائعة حول API](/ar/upcart/upcart_api_frequently_asked_questions) لمزيد من خطوات استكشاف الأخطاء.