كيف يمكن للمطورين توسيع وظائف Braze

لتوسيع وظائف Braze، اختر نقطة الامتداد بناءً على سؤالين: اتجاه تدفق البيانات، ومدى حداثتها. تدخل البيانات عبر حزمة تطوير البرمجيات (SDK)، أو واجهة برمجة تطبيقات Braze، أو ميزة استيعاب بيانات السحابة (Cloud Data Ingestion)، أو تحويل البيانات. وتخرج البيانات عبر خطافات الويب (webhooks) وخدمة Currents، وتصل عند وقت العرض عبر المحتوى المتصل (Connected Content)، وتعمل على الشاشة من خلال جسر JavaScript.

‍

أبرز النقاط

• اختر كل نقطة امتداد في Braze بناءً على اتجاه تدفق البيانات ومدى حداثتها.
• استخدم التجميع (Batch) لطلبات /users/track، حيث يمكن لكل طلب أن يحمل ما يصل إلى 75 كائناً عبر السمات والأحداث والمشتريات.
• تستدعي ميزة المحتوى المتصل (Connected Content) نقطة النهاية الخاصة بك مع عرض كل رسالة، لذا تأكد من ضبط حجم نقطة النهاية بما يتناسب مع أكبر عملية إرسال لديك.
• لا تعيد Braze محاولة إرسال خطافات الويب (webhooks) إلا في حالات استجابة معينة، مثل 408 و429 و5XX، لذا راقب النظام المستقبِل لرصد أخطاء العميل.
• توفر خدمة Currents البيانات مرة واحدة على الأقل، لذا تأكد من إزالة التكرارات باستخدام حقل معرف الحدث (event id).
• في كود HTML المخصص، استدعِ طريقة النقر (click method) الخاصة بجسر JavaScript بشكل صريح، وإلا ستبقى تقارير النقر لتلك الرسالة فارغة.

‍

ماذا يعني توسيع وظائف Braze كمطور؟

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

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

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

‍

أي نقطة امتداد تناسب أي مهمة؟

كل صف أدناه يمثل نقطة امتداد موثقة. العمود الأخير هو السلوك الذي يجب التصميم بناءً عليه، وهو الجزء الذي يتطلب معظم جهد البناء.

نقطة الامتداد | الاتجاه | وقت التشغيل | التصميم بناءً على SDK | إلى داخل Braze | عند قيام المستخدم بإجراء | يتم تخزين الأحداث غير المرسلة على الجهاز وإعادة محاولة إرسالها بعد إعادة الاتصال، دون حدوث انقطاع زمني REST API, /users/track | إلى داخل Braze | عند استدعاء نظامك | ما يصل إلى 75 كائناً لكل طلب عبر السمات والأحداث والمشتريات استيعاب بيانات السحابة | إلى داخل Braze | وفق جدول زمني أو عند الطلب | أقصر فاصل زمني للوحة التحكم هو 15 دقيقة افتراضياً؛ يمكن لنقطة النهاية تشغيل مزامنة عند الطلب تحويل البيانات | إلى داخل Braze | عندما يرسل طرف ثالث خطاف ويب | الكتابة عبر /users/track وتسجيل نقاط البيانات بنفس الطريقة المحتوى المتصل | إلى داخل رسالة | عند عرض الرسالة | طلبات GET مخزنة مؤقتاً افتراضياً؛ إعادة المحاولة غير متاحة لرسائل داخل التطبيق أو اللافتات خطافات الويب | إلى خارج Braze | عند إرسال خطوة رسالة | إعادة المحاولة فقط لاستجابات معينة؛ معظم أخطاء العميل لا تتم إعادة محاولتها Currents | إلى خارج Braze | بشكل مستمر | تسليم مرة واحدة على الأقل، لذا قد تحدث تكرارات جسر JavaScript | على الشاشة | عند تفاعل المستخدم | تحتاج النقرات في الكود المخصص إلى استدعاء صريح ليتم تسجيلها

‍

يوضح الجدول أيضاً ما ينقص التكامل الفردي. خطط لمسار وارد واحد على الأقل، ومسار صادر واحد، وقرار بشأن بيانات وقت العرض.

‍

كيف يجب أن تصل البيانات إلى Braze؟

استخدم SDK لأي إجراء يقوم به المستخدم في تطبيقك، لأنه الأقرب للحدث. توثق Braze أن حزم SDK لنظام Android وSwift والويب تخزن الأحداث غير المرسلة على الجهاز وتعيد محاولتها بعد إعادة الاتصال، دون حدوث انقطاع زمني. لذا، فإن الأحداث المتأخرة أمر طبيعي، ويجب على أي نموذج لاحق قبولها.

استخدم واجهة برمجة تطبيقات Braze عندما تكون أنظمتك هي المصدر الموثوق للبيانات. يمكن لكل طلب /users/track أن يحمل ما يصل إلى 75 كائناً مجتمعة عبر السمات والأحداث والمشتريات. قم بتجميع التحديثات حتى ذلك الحد بدلاً من إرسال طلب واحد لكل تغيير، ليبقى عدد الطلبات منخفضاً.

استخدم ميزة استيعاب بيانات السحابة عندما تكون البيانات موجودة بالفعل في مستودع بيانات. افتراضياً، أقصر فاصل زمني للوحة التحكم هو 15 دقيقة، وتتيح لك نقطة النهاية تشغيل مزامنة عند انتهاء مهمة المستودع. قم بالتشغيل عند اكتمال المهمة حيثما أمكن، لأن الجدول الزمني الثابت قد يبدأ بينما لا يزال الجدول قيد التحميل.

استخدم تحويل البيانات عندما يمكن لمنصة طرف ثالث إرسال خطافات ويب ولا يمكنك تغيير الكود الخاص بها. يقوم هذا بتحويل حمولة خطاف الويب إلى طلبات واجهة برمجة تطبيقات Braze باستخدام JavaScript، وحد المعدل هو 1,000 طلب وارد في الدقيقة لكل مساحة عمل. تقوم عمليات الكتابة الخاصة بها بتسجيل نقاط البيانات تماماً كما يفعل طلب /users/track المباشر، لذا ضع ذلك في ميزانيتك.

دليلنا حول دمج بيانات نظام إدارة علاقات العملاء (CRM) في Braze يتعمق أكثر في كيفية اختيار الحقول المراد مزامنتها. يتم تناول تسمية الأحداث في تتبع أحداث المستخدم في Braze.

‍

متى يجب على الرسالة جلب البيانات أثناء عرضها؟

استخدم خاصية الجلب عند العرض فقط عندما تؤدي القيمة القديمة إلى جعل الرسالة غير صحيحة. تقوم ميزة "المحتوى المتصل" (Connected Content) باستدعاء نقطة النهاية الخاصة بك مع عرض كل رسالة، لذا فهي مناسبة للعروض والأرصدة والمخزون التي تتغير بين عمليات المزامنة. أما كل ما عدا ذلك، فمن الأوفر مزامنته مسبقاً.

توثق Braze أن "المحتوى المتصل" يدعم طلبات GET وPOST، بينما تدعم اللافتات (Banners) طلبات GET فقط. يتم تخزين طلبات GET مؤقتاً بشكل افتراضي، بينما لا يتم تخزين طلبات POST مؤقتاً إلا عند تحديد مدة صلاحية لذاكرة التخزين المؤقت. يمكن أن تتراوح مدة صلاحية التخزين المؤقت من خمس دقائق إلى أربع ساعات.

كلا هذين النموذجين مأخوذان مباشرة من وثائق Braze.

{% connected_content https://api.example.com/user :save user_data %} {% connected_content https://example.com/webservice.json :cache_max_age 900 %}

‍

تتحمل نقطة النهاية الخاصة بك العبء، وهذا هو الجزء الذي يجب التخطيط له. لا تفرض Braze حدًا منفصلاً لمعدل الاستخدام خاصًا بها على "المحتوى المتصل"، ويتم إرسال الرسائل بالتوازي عبر حملاتك وCanvas. قم بتهيئة نقطة النهاية لتناسب أكبر عملية إرسال لديك، وليس المتوسط.

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

‍

كيف يجب على Braze إرسال البيانات؟

استخدم خطافات الويب (webhooks) عندما يجب أن تؤدي خطوة الرسالة إلى إجراء في نظام آخر. تعيد Braze محاولة تسليم خطاف الويب فقط في حالات استجابة معينة، مثل 408 و429 و5XX. معظم الاستجابات الأخرى، بما في ذلك 401 Unauthorized، لا يتم إعادة محاولتها.

صمم نظامك مع مراعاة هذا التفصيل الأخير أولاً. عادةً ما تُرجع بيانات الاعتماد منتهية الصلاحية في الجانب المستقبِل رمز 401، لذا لا تتم إعادة محاولة خطافات الويب تلك. راقب معدل الخطأ في النظام المستقبِل، وليس فقط عدد عمليات الإرسال من Braze، وقم بتحديث بيانات الاعتماد قبل انتهاء صلاحيتها.

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

استخدم Currents عندما تحتاج إلى بيانات أحداث Braze في مستودع بيانات أو أداة تحليلية. توفر Currents البيانات مرة واحدة على الأقل، لذا قد تظهر نسخ مكررة أحياناً. قم بإزالة التكرار بناءً على حقل معرف الحدث (event id) الذي يأتي مع كل حدث، وقم بمعالجة الملفات فور وصولها بدلاً من إعادة فحص الأقسام القديمة.

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

‍

ماذا عن الكود الذي يعمل على شاشة المستخدم؟

يمكن لرسائل HTML المخصصة داخل التطبيق واللافتات التواصل مع حزمة تطوير البرمجيات (SDK) الخاصة بـ Braze من خلال جسر JavaScript. بهذه الطريقة، يقوم التصميم المخصص بإبلاغ Braze بما يفعله المستخدم. حصلت صفحات الهبوط أيضاً على جسر JavaScript، وهو متاح بشكل عام وفقاً لملاحظات إصدار 20 أغسطس 2026.

العقبة تكمن في تتبع النقرات. في HTML المخصص، لا يمكن لـ SDK إرفاق مستمعي النقرات بعناصرك تلقائياً، لذا يجب إجراء استدعاء النقرة الخاص بالجسر بشكل صريح. تعامل مع فقدان استدعاء النقرة كعائق يمنع الإصدار، لأنه بدونه ستكون تقارير النقرات لتلك الرسالة فارغة.

منشورنا حول إنشاء رسائل جذابة داخل التطبيق تتناول متى يستحق استخدام HTML المخصص عناء البناء الإضافي.

‍

ما هو الترتيب الذي يجب أن تتبعه لاختيار نقطة الربط؟

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

1. هل تبدأ البيانات بإجراء من المستخدم في تطبيقك؟ استخدم حزمة تطوير البرمجيات (SDK).
2. هل يحتفظ نظامك الخاص بالبيانات الأساسية ويقوم بتغييرها وفق جدول زمني خاص به؟ استخدم واجهة برمجة تطبيقات Braze بنظام الدفعات.
3. هل البيانات موجودة بالفعل في مستودع بيانات؟ استخدم ميزة استيعاب بيانات السحابة (Cloud Data Ingestion)، وقم بتفعيلها عند اكتمال التحميل.
4. هل يوفر الطرف الثالث خطافات الويب (webhooks) فقط؟ استخدم ميزة تحويل البيانات (Data Transformation).
5. هل ستؤدي قيمة تمت مزامنتها مسبقاً إلى جعل الرسالة غير صحيحة؟ استخدم المحتوى المتصل (Connected Content)، مع مراعاة حجم أكبر عملية إرسال لديك.
6. هل يجب أن تؤدي عملية الإرسال إلى إجراء في مكان آخر؟ استخدم خطاف ويب (webhook)، وراقب الطرف المستلم.
7. هل تحتاج إلى سجل الأحداث خارج Braze؟ استخدم Currents، وقم بإزالة التكرارات بناءً على معرف الحدث.

‍

دوّن الإجابة لكل عملية تكامل مع تحديد المسؤول عنها. هذه القائمة المكتوبة هي ما يتيح لأي شخص آخر استكشاف الأخطاء وإصلاحها لاحقاً.

‍

أين يرتبط هذا ببقية البرنامج؟

تعد البيانات في وقت العرض (Render-time data) أحد الأنماط في سبع طرق لتقديم محتوى ديناميكي. عمليات الإرسال التي يتم تفعيلها عبر واجهة برمجة التطبيقات والتي تنتهي بها العديد من عمليات التكامل مغطاة في أتمتة رسائل المعاملات الإلكترونية.

بصفتها شريكاً في تنفيذ Braze، توصي CustomerIK بتحديد الاتجاه ومدى حداثة البيانات لكل عملية تكامل قبل اختيار الأداة. فالأداة تُختار بناءً على هاتين الإجابتين، وكذلك معظم آليات معالجة الأخطاء.

‍

الأسئلة الشائعة
‍

1. هل تقوم ميزة تحويل البيانات (Data Transformation) بتسجيل نقاط البيانات؟

تؤكد Braze أنها تقوم بذلك في معظم الحالات. تنتهي كل عملية تحويل باستدعاء /users/track، مما يسجل نقاط البيانات كما لو كنت قد استدعيت نقطة النهاية مباشرة.

2. هل يمكن للمحتوى المتصل (Connected Content) إعادة محاولة استدعاء فاشل في رسالة داخل التطبيق؟

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

3. ما هي حالات فشل خطافات الويب (webhooks) التي تعيد Braze محاولتها؟

تقوم Braze بإعادة محاولة إرسال الطلبات فقط عند تلقي استجابات معينة، مثل 408 و429 و5XX. أما معظم الاستجابات الأخرى، بما في ذلك 401 غير مصرح به (Unauthorized)، فلا تتم إعادة محاولتها.

4. هل يمكن لـ Currents إرسال نفس الحدث مرتين؟

نعم، يحدث ذلك أحياناً. توفر Currents خاصية التسليم لمرة واحدة على الأقل، لذا يرجى إجراء إلغاء التكرار (deduplication) باستخدام حقل المعرف (id) المرسل مع كل حدث.

5. كم عدد الكائنات التي يمكن أن يحملها طلب /users/track واحد؟

ما يصل إلى 75 كائناً مجمعة عبر السمات والأحداث والمشتريات. يقوم كل كائن بتحديث مستخدم واحد.

‍

المصادر

• Braze،تحويل البيانات. تم الاسترجاع في 14 أكتوبر 2026.
• Braze،خطافات الويب (Webhooks). تم الاسترجاع في 14 أكتوبر 2026.
• Braze،دلالات تسليم أحداث Currents. تم الاسترجاع في 14 أكتوبر 2026.
• Braze،إجراء استدعاء للمحتوى المتصل (Connected Content). تم الاسترجاع في 14 أكتوبر 2026.
• Braze،التخزين المؤقت لاستجابات المحتوى المتصل (Connected Content). تم الاسترجاع في 14 أكتوبر 2026.
• Braze،محاولات إعادة الاتصال للمحتوى المرتبط. تم الاسترجاع في 14 أكتوبر 2026.
• Braze،الكود المخصص وجسر JavaScript للافتات. تم الاسترجاع في 14 أكتوبر 2026.
• Braze،حدود واجهة برمجة التطبيقات (API). تم الاسترجاع في 14 أكتوبر 2026.
• Braze،استيعاب البيانات السحابية. تم الاسترجاع في 14 أكتوبر 2026.
• Braze،ما الجديد في Braze. تم الاسترجاع في 14 أكتوبر 2026.

‍

CustomerIK هي شريك تنفيذ لـ Braze، وتعمل في مجالات الإعداد، والتكامل التقني، وعمليات التسويق، وإدارة بيانات العملاء.

إذا كنت تخطط لدمج Braze وترغب في تحديد نقاط الامتداد قبل البدء في عملية البناء، دعنا نتحدث.

‍