> ## 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.

# نظرة عامة

> كيف تعمل حزمة Aftersell Cart SDK: نقطة الدخول العامة، والأجزاء الأربعة لواجهة البرمجة، ومتى يتم تحميلها، وكيفية تشغيل التعليمات البرمجية عليها بأمان.

**Cart SDK** هي واجهة برمجة تطبيقات JavaScript لسلة Aftersell على واجهة متجرك. تتيح لك تغيير سلوك السلة، والتفاعل مع ما يقوم به المتسوقون، وقراءة محتويات السلة أو تغييرها من خلال التعليمات البرمجية.

يمكنك تشغيل تعليمات SDK البرمجية عبر [النصوص البرمجية المخصصة](/ar/aftersell/cart/custom-scripts)، أو عبر وضع React في [كتلة التعليمات البرمجية المخصصة](/ar/aftersell/cart/custom-code-blocks) لكتلة تعرض واجهتها الخاصة.

<Note>
  كثير مما يطلبه التجار من SDK متوفر بالفعل كإعداد. قبل كتابة نص برمجي، تحقق مما إذا كانت [كتلة سلة](/ar/aftersell/cart/blocks-overview)، أو [الشروط حسب السوق/الدولة/العملة](/ar/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency)، أو [أحد إعدادات السلة](/ar/aftersell/cart/cart-settings) يقوم بذلك بالفعل. فهذه تستمر في العمل عبر عمليات إعادة تصميم السلة، بينما قد لا يستمر نصك البرمجي.
</Note>

<div id="the-global-entry-point">
  ## نقطة الدخول العامة
</div>

كل شيء يتفرع من متغير عام واحد:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart
```

<Note>
  **كل مقتطف في هذه الوثائق يكتب `window.aftersell.cart` بالكامل**، بحيث يعمل أي منها بمفرده عند لصقه. كما أن إنشاء اسم مختصر له مرة واحدة (`const cart = window.aftersell.cart;`) واستخدام `cart` من ذلك الحين فصاعدًا صالح تمامًا أيضًا، وآمن حتى قبل تحميل السلة. فقط تذكّر تضمين ذلك السطر إذا اختصرت مقتطفًا، لأن `cart` بمفردها تُلقي الخطأ `cart is not defined`.
</Note>

أربعة أجزاء تقوم بالعمل:

<Columns cols={2}>
  <Card title="التهيئة" icon="sliders" href="/ar/aftersell/cart/sdk-configure">
    حدّد سلوك السلة: متى يُفتح الدُرج، وكيف يتم تنسيق العملة، وما إذا كانت Aftersell تعترض الإضافة إلى السلة.
  </Card>

  <Card title="الأحداث" icon="tower-broadcast" href="/ar/aftersell/cart/sdk-events">
    تفاعل مع ما يحدث: تم تحميل السلة، تمت إضافة عنصر، فُتح الدُرج، تم النقر على الدفع.
  </Card>

  <Card title="الإجراءات" icon="wand-magic-sparkles" href="/ar/aftersell/cart/sdk-actions">
    اقرأ السلة وغيّرها: افتحها، أضف عنصرًا، حدّث كمية، اقرأ الحالة الحالية.
  </Card>

  <Card title="الخُطافات" icon="plug" href="/ar/aftersell/cart/sdk-hooks">
    غيّر طريقة عمل السلة نفسها: أخفِ الأسطر أو أعد تسميتها، أعد ترتيبها، أرفق بيانات إضافية، تحكّم في الإضافة إلى السلة.
  </Card>
</Columns>

<Note>
  إذا توقف أحد سكربتاتك عن العمل عند الإضافة إلى السلة، فابدأ من [اعتراض الإضافة إلى السلة](/ar/aftersell/cart/add-to-cart-interception). فهو يشرح لماذا يتولى Aftersell عملية الإضافة، وكل طريقة لاستثناء نموذج.
</Note>

بالإضافة إلى ثلاثة أعضاء أصغر:

| العضو        | ما هو الغرض منه                                                    |
| ------------ | ------------------------------------------------------------------ |
| `ready()`    | وعد (Promise) يتحقق بمجرد تحميل السلة لأول مرة.                    |
| `context`    | سياق المشتري المعروض من الخادم، قابل للقراءة بشكل متزامن.          |
| `shadowRoot` | الجذر الظلي (shadow root) للسلة، للاستعلام عن العناصر داخل الدُرج. |

<div id="events-actions-or-hooks">
  ## أحداث أم إجراءات أم خُطافات؟
</div>

من السهل الخلط بين الثلاثة، واختيار الخيار الخاطئ هو السبب الأكثر شيوعًا لعدم قيام النص البرمجي بما توقعه كاتبه:

| تريد أن…                               | استخدم    | مثال                                         |
| -------------------------------------- | --------- | -------------------------------------------- |
| تشغّل تعليمات برمجية *عند حدوث شيء ما* | **حدث**   | إرسال حدث تحليلات عند إضافة عنصر.            |
| *تغيّر ما بداخل* السلة                 | **إجراء** | إضافة هدية مجانية بمجرد تجاوز الإجمالي 50\$. |
| تغيّر *طريقة عمل السلة أو عرضها*       | **خُطاف** | إخفاء أسطر الهدايا المجانية من الدُرج.       |

الفرق الأهم: **الإجراء يغيّر سلة المتسوق الفعلية** (وإجماليه)، بينما **الخُطاف يغيّر ما يُعرض فقط**. إخفاء سطر بخُطاف يُبقيه في السلة وفي الإجمالي؛ أما إزالته بإجراء فتخرجه فعليًا.

<div id="how-and-when-it-loads">
  ## كيف ومتى يتم التحميل
</div>

تُحمَّل السلة على مرحلتين، وقد بُنيت SDK بحيث لا تضطر إلى التفكير في الترتيب:

1. **بذرة (stub)** صغيرة تنشئ `window.aftersell.cart` فورًا، لذا فهي موجودة دائمًا.
2. تُحمَّل SDK الكاملة بعد ذلك بوقت قصير وتتولى الأمر، مطوّرةً البذرة في مكانها، لذا يستمر المرجع الذي التقطته سابقًا في العمل.

هذا يمنحك فئتين من الاستدعاءات:

<Columns cols={2}>
  <Card title="استدعاءات الإعداد: آمنة فورًا" icon="circle-check">
    `configure(...)` و `events.on(...)` وكل استدعاء `hooks.register*`. تُخزَّن مؤقتًا قبل الإقلاع وتُعاد بالترتيب بمجرد تحميل SDK. ضعها في أعلى نصك البرمجي.
  </Card>

  <Card title="الإجراءات: انتظر ready()" icon="clock">
    كل شيء ضمن `actions.*`. شغّلها داخل `ready()` أو داخل معالج حدث. إذا استُدعيت مبكرًا جدًا فإنها تحذّر في وحدة التحكم ولا تفعل شيئًا، بأمان: فالإجراءات غير المتزامنة لا تزال تتحقق، لذا لن تنكسر سلسلة `.then()`.
  </Card>
</Columns>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Set-up: fine at the top level, before the cart has loaded.
window.aftersell.cart.configure({ open_on_add_to_cart: 'always' });

window.aftersell.cart.events.on('item_added', (payload) => {
  console.log('Added', payload.item.title);
});

// Actions: wait until the cart is ready.
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});
```

<div id="ready">
  ### ready()
</div>

تُعيد `ready()` وعدًا يتحقق بمجرد **استقرار** أول تحميل للسلة. وهي تتحقق عند الفشل كما عند النجاح، لذا لن يترك متسوق على اتصال متقطع نصك البرمجي معلقًا أبدًا. تحقق من `getCart()` بحثًا عن `null` بدلًا من افتراض وصول سلة.

استدعاء `ready()` بعد أن تكون السلة قد حُمّلت بالفعل يتحقق فورًا، لذا فهي آمنة للاستخدام كبوابة عامة تعني "السلة موجودة الآن" في أي مكان في تعليماتك البرمجية.

<Tip>
  لا تحتاج إلى `ready()` داخل معالج حدث. فبحلول وقت انطلاق `cart_loaded` أو `cart_updated` أو `item_added`، تكون السلة محمّلة والإجراءات آمنة للاستدعاء.
</Tip>

<div id="context">
  ## context
</div>

يحمل `window.aftersell.cart.context` بيانات المشتري المعروضة من الخادم، وهي قابلة للقراءة بشكل متزامن، دون الحاجة إلى `ready()`. استخدمه للتفريع حسب السوق أو الدولة الذي يجب أن يحدث قبل تحميل السلة.

| الحقل                     | الوصف                                                                       | متاح قبل الإقلاع               |
| ------------------------- | --------------------------------------------------------------------------- | ------------------------------ |
| `shopify_market`          | سوق Shopify الخاص بالمشتري.                                                 | نعم                            |
| `customer_country`        | رمز الدولة المكوّن من حرفين.                                                | نعم                            |
| `customer_currency`       | رمز العملة النشطة.                                                          | نعم                            |
| `money_format`            | تنسيق العملة في Shopify الخاص بالمتجر.                                      | نعم                            |
| `backend_url`             | مضيف الخادم الخلفي المباشر، يُستخدم كبديل عندما لا يكون وكيل التطبيق مهيأً. | نعم                            |
| `storefront_access_token` | رمز مميز لاستدعاءات Storefront API.                                         | **لا** — يُضاف عند إقلاع السلة |

<Warning>
  `storefront_access_token` هو حقل `context` الوحيد الذي لا يعرضه الخادم داخل `cart.context`. يُضاف إلى `context` عند إقلاع السلة، لذا فإن قراءته في أعلى نصك البرمجي تعطي `undefined`. انتظر `window.aftersell.cart.ready()` أولًا.
</Warning>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}
```

<Note>
  لعرض إعدادات كتلة مختلفة حسب السوق أو الدولة أو العملة، استخدم [الشروط في محرر السلة](/ar/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency) بدلًا من ذلك. لا حاجة إلى نص برمجي. واجهة الشروط الكاملة متوفرة حاليًا في [Rewards](/ar/aftersell/cart/rewards-block#per-market-rewards).
</Note>

<div id="shadowroot">
  ## shadowRoot
</div>

تُعرض السلة داخل جذر ظلي (shadow root)، لذا فإن `document.querySelector` **لا يستطيع رؤية أي شيء داخل الدُرج**. للوصول إلى عنصر في السلة، استعلم عن الجذر الظلي:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
const root = window.aftersell.cart.shadowRoot;
const button = root?.querySelector('.cart-external-checkout-button');
```

استهدف نفس **فئات `cart-external-*` العامة** التي تستخدمها [CSS المخصصة](/ar/aftersell/cart/custom-css). فهذه هي المقابض المدعومة. أما نظائرها `cart-internal-*` فهي أعمال السلة الداخلية، لذا استعلم عن الخارجية بدلًا منها.

<Warning>
  لا تلجأ إلى الجذر الظلي إلا عندما لا تقوم أي كتلة أو إعداد أو خُطاف بالمهمة. فالخُطاف يصمد أمام إعادة تصميم السلة؛ أما استعلام DOM فصيانته مشكلة تقع على عاتق تعليماتك البرمجية.
</Warning>

الجذر الظلي لا يكون موجودًا إلا بعد إقلاع السلة، لذا اقرأه داخل `ready()` أو داخل معالج حدث بدلًا من أعلى نصك البرمجي.

<div id="debugging">
  ## تصحيح الأخطاء
</div>

يجب ألا يُعطّل نص برمجي معطوب أبدًا الإضافة إلى السلة أو الدُرج، لذا تحتوي SDK الأعطال بدلًا من تركها تنتشر. أما مكان ظهور العطل فيعتمد على ما تعطّل:

| ما الذي فشل                                                   | أين يظهر                                             |
| ------------------------------------------------------------- | ---------------------------------------------------- |
| نصك البرمجي ألقى خطأ في المستوى الأعلى                        | `console.error`، مع ذكر السطر وما الذي لم يعمل أبدًا |
| معالج [حدث](/ar/aftersell/cart/sdk-events) ألقى خطأ           | `console.error`؛ المعالجات الأخرى تستمر في العمل     |
| [خُطاف](/ar/aftersell/cart/sdk-hooks) ألقى خطأ                | صامت. يذهب إلى قناة التصحيح أدناه                    |
| [إجراء](/ar/aftersell/cart/sdk-actions) نُفّذ قبل تحميل السلة | `console.warn`؛ الاستدعاء لا يفعل شيئًا              |

<div id="when-your-script-throws">
  ### عندما يُلقي نصك البرمجي خطأ
</div>

يتوقف النص البرمجي المخصص **عند أول خطأ**، لذا فإن كل `configure` و `events.on` و `hooks.register*` تحت ذلك السطر لا تعمل أبدًا. تقول السلة ذلك صراحةً:

```
[aftersell-cart] Initialization script error on line 12 — 4 more line(s) did not run;
any configure/events/hooks below are unregistered.
```

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

كما تعمل نصوصك البرمجية تحت أسماء ملفاتها الخاصة، لذا تظهر باسم `aftersell-cart-init.js` و `aftersell-cart-cart-update.js` في DevTools. يمكنك فتحها من لوحة Sources وتعيين نقاط توقف مثل أي ملف آخر.

<div id="the-debug-channel">
  ### قناة التصحيح
</div>

تُبقى أعطال الخُطافات عمدًا بعيدة عن وحدة التحكم حتى لا يراها المتسوقون أبدًا. إنها تذهب إلى هنا بدلًا من ذلك:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// After reproducing the problem, inspect what was swallowed:
window.aftersellCartDebugEvents.filter((entry) => entry.level === 'ERROR');

// Or watch them live:
window.addEventListener('aftersell-cart-debug', (event) => console.log(event.detail));
```

<div id="where-to-go-next">
  ## إلى أين تذهب بعد ذلك
</div>

<Columns cols={2}>
  <Card title="التهيئة" icon="sliders" href="/ar/aftersell/cart/sdk-configure">
    كل خيار، مع مثال لكل منها.
  </Card>

  <Card title="الأحداث" icon="tower-broadcast" href="/ar/aftersell/cart/sdk-events">
    كل حدث، ومتى ينطلق، وما الذي يجب تجنبه في المعالج.
  </Card>

  <Card title="الإجراءات" icon="wand-magic-sparkles" href="/ar/aftersell/cart/sdk-actions">
    كل إجراء، مع مقتطف لكل منها.
  </Card>

  <Card title="الخُطافات" icon="plug" href="/ar/aftersell/cart/sdk-hooks">
    كل خُطاف، وكيف تتراكب التسجيلات.
  </Card>

  <Card title="كائن السلة" icon="table-list" href="/ar/aftersell/cart/sdk-cart-object">
    شكل السلة وأسطرها.
  </Card>

  <Card title="حالات الاستخدام" icon="book-open" href="/ar/aftersell/cart/sdk-use-cases">
    حلول كاملة وقابلة للتشغيل لأكثر الطلبات شيوعًا.
  </Card>
</Columns>