التكاملات الخارجية

🔗 التكاملات الخارجية

قم بربط أحداث LoyaltyTree الخاصة بك مع منصات التسويق والأتمتة والتحليلات الخارجية. أرسل بيانات الوقت الحقيقي حول نشاط العملاء لتعزيز حملات البريد الإلكتروني، وشرائح العملاء، والأتمتة، والمزيد.

المنصات المدعومة

يدعم LoyaltyTree إرسال الأحداث إلى المنصات التالية:

المنصة	النوع	ما تحتاجه
Klaviyo	تسويق عبر البريد الإلكتروني/SMS	مفتاح API الخاص بك في Klaviyo
Omnisend	تسويق عبر البريد الإلكتروني/SMS	مفتاح API الخاص بك في Omnisend
Shopify Flow	أتمتة Shopify	مقبض مشغل تدفق (تم إنشاؤه في Shopify Flow)
Webhook عام	أي نقطة نهاية HTTP	رابط webhook يقبل طلبات POST

البدء

الخطوة 1: الانتقال إلى التكاملات

اذهب إلى المتاجر → [متجرك] → التكاملات → Webhooks الخارجية في لوحة التحكم الخاصة بك.

الخطوة 2: إضافة تكامل جديد

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

الخطوة 3: إدخال بيانات الاعتماد الخاصة بك

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

الخطوة 4: اختبار الاتصال

استخدم زر اختبار على بطاقة التكامل الخاصة بك لإرسال حدث اختبار والتحقق من أن كل شيء متصل بشكل صحيح.

الأحداث المدعومة (19 إجمالي)

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

🌱 أحداث كسب البذور

يتم تفعيلها عندما يكسب العميل بذورًا من خلال أنشطة متنوعة.

الحدث	مفتاح الحدث	يتم تفعيله عندما
البذور – المكتسبة – الطلب	`seeds.earned.order`	يكسب العميل بذورًا من عملية شراء
البذور – المكتسبة – الزيارة	`seeds.earned.visit`	يكسب العميل بذورًا من زيارة المتجر
البذور – المكتسبة – المراجعة	`seeds.earned.review`	يكسب العميل بذورًا من كتابة مراجعة
البذور – المكتسبة – الإحالة	`seeds.earned.referral`	يكسب العميل بذورًا من إحالة ناجحة
البذور – المكتسبة – المشاركة الاجتماعية	`seeds.earned.social_share`	يكسب العميل بذورًا من المشاركة على وسائل التواصل الاجتماعي
البذور – المكتسبة – المكافأة	`seeds.earned.bonus`	يتلقى العميل بذورًا إضافية (عيد ميلاد، جائزة يدوية، إلخ)

⭐ أحداث المستوى والمراجعة

الحدث	مفتاح الحدث	يتم تفعيله عندما
المستوى – تغير	`tier.changed`	ينتقل العميل إلى مستوى ولاء مختلف
المراجعة – المقدمة	`review.submitted`	يقدم العميل مراجعة جديدة للمنتج
المراجعة – المعتمدة	`review.approved`	تمت الموافقة على مراجعة المنتج (من قبل الذكاء الاصطناعي أو يدويًا)
المراجعة – مرفوضة	`review.rejected`	تم رفض مراجعة المنتج

🎁 أحداث المكافأة

الحدث	مفتاح الحدث	يتم تفعيله عندما
بطاقة هدايا – مكتسبة	`gift_card.earned`	يؤهل العميل للحصول على مكافأة بطاقة هدايا
بطاقة هدايا – تم المطالبة بها	`gift_card.claimed`	يسترد العميل بطاقة الهدايا الخاصة به
رصيد المتجر – مكتسب	`store_credit.earned`	يؤهل العميل للحصول على رصيد المتجر
رصيد المتجر – تم المطالبة به	`store_credit.claimed`	يسترد العميل رصيد المتجر الخاص به

🌳 أحداث البيئة والإحالة

الحدث	مفتاح الحدث	يتم تفعيله عندما
المنتج البيئي – مُنح	`eco_product.awarded`	يسترد العميل بذورًا مقابل منتج بيئي
البيئة – تم زرع شجرة	`eco.tree_planted`	تُزرع شجرة للعميل
الإحالة – تم إنشاؤها	`referral.generated`	ينشئ العميل رابط إحالة
الإحالة – زيارة	`referral.visit`	يزور شخص المتجر من خلال رابط إحالة
الإحالة – ناجحة	`referral.successful`	يقوم زائر مُحال بإجراء عملية شراء

أدلة إعداد المنصة

📧 Klaviyo

Klaviyo هي منصة تسويق عبر البريد الإلكتروني وSMS تحظى بشعبية بين متاجر Shopify. يرسل LoyaltyTree الأحداث إلى Klaviyo باستخدام API الأحداث (v3) الخاصة بهم، بحيث يمكنك بناء شرائح، وتدفقات، وحملات بناءً على نشاط الولاء.

الإعداد:

في Klaviyo، انتقل إلى الإعدادات → مفاتيح API وأنشئ مفتاح API خاص
في LoyaltyTree، انقر على + إضافة تكامل، واختر Klaviyo
ألصق مفتاح API الخاص بك
اختر الأحداث التي تريد إرسالها
انقر على حفظ التكامل

كيف يعمل: يقوم LoyaltyTree بإنشاء أحداث Klaviyo مع بريد العميل الإلكتروني كمعرف الملف الشخصي. تظهر الأحداث كمقاييس مخصصة (مثل "البذور المكتسبة من الطلب"، "تغير المستوى") التي يمكنك استخدامها في تدفقات وشرائح Klaviyo. يتم إرسال كميات البذور كقيمة الحدث، بحيث يمكنك استخدامها في الانقسامات الشرطية.

📨 Omnisend

Omnisend هي منصة تسويق عبر البريد الإلكتروني وSMS أخرى تحظى بشعبية. يرسل LoyaltyTree الأحداث باستخدام API أحداث Omnisend (v5).

الإعداد:

في Omnisend، انتقل إلى الإعدادات → مفاتيح API وأنشئ مفتاحًا
في LoyaltyTree، انقر على + إضافة تكامل، واختر Omnisend
ألصق مفتاح API الخاص بك
اختر الأحداث التي تريد إرسالها
انقر على حفظ التكامل

كيف يعمل: يتم إرسال الأحداث مع بريد العميل الإلكتروني، والاسم، ومعرف العميل في Shopify. تتضمن كل حدث جميع الخصائص ذات الصلة (كميات البذور، تفاصيل الطلب، معلومات المستوى، إلخ) بحيث يمكنك استخدامها في سير العمل الأوتوماتيكي في Omnisend وتقسيم العملاء.

⚡ Shopify Flow

Shopify Flow هي أداة الأتمتة المدمجة في Shopify. يرسل LoyaltyTree الأحداث مباشرة إلى Shopify Flow باستخدام تغيير تدفق GraphQL flowTriggerReceive، مما يعني أن الأحداث تظهر كمشغلات داخل سير العمل الخاص بك في Flow - لا حاجة لتطبيقات طرف ثالث.

⚠️ هام: Shopify Flow متاح على خطة Shopify الأساسية وما فوق. تحتاج إلى تثبيت تطبيق Shopify Flow في متجرك.

الإعداد:

في لوحة التحكم الخاصة بك في Shopify، انتقل إلى Flow وأنشئ سير عمل جديد
أضف مشغلًا - استخدم مقبض المشغل من تطبيق LoyaltyTree
في LoyaltyTree، انقر على + إضافة تكامل، واختر Shopify Flow
أدخل مقبض مشغل التدفق الذي يتطابق مع مشغل Shopify Flow الخاص بك
اختر الأحداث التي تريد إرسالها
انقر على حفظ التكامل

كيف يعمل: عندما يحدث حدث مشترك، يستخدم LoyaltyTree اتصال API Shopify لمتجرك لإرسال بيانات الحدث مباشرة إلى Shopify Flow عبر GraphQL. يتم تسوية الحمولة إلى مفاتيح قابلة للقراءة البشرية مثل "بريد العميل الإلكتروني"، "نوع الحدث"، "المبلغ"، إلخ. يمكنك بعد ذلك استخدام هذه القيم كشرط في Flow لتحفيز إجراءات مثل إرسال البريد الإلكتروني، أو وضع علامات على العملاء، أو إنشاء مهام.

أمثلة على أتمتة Shopify Flow:

وضع علامات على العملاء عندما يصلون إلى المستوى الذهبي
إرسال إشعار داخلي عبر Slack عندما تُزرع شجرة
إنشاء مهمة عندما يتم تقديم مراجعة
إضافة ملاحظة إلى ملف العميل عندما يكسبون بطاقة هدايا

🌐 Webhook عام

أرسل أحداث LoyaltyTree إلى أي نقطة نهاية HTTP. هذا مثالي للاتصال بالأنظمة المخصصة، أو Zapier، أو Make (Integromat)، أو n8n، أو أي منصة أخرى تقبل POSTs webhook.

الإعداد:

احصل على رابط نقطة نهاية webhook من منصتك المستقبلة
في LoyaltyTree، انقر على + إضافة تكامل، واختر Webhook عام
أدخل رابط webhook
(اختياري) اختر طريقة المصادقة وأضف بيانات الاعتماد
(اختياري) أضف سر webhook للتحقق من توقيع HMAC
اختر الأحداث التي تريد إرسالها
انقر على حفظ التكامل

خيارات المصادقة:

الطريقة	الرأس المرسل	الوصف
توقيع HMAC	`X-LoyaltyTree-Signature`	SHA-256 HMAC لجسم الحمولة، موقع باستخدام سر webhook الخاص بك
رمز Bearer	`Authorization: Bearer <token>`	مصادقة رمز Bearer على نمط OAuth القياسي
X-Token	`X-Token: <token>`	رمز بسيط في رأس مخصص
رأس مخصص	`<your-header>: <token>`	حدد اسم رأسك الخاص وقيمة الرمز

قوالب الحمولة المخصصة: بالنسبة لـ Webhooks العامة، يمكنك تخصيص تنسيق الحمولة لكل حدث باستخدام متغيرات القالب. هذا يتيح لك مطابقة التنسيق الدقيق الذي تتوقعه نظامك المستلم.

الرؤوس القياسية المرسلة مع كل طلب:

Content-Type: application/json
User-Agent: LoyaltyTree/1.0
X-LoyaltyTree-Event: <event_type>
X-LoyaltyTree-Timestamp: <ISO timestamp>

مثال على حمولة Webhook

إليك كيف يبدو حدث seeds.earned.order عند تسليمه إلى Webhook عام:

{
  "event": "seeds.earned.order",
  "timestamp": "2026-02-06T14:30:00.000Z",
  "customer": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "display_name": "Jane Smith",
    "shopify_customer_id": "7891234567890"
  },
  "amount": 50,
  "order_id": "6012345678901",
  "order_number": "1042",
  "order_total": "89.99",
  "order_currency": "USD",
  "balance": 350,
  "tier": "Silver"
}

تتضمن كل حمولة حدث كائن العميل مع بريدهم الإلكتروني، واسمهم، ومعرف العميل في Shopify، بالإضافة إلى حقول البيانات الخاصة بالحدث.

مرجع بيانات الحدث

فيما يلي قائمة مفصلة بالحقول البيانات المضمنة مع كل نوع حدث.

🌱 seeds.earned.order

amount – عدد البذور المكتسبة
order_id – معرف الطلب في Shopify
order_number – رقم الطلب القابل للقراءة البشرية
order_total – المبلغ الإجمالي للطلب
order_currency – رمز العملة (مثل USD)
balance – رصيد البذور الجديد للعميل
tier – اسم المستوى الحالي للعميل

👁️ seeds.earned.visit

amount – عدد البذور المكتسبة
visit_number – أي زيارة كانت هذه
balance – رصيد البذور الجديد للعميل
tier – اسم المستوى الحالي للعميل

✍️ seeds.earned.review

amount – عدد البذور المكتسبة
product – كائن مع id وtitle للمنتج
rating – تقييم النجوم (1-5)
has_photos – ما إذا كانت المراجعة تتضمن صورًا
platform – منصة المراجعة (مثل "loyaltytree")
balance – رصيد البذور الجديد للعميل
tier – اسم المستوى الحالي للعميل

🤝 seeds.earned.referral

amount – عدد البذور المكتسبة
referral_type – نوع الإحالة (مثل "referral_purchase")
referred_customer – كائن مع معلومات العميل المُحال
balance – رصيد البذور الجديد للعميل
tier – اسم المستوى الحالي للعميل

📱 seeds.earned.social_share

amount – عدد البذور المكتسبة
platform – المنصة الاجتماعية المستخدمة (مثل "تويتر"، "فيسبوك")
share_url – الرابط الذي تم مشاركته
balance – رصيد البذور الجديد للعميل
tier – اسم المستوى الحالي للعميل

🎉 seeds.earned.bonus

amount – عدد البذور المكتسبة
reason – سبب المكافأة (مثل "مكافأة عيد الميلاد")
balance – رصيد البذور الجديد للعميل
tier – اسم المستوى الحالي للعميل

📊 tier.changed

old_tier – اسم المستوى السابق
new_tier – اسم المستوى الجديد
total_seeds – إجمالي بذور العميل مدى الحياة

📝 review.submitted

review_id – معرف المراجعة الفريد
product – كائن مع id وtitle للمنتج
rating – تقييم النجوم (1-5)
title – عنوان المراجعة
body – نص جسم المراجعة
photos – مصفوفة من روابط الصور
has_photo – ما إذا كانت المراجعة تحتوي على صور

✅ review.approved

review_id – معرف المراجعة الفريد
product – كائن مع id وtitle للمنتج
rating – تقييم النجوم (1-5)
title – عنوان المراجعة
body – نص جسم المراجعة
photos – مصفوفة من روابط الصور
seeds_awarded – البذور الممنوحة لهذه المراجعة

❌ review.rejected

review_id – معرف المراجعة الفريد
product – كائن مع id وtitle للمنتج
rating – تقييم النجوم (1-5)
rejection_reason – سبب رفض المراجعة

🎁 gift_card.earned

amount – القيمة النقدية لبطاقة الهدايا
currency – رمز العملة
seeds_redeemed – البذور التي تم إنفاقها لكسب ذلك
tier – المستوى الحالي للعميل

💳 gift_card.claimed

amount – القيمة النقدية لبطاقة الهدايا
currency – رمز العملة
code – رمز بطاقة الهدايا

💰 store_credit.earned & store_credit.claimed

amount – القيمة النقدية لرصيد المتجر
currency – رمز العملة
seeds_redeemed – البذور التي تم إنفاقها (فقط حدث الكسب)
tier – المستوى الحالي للعميل (فقط حدث الكسب)

🌳 eco_product.awarded

eco_product_name – اسم المنتج البيئي
eco_product_type – النوع (مثل "شجرة"، "مرجان")
seeds_spent – البذور التي تم إنفاقها على هذا المنتج

🌲 eco.tree_planted

trees_count – عدد الأشجار المزروعة
project_name – اسم مشروع إعادة التشجير
certificate_url – رابط شهادة الزراعة

🔗 referral.generated, referral.visit & referral.successful

referral_code – رمز الإحالة الفريد (تم إنشاؤه فقط)
share_url – رابط الإحالة (تم إنشاؤه فقط)
visitor_id – معرف الزائر المجهول (فقط الزيارة)
seeds_awarded – البذور المكتسبة (فقط الزيارة والنجاح)
referred_customer – معلومات حول العميل الجديد (فقط النجاح)
order_total – المبلغ الإجمالي لطلب العميل المُحال (فقط النجاح)

موثوقية & منطق إعادة المحاولة

يستخدم LoyaltyTree قائمة انتظار غير متزامنة لضمان تسليم الأحداث بشكل موثوق. لا تُفقد الأحداث أبدًا - إذا فشل التسليم، فإن النظام يعيد المحاولة تلقائيًا مع زيادة زمن الانتظار بشكل متزايد.

محاولة إعادة المحاولة	زمن الانتظار
المحاولة الأولى	1 دقيقة
المحاولة الثانية	5 دقائق
المحاولة الثالثة	30 دقيقة
المحاولة الرابعة	ساعتان
المحاولة الخامسة (الأخيرة)	24 ساعة

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

سجلات الأحداث

يتم تسجيل كل تسليم حدث ويمكن رؤيته في قسم سجلات الأحداث على صفحة التكاملات. يمكنك تصفية السجلات حسب:

الاتصال – رؤية الأحداث لتكامل معين
الحدث – تصفية حسب نوع الحدث
العميل – البحث بواسطة بريد العميل الإلكتروني أو الاسم
نطاق التاريخ – عرض الأحداث من فترة زمنية معينة

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

استكشاف الأخطاء وإصلاحها

تظهر الأحداث حالة "فاشلة"

تحقق من رسالة الخطأ في سجلات الأحداث. الأسباب الشائعة:

تعذر الاتصال – قد يكون رابط webhook معطلاً أو غير صحيح
خطأ 401/403 – قد يكون مفتاح API أو رمز المصادقة الخاص بك غير صالح
انتهاء الوقت – الخادم المستلم بطيء جدًا في الاستجابة (انتهاء الوقت 10 ثواني)

لا تظهر الأحداث في Klaviyo/Omnisend

تأكد من أن العميل لديه عنوان بريد إلكتروني صالح. تتطلب كل من Klaviyo وOmnisend بريدًا إلكترونيًا لربط الحدث. العملاء المجهولون الذين ليس لديهم بريد إلكتروني لن يولدوا أحداثًا لهذه المنصات.

مشغل Shopify Flow لا يعمل

تحقق من:

تم تثبيت تطبيق Shopify Flow في متجرك
سير العمل الخاص بك في Flow نشط (غير متوقف)
يتطابق مقبض المشغل في LoyaltyTree تمامًا مع ما قمت بإعداده في Shopify Flow
تدعم خطتك في Shopify Flow (الأساسية أو أعلى)

الأمان

جميع مفاتيح API والرموز مشفرة أثناء الراحة باستخدام تشفير AES-256-CBC
تتيح أسرار webhook التحقق من توقيع HMAC حتى يتمكن نقطة النهاية الخاصة بك من التحقق من أن الطلبات جاءت بالفعل من LoyaltyTree
تتم معالجة الأحداث من خلال قائمة انتظار غير متزامنة - لا تتأثر أداء متجرك بتسليم التكامل
يتم تنظيف الأحداث القديمة والسجلات تلقائيًا بعد 30 يومًا