الدخول المستند إلى API

تحتاج إلى مساعدة المطور

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

كيف يعمل

يسمح لك الدخول المستند إلى API بإطلاق رحلة العميل في اللحظة التي يقع فيها حدث تجاري معين. لبدء حملة، يجب عليك إرسال طلب API خاص.

فيما يلي بعض حالات الاستخدام للدخول المستند إلى API:

• إعلام العملاء عند عودة المنتجات إلى المخزون
• إخبار المستخدمين بانخفاض سعر منتج شائع
• إشعار المشتركين عند صدور حلقة بودكاست جديدة

على عكس الأحداث (Events) العادية، قد تحدث كل هذه الأحداث التجارية خارج التطبيق. على سبيل المثال، لا يمكن التحقق من توفر منتج إلا في قاعدة بيانات خارجية. هنا يأتي دور الدخول المستند إلى API: يمكنك إعداد إرسال طلب لإطلاق رحلة كلما حدثت تغييرات معينة خارج التطبيق (على سبيل المثال، في قاعدة بياناتك الخارجية).

يعمل على النحو التالي:

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

يمكنك إرسال الطلب عددًا غير محدود من المرات لتغيير شروط التجزئة أو محتوى الرسالة.

لمزيد من التفاصيل، اتبع التعليمات أدناه.

إعداد رحلة بدخول مستند إلى API

1. أنشئ رحلة بدخول مستند إلى API:

2. انقر نقرًا مزدوجًا على خطوة الدخول المستند إلى API. ستفتح نافذة تكوين الدخول.

3. يمكنك تعديل محتوى الإشعارات الفورية (push) والبريد الإلكتروني (email) في كل مرة يتم فيها إطلاق الرحلة باستخدام العناصر النائبة للمحتوى. يمكن تغيير قيمة كل عنصر نائب في الطلب. إذا لم تكن بحاجة إلى هذا الخيار، يمكنك تخطي هذه الخطوة.

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

أولاً، أضف أسماء العناصر النائبة في نافذة إعداد الدخول المستند إلى API. يمكنك استخدام أي أسماء مناسبة لك.

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

• {placeholder_name|format_modifier|} – إذا لم يتم تحديد قيمة العنصر النائب عند إطلاق الحملة، سيرى المستخدمون مساحة فارغة في مكانه.
• {placeholder_name|format_modifier} – إذا لم يتم تحديد قيمة العنصر النائب ولم يتم تعيينها بالفعل لمستخدم (في حال استخدمت وسمًا (Tag) كعنصر نائب)، فلن يتم إرسال الرسالة.

معدِّلات التنسيق

• CapitalizeFirst – يحول الحرف الأول في قيمة العنصر النائب إلى حرف كبير
• CapitalizeAllFirst – يحول الحرف الأول في كل كلمة من قيمة العنصر النائب إلى حرف كبير
• UPPERCASE – يحول كل الحروف إلى أحرف كبيرة
• lowercase – يحول كل الحروف إلى أحرف صغيرة
• regular – يدرج قيمة العنصر النائب تمامًا كما هي محددة في الطلب

نصيحة

يمكنك أيضًا استخدام اسم وسم (Tag) موجود بدلاً من اسم العنصر النائب. في هذه الحالة، يجب عليك تكوين الكتابة فوق قيمة هذا الوسم بالقيمة المحددة في الطلب كما هو موضح أدناه.

عند تكوين عنصر الإشعار الفوري (Push) أو البريد الإلكتروني (Email) في رحلتك، حدد الإعداد المسبق الذي تم إنشاؤه وقم بتشغيل خيار تخصيص الرسالة بسمات الحدث (Personalize message with event attributes).

حدد العناصر النائبة التي تريد تعديلها في الطلب عند إطلاق الرحلة. اختر إدخال الدخول المستند إلى API (API-based entry entry) كمصدر واسم العنصر النائب كسمة ديناميكية:

انقر على تطبيق (Apply) لحفظ التغييرات.

4. في نافذة تكوين الدخول، انسخ قالب الطلب لتعديله:

ملاحظة

لإطلاق رحلة عبر API، يجب عليك تضمين رمز تفويض صالح في رأس Authorization.

تنسيق الرأس المطلوب

Authorization: Api <your_api_token>

مثال

Authorization: Api c8dc6435-xxxxxxxxxxxxxxx

5. أضف فلاتر الجمهور إلى المعلمة "filter" باستخدام لغة التجزئة أو انسخ منطق التجزئة من شرائحك. قم بإعداد الوسوم (Tags) اللازمة مسبقًا.

على سبيل المثال، لاستهداف المستخدمين الذين أضافوا عنصر Socks إلى Wishlist الخاصة بهم، يجب أن تبدو قيمة "filter" كما يلي:

"filter": "A(\"12345-12345\") * "T(\"Wishlist\", EQ, \"Socks\")"

في هذا المثال، يجب أن يكون لديك وسم Wishlist مهيأ في تطبيقك.

ملاحظة

يتم إضافة رمز التطبيق الخاص بك تلقائيًا إلى المعلمة "filter" بالتنسيق A(\"12345-12345\"). لا تقم بإزالته أو تعديله.

أيضًا، يرجى الأخذ في الاعتبار أنه يجب تهريب علامات الاقتباس ("") والشرطات المائلة العكسية (\) بشرطة مائلة عكسية (\) في استعلامات JSON.

نصيحة

يمكنك أيضًا استهداف أجهزة أو مستخدمين معينين مباشرةً عن طريق تمرير مصفوفة من HWIDs في المعلمة "hwids" أو معرفات المستخدمين (User IDs) في المعلمة "users" بدلاً من استخدام الفلاتر:

"users": ["user_id_1", "user_id_2", ...],
"hwids": ["hwid_1", "hwid_2", ...]

6. إذا قمت بإعداد العناصر النائبة، فحدد المحتوى المطلوب كقيم لها:

7. إذا كنت تخطط لإعادة تشغيل حملتك بشكل متكرر ولا تريد أن يدخل نفس المستخدمين الرحلة عدة مرات، فقم بتعيين حدود الدخول إلى الحملة.

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

8. إذا كنت تريد إطلاق رحلة كلما حدث حدث تجاري معين، فقم بأتمتة الطلب باستخدام الـ webhook. بمجرد وقوع الحدث، يجب على الـ webhook إرسال الطلب تلقائيًا لبدء الرحلة.

يمكنك أيضًا إرسال الطلب يدويًا إذا لم تكن بحاجة إلى الأتمتة.

ملاحظة

• إذا قمت بتغيير شروط التجزئة عند إرسال طلب جديد، فلن يؤثر ذلك على المستخدمين الذين دخلوا الرحلة بالفعل.
• إذا قمت بتغيير محتوى الرسالة عند إرسال طلب جديد، فسيتلقى جميع المستخدمين الإصدار الجديد من الرسالة (بما في ذلك أولئك الذين دخلوا الرحلة بالفعل ولكنهم لم يتلقوا هذه الرسالة بعد).