التطبيقات المدمجة في زد: ابنِ تجربتك داخل لوحة تحكم التاجر

لماذا تبني تطبيقًا مدمجًا؟

التطبيق المدمج يعمل داخل لوحة تحكم التاجر في زد عبر iframe. يفتح التاجر تطبيقك ويستخدمه دون أن يغادر اللوحة، ودون تسجيل دخول منفصل.

هذه الفوائد كما يذكرها التوثيق:

• تكامل سلس: تجربة واحدة متصلة للتاجر.
• ظهور أكبر: وصول وتفاعل أكبر مع تطبيقك.
• دخول أسهل: لا حاجة إلى تسجيل دخول منفصل.
• ولاء أعلى: التجربة السلسة ترفع رضا التاجر وتطيل استخدامه للتطبيق.

الـ Authentication في ست خطوات

التطبيقات المدمجة لا تستخدم تسجيل الدخول المعتاد. تمر الـ Authentication بست خطوات، وكلها إلزامية:

1. التاجر يثبّت التطبيق: توجّهه زد إلى Redirect URL الخاص بك مع Authorization Code. أضِف صلاحية embedded_apps_tokens_write إلى طلب OAuth الأول.
2. استبدال الرمز بالـ Tokens: احفظ access_token وauthorization وrefresh_token مرتبطة بقيمة store_id الخاصة بالتاجر.
3. تسجيل رمز البحث: أنشئ UUID من الإصدار 4 على الـ Server الخاص بك، واحفظه مع Tokens التاجر، ثم سجّله لدى زد. لا تستخدم authorization هنا، فهو JWT طويل يُقتطع حين يُمرَّر في رابط الـ iframe.
4. ضبط Application URL: في لوحة المطورين، اجعله يشير إلى endpoint ثابت على الـ Server الخاص بك يعرض محتوى الـ iframe، مثل https://your-app.com/embedded.
5. التاجر يفتح التطبيق: تحمّل زد رابط تطبيقك داخل iframe وتضيف إليه الـ UUID.
6. التعرّف على التاجر وعرض الصفحة: اقرأ المعامل token، وابحث عن الـ UUID في Databaseك لتجلب store_id والـ Tokens، ثم اعرض الصفحة.

هذا طلب تسجيل الـ UUID في الخطوة الثالثة:

curl -X POST 'https://api.zid.sa/v1/managers/embedded-apps-token' \
  --header 'Authorization: Bearer {{authorization}}' \
  --header 'x-manager-token: {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
      "token": "{{your_generated_uuid}}"
  }'

وهذا ما يصل إلى رابط تطبيقك في الخطوة الخامسة:

GET /embedded?token={{your_generated_uuid}}&language=en

التوجيه والأمان وحذف الـ Token

حين يكتمل OAuth في تطبيقك، يمكنك توجيه التاجر مباشرة إلى التطبيق داخل اللوحة:

https://dashboard.zid.sa/{language_code}/stores/{store_id}/apps/{app_id}/embedded

يجب أن يكون {app_id} هو ID تطبيقك الفعلي في زد. أما المتجر ولغة اللوحة فتحددهما زد من Session التاجر، فلا حاجة إلى أن تكتشف اللغة بنفسك.

تفرض زد سياسة Content Security Policy على التطبيقات المدمجة، ويجب أن ترسل كل صفحة داخل الـ iframe Headers CSP المذكورة في التوثيق. وإذا غاب منها frame-ancestors، فستحجب اللوحة تطبيقك.

أخطاء شائعة ينبّه إليها التوثيق:

• خصّص UUID فريدًا لكل متجر، وأنشئ UUID جديدًا إذا أعاد التاجر التثبيت، لأن القديم يصبح غير صالح.
• استخدم رموزًا آمنة للروابط. صيغة UUID (أرقام ست عشرية وشرطات) آمنة.
• احفظ access_token وauthorization على الـ Server الخاص بك فقط، ولا تعرضهما أبدًا للمتصفح أو في HTML الـ iframe.
• عند إلغاء التثبيت، احذف Token التاجر بطلب DELETE https://api.zid.sa/v1/managers/embedded-apps-token.

واجهة بمظهر زد مع Zid MUI

إذا كنت تبني تطبيقًا مدمجًا، ينصح التوثيق باستخدام Zid MUI لتبقى واجهتك منسجمة مع لوحة زد. هي مكتبة واجهات مبنية على نظام تصميم MUI وعلى إرشادات هوية زد، وفيها مكوّنات وأيقونات وhooks وأدوات للثيم، مع دعم كامل للاتجاه من اليمين إلى اليسار.

تستطيع استخدامها بطريقتين:

• React: مكتبة المكوّنات كاملة. غلّف تطبيقك بـ ThemeProvider من MUI مع themeParcel، ثم استورد مكوّنات مثل AppButton وAppInputBase.
• CSS فقط: لمشاريع Vue أو Angular أو JavaScript الخالص. ثبّت الحزمة بـ pnpm add @zidsa/zidmui، واستورد ملف الأنماط، وأضِف خط IBM Plex Sans Arabic، ثم استخدم أصنافًا مثل zid-button وzid-input.

أمر التثبيت لمشاريع React:

pnpm add @zidsa/zidmui react react-dom use-debounce @mui/material @mui/lab @emotion/styled

تصفّح جميع المكوّنات في Zid MUI Storybook على ui.zid.sa.

Servers أسرع مع Zid SDKs

تتولى Zid SDKs التواصل مع APIs زد نيابة عنك، وفيها نماذج بيانات جاهزة لردود الواجهات. لذلك تناسب خدمات الـ Server و Scripts الأتمتة والتكاملات.

• Python: متاحة الآن على GitHub في zidsa/sdk-python، ومعها تطبيق تجريبي في zidsa/demo-app-python.
• Laravel وTypeScript: يذكر التوثيق أنهما قادمتان قريبًا.

تفاعل مع ما يحدث في واجهة المتجر

كثير من التطبيقات المدمجة تحتاج أن تعرف ما يفعله المتسوقون في المتجر. عبر Custom Snippets يحقن تطبيقك كود JavaScript أو CSS في كل متجر ثبّته. أضِفها من الإعدادات العامة لتطبيقك في لوحة الشركاء، ثم أرسلها للمراجعة.

يستطيع الـ Script أن يقرأ Objects عامة مثل window.customer وwindow.customerAuthState وwindow.customerAsync، وأن يستجيب لسبعة أحداث مدعومة في واجهة المتجر:

• الشراء، وعرض المنتج، والإضافة إلى السلة، والحذف من السلة، وبدء الدفع.
• عرض قائمة المنتجات واختيار منتج منها، وهما حدثان جديدان بحسب التوثيق.