.svg)
نادراً ما تتعطل تخصيصات Liquid في Braze داخل الرسالة الواحدة، لكنها تتعطل عندما يعيد عدة أشخاص استخدام مقتطف برمجي واحد عبر سطور الموضوع، وكتل المحتوى (Content Blocks)، وخطوات Canvas. اكتب كود Liquid لكل حقل على حدة، وأعد استخدام الكتل عبر الوسوم (tags) بدلاً من سحبها وإفلاتها. اتفقوا على قواعد داخلية لاستخدام علامات الاقتباس، والمسافات، وأنواع البيانات، واحرصوا على أن تظل حمولات المشغلات (trigger payloads) صغيرة الحجم.
أبرز النقاط
- يقوم Braze بمعالجة كل مكون من مكونات الرسالة بشكل منفصل، لذا كرر كود Liquid في كل حقل يحتاج إلى قيمة.
- تظل كتل المحتوى (Content Blocks) المدرجة عبر Liquid مرتبطة بالكتلة المصدر، بينما تصبح الكتل التي يتم سحبها وإفلاتها منفصلة وتحتفظ بالنسخة القديمة.
- يتعرف Liquid فقط على الرموز العادية، لذا قم بإيقاف ميزة علامات الاقتباس والشرطات الذكية على كل جهاز يُستخدم لتحرير Braze.
- استخدم الشرطات داخل محددات الوسوم، أو الشروط ذات السطر الواحد، لمنع Liquid من إضافة أسطر فارغة.
- حافظ على حجم حمولات سياق Canvas (context payloads) أقل من 1 كيلوبايت تقريباً، وأرسل المعرفات بدلاً من الكائنات الكاملة.
- حدد نوع كل حقل والقيمة الاحتياطية له قبل كتابة أي نص مخصص.
ما الذي يتغير عندما تعمل تخصيصات Liquid في Braze عبر رسائل متعددة؟
من السهل ضبط رسالة واحدة تحتوي على اسم أول وقيمة افتراضية. تبدأ الصعوبة عندما يتم استخدام المنطق نفسه في حملات متعددة، وكتل محتوى متنوعة، وCanvas يقوم بتحريره أكثر من شخص. عند هذه النقطة، يصبح المقتطف المشترك هو مصدر الخطأ، وسيتكرر أي خطأ فيه في كل مكان يُستخدم فيه.
يوصي Braze بأن تقوم بـ اختبار جميع الرسائل التي تستخدم Liquid قبل الإرسال، لتقليل مخاطر حدوث أخطاء أو استخدام كود Liquid غير مدعوم. اعتبر هذا هو الحد الأدنى. تحتاج مكتبة القوالب إلى قواعد تمنع تكرار الخطأ نفسه، لأن الاختبار لا يكتشف الخطأ إلا بعد وجوده بالفعل.
التكرار هو التكلفة الرئيسية التي يجب إدارتها هنا. تجيب الأسئلة الشائعة حول Liquid في Braze بـ "لا" على سؤال ما إذا كان استخدام Liquid يسجل نقاط بيانات، لذا فإن تكرار الوسم يستهلك جهداً في الصيانة بدلاً من استهلاك نقاط البيانات. بقية هذا المنشور تدور حول كيفية تقليل هذا الجهد.
لماذا يختفي متغير من سطر الموضوع عند ظهوره في متن الرسالة؟
يعالج Braze كل مكون من مكونات الرسالة بشكل منفصل، بما في ذلك سطر الموضوع، ومتن HTML، والنص التمهيدي (preheader)، وعنوان إشعار الدفع. أي تعيين (assign) أو التقاط (capture) يتم في حقل واحد لا يكون متاحاً في حقل آخر. الحل الذي يقدمه Braze هو تكرار كود Liquid أو استدعاء Connected Content في كل حقل يحتاج إلى تلك القيمة.
ابنِ على هذا الأساس بدلاً من مقاومته. امنح كل حقل يستخدم بيانات شخصية ترويسة قصيرة خاصة به من وسوم التعيين (assign tags) في الأعلى. استخدم الترتيب نفسه وأسماء المتغيرات نفسها في كل منها. عندها، سيرى أي شخص يقرأ سطر الموضوع أو النص التمهيدي بالضبط ما يعتمد عليه ذلك الحقل.
من السهل تفويت الخطأ الذي يمنعه هذا الإجراء أثناء المراجعة. فالمتن الذي يعمل بشكل صحيح وسطر الموضوع الذي يعرض تحية فارغة يبدوان جيدين في أداة الإنشاء إذا قمت بمعاينة المتن فقط. قم بمعاينة كل حقل لمستخدم الاختبار نفسه قبل التحقق من أي شيء آخر.
استخدم assign لقيمة واحدة مع فلتر واحد كحد أقصى، وهو ما يوصي به Braze. استخدم capture لأي نص يتكون من أكثر من قيمة، مثل رابط يحتوي على معاملات أو متن استدعاء Connected Content. هذا التقسيم هو توجيه Braze، ونوصي باعتباره قاعدة مراجعة حتى يعرف المراجعون ما يمكن توقعه.
كيف يجب عليك إعادة استخدام Liquid من خلال كتل المحتوى (Content Blocks)؟
كتل المحتوى هي الطريقة التي يتم بها إعادة استخدام Liquid عبر رسائل متعددة، ومنشورنا حول سبع طرق لتقديم محتوى ديناميكي تتناول الأسباب التي تجعلها مهمة. هناك تفصيل واحد يحدد ما إذا كان التعديل اللاحق سيصل إلى كل رسالة تستخدم الكتلة البرمجية.
توثق Braze أن كتل المحتوى (Content Blocks) التي يتم إدراجها عبر Liquid تظل مرتبطة بالكتلة الأصلية وتعكس أي تغييرات لاحقة. أما سحب كتلة إلى رسالة باستخدام محرر السحب والإفلات فيحافظ على تخطيطها ولكنه يفك ارتباطها، مما يعني أن التعديلات المستقبلية لن تصل إلى تلك الرسالة. تكمن المقايضة في المعاينة، حيث قد لا يتم تطبيق استعلامات وسائط الجوال في الكتلة الموسومة بنفس الطريقة.
نطلق على الانحراف الذي يسببه هذا اسم "مشكلة اللقطة" (snapshot problem). فعندما يقوم فريق بإصلاح خطأ في كتلة ما، تتلقى جميع الرسائل الموسومة التحديث، بينما تحتفظ النسخ المسحوبة بالإصدار القديم. لذا، قم بإدراج الكتل المشتركة عن طريق الوسم، ولا تستخدم السحب إلا عندما تحتاج الرسالة فعلياً إلى نسخة ثابتة، واحتفظ بسجل للرسائل التي تحتوي على لقطات.
تعد المسافات فخاً آخر من فخاخ إعادة الاستخدام. تتبع Braze المسافات الإضافية في كتل المحتوى التي تحتوي على Liquid إلى فواصل الأسطر داخل العبارات الشرطية، وتنصح بكتابة تلك العبارات في سطر واحد. وفي محررات السحب والإفلات، يتمثل الحل الموصى به لـ Liquid متعدد الأسطر في استخدام الواصلات داخل محددات الوسم، حيث تعمل على إزالة المسافات البيضاء المحيطة والحفاظ على قابلية قراءة الكود.
ما هي القواعد الداخلية التي تمنع تعطل Liquid داخل الفريق؟
تجيب كل قاعدة أدناه على سبب موثق للفشل. العمود الأيمن هو طريقتنا الموصى بها لإلزام الفريق بها، وهو الجزء الذي تضيفه مكتبة القوالب.
القاعدةالسبب الموثقكيفية فرضهاعلامات الاقتباس المستقيمة فقطلا يتعرف Liquid إلا على الأحرف المستقيمة، لذا تسبب علامات الاقتباس والشرطات الذكية أخطاء في التحليل، وغالباً ما يكون ذلك بسبب إعداد macOS "استخدام علامات الاقتباس والشرطات الذكية"قم بإيقاف تشغيل هذا الإعداد على كل جهاز يقوم بتحرير Braze، كخطوة ضمن إجراءات التهيئة للعملالتحكم في المسافات البيضاء افتراضياًيؤدي استخدام Liquid متعدد الأسطر في محررات السحب والإفلات إلى تحويل فواصل الأسطر إلى أسطر فارغة قبل المخرجات المرئيةاكتب محددات الوسم مع واصلات في المقتطفات المشتركة منذ البدايةفرض الأنواع عند التعيينتحتاج بعض أنواع خصائص سياق Canvas إلى فرض النوع قبل المقارنات أو العمليات الحسابيةاستخدم plus: 0 في سطر التعيين، وليس في المقارنة أبداًلا تقارن الوقت بالفراغلا يمكن لـ Liquid مقارنة كائن وقت بسلسلة نصيةقم بتعيين سمة الوقت مع قيمة افتراضية عبارة عن سلسلة نصية فارغة، ثم قارن المتغيرقوسان، بدون تداخلتتسبب الأقواس المتعرجة الإضافية أو المفقودة في ظهور خطأ "رمز نهاية غير متوقع" وتعطل Liquid الذي يتم تشغيله عبر APIابحث في كل مقتطف عن أقواس ثلاثية قبل المراجعةأسباب الإلغاء هي نصوص ثابتةيأخذ وسم abort_message سلسلة نصية ثابتة، وليس Liquidضع المنطق قبل الوسم وحافظ على وضوح السبب في التقارير
تأتي علامات الاقتباس الذكية في المرتبة الأولى لأنها تنتج عن إعدادات الكمبيوتر المحمول، لذا لا توجد معرفة بـ Liquid يمكنها الحماية منها.
تستحق القيم الافتراضية سطراً إضافياً. توثق Braze أن القيمة الافتراضية تظهر للقيم الفارغة ولكن ليس للقيم الخالية (blank). فالحقل الذي يحتوي على مسافة فقط يتجاوز هذا الإجراء. يجب معاينة أي مقتطف مشترك يدرج نصاً مكتوباً من ملف تعريف المستخدم باستخدام قيمة تحتوي على مسافات بيضاء فقط.
ما هو الحجم المناسب لبيانات سياق Canvas وبيانات المشغلات؟
لا تضع Braze حداً صارماً لخصائص سياق Canvas، لكنها تنصح بإبقاء أحجام البيانات (payloads) أقل من 1 كيلوبايت تقريباً، أي حوالي 1000 حرف. يمكن للكائنات الأكبر حجماً أن تزيد من استهلاك الذاكرة وتؤخر عرض الرسائل أثناء عمليات الإرسال ذات الحجم الكبير.
أرسل المعرفات والحقول القليلة التي تقرأها الرسالة، وليس الكائنات بأكملها. إذا كان القالب يحتاج إلى عنوان المنتج وسعره، فيتم إرسال هاتين القيمتين فقط، ويظل أي شيء آخر في الكتالوج. هذا يحافظ على صغر حجم البيانات ويجعل احتياجات القالب من البيانات مرئية في مكان واحد.
هناك حدان هيكليان يؤثران على حجم البيانات أيضاً. لا يتعامل Liquid أصلاً مع مصفوفات المصفوفات، لذا تنصح Braze بتخزين القيم كسلاسل نصية مفصولة بفواصل وتحليلها باستخدام مرشح split. بالنسبة للخصائص التي يتم تشغيلها عبر API، استخدم قوسين للفتح وقوسين للإغلاق بالضبط، حيث أن وجود زوج إضافي هو سبب شائع للفشل.
تعتمد الكثير من بيانات الأحداث على هذا، لذا فإن الانضباط في التسمية في منشورنا حول تتبع أحداث المستخدم في Braze مهم هنا. فالخاصية التي تصل باسم ونوع يمكن التنبؤ بهما تحتاج إلى كود Liquid أقل دفاعية.
ما هو الترتيب الذي يجب أن تتبعه لبناء قالب Liquid مشترك؟
ابنِ القالب بهذا الترتيب، لأن كل خطوة تزيل فئة من الأخطاء قبل أن تتمكن الخطوة التالية من إخفائها.
- ادرج كل حقل تعرضه الرسالة، وبيانات الملف الشخصي أو الحدث أو السياق التي يقرأها كل حقل.
- حدد نوع كل قيمة والقيمة الاحتياطية عند فراغها، بما في ذلك النصوص التي تحتوي على مسافات بيضاء فقط.
- اكتب ترويسة التعيين (assign header) لكل حقل، مع القيم الافتراضية وفرض النوع في سطر التعيين.
- اكتب الشروط في سطر واحد أو باستخدام فواصل واصلة.
- أدرج الكتل المشتركة باستخدام وسم "كتلة المحتوى" (Content Block)، ودوّن أي رسالة تحتوي على نسخة مسحوبة.
- استخدم "معاينة كمستخدم مخصص" (Preview as Custom User) وأدخل قيم خصائص الحدث النموذجية لكل حالة.
- عاين سطر الموضوع، والنص التمهيدي، والمتن لنفس المستخدم قبل إجراء أي إرسال تجريبي.
الخطوة الثانية هي حيث تنتمي معظم القرارات. القالب الذي يعرف وظيفة كل حقل عند فقدان البيانات أسهل بكثير في المشاركة من القالب الذي يتعامل مع القيم الاحتياطية كإضافة تجميلية.
كيف يبدو ترويسة الحقل من الناحية العملية؟
هذا نموذج افتراضي لبريد إلكتروني لتحديث الطلب، وليس عملاً خاصاً بعميل. تستخدم لغة Liquid النماذج الموضحة فقط في وثائق Braze، وتحتاج إلى معاينة لكل حالة قبل الاستخدام.
يحتوي حقل سطر الموضوع على ترويسة خاصة به.
{%- assign first = {{${first_name}}} | default: 'there' -%}
{{ first }}، طلبك في الطريق إليك
يكرر حقل المتن الترويسة ويضيف ما يحتاجه المتن فقط.
{%- assign first = {{${first_name}}} | default: 'there' -%}
{%- assign item_count = {{custom_attribute.${open_order_items}}} | plus: 0 -%}
{% capture order_line %}{{ item_count }} items from order {{custom_attribute.${order_id}}}{% endcapture %}
مرحباً {{ first }}، تم شحن {{ order_line }}.
تكرار السطر الأول مقصود. يتم عرض الحقلين بشكل منفصل، لذا فإن التكرار هو السلوك الموثق وليس مجرد سهو. يتم تناول عمليات الإرسال المتعلقة بالمعاملات مثل هذه في دليلنا حول أتمتة رسائل المعاملات الإلكترونية.
أين تقع لغة Liquid ضمن البرنامج الأوسع؟
تعد Liquid طبقة واحدة من طبقات التخصيص. دليلنا حول التخصيص الفائق في Braze يغطي تصميم البيانات والرحلة المحيطة بها. معالجة اللغة موجودة في تدويل حملات Braze، وتخطيط الرسائل داخل التطبيق موجود في إنشاء رسائل جذابة داخل التطبيق.
بصفتنا شريكاً في تنفيذ Braze، توصي CustomerIK بكتابة القيمة الاحتياطية وترويسة الحقل قبل أي نص مخصص. القالب الذي يقرأ بشكل جيد حتى مع فقدان البيانات هو القالب الذي ينجح عند إعادة استخدامه.
الأسئلة الشائعة
1. هل تنتقل متغيرات Liquid من سطر الموضوع إلى المتن؟
لا يحدث ذلك. يقوم Braze بمعالجة كل مكون على حدة، لذا فإن التعيين أو الالتقاط في حقل واحد لا يكون متاحاً في حقل آخر. كرر كود Liquid في كل حقل يحتاج إلى القيمة.
2. لماذا لا تظهر تعديلات "كتلة المحتوى" (Content Block) في بعض الرسائل؟
تحتفظ الكتلة التي يتم سحبها إلى رسالة السحب والإفلات بتخطيطها ولكنها تصبح منفصلة عن الكتلة المصدر. أما الكتل التي يتم إدراجها عبر Liquid فتبقى مرتبطة وتعكس التغييرات اللاحقة، لذا استخدم هذا الوسم عندما ترغب في أن تصل التعديلات إلى الرسالة.
3. لماذا يفشل كود Liquid الذي يبدو صحيحاً في المعالجة؟
تعد علامات الاقتباس والشرطات الذكية سبباً شائعاً لذلك، لأن Liquid لا يتعرف إلا على الأحرف المستقيمة. يقوم إعداد macOS المسمى "استخدام علامات الاقتباس والشرطات الذكية" (Use smart quotes and dashes) بتحويلها تلقائياً أثناء الكتابة في لوحة التحكم.
4. كيف يمكنني إزالة الأسطر الفارغة الإضافية الناتجة عن Liquid في محرر السحب والإفلات؟
أضف واصلات داخل محددات الوسم لإزالة المسافات البيضاء المحيطة، أو ضع كود Liquid في سطر واحد. ينطبق كلا النهجين على محرري البريد الإلكتروني والرسائل داخل التطبيق، وكذلك على كتل المحتوى.
5. ما هو الحجم الأقصى لخصائص سياق Canvas؟
لا يضع Braze حداً صارماً، لكنه ينصح بإبقاء الحمولات أقل من 1 كيلوبايت تقريباً، أي حوالي 1000 حرف. يمكن أن تؤدي الكائنات الأكبر حجماً إلى زيادة استهلاك الذاكرة وإبطاء المعالجة أثناء عمليات الإرسال ذات الحجم الكبير.
المصادر
- Braze،الأسئلة الشائعة حول Liquid. تم الاسترجاع في 14 أكتوبر 2026.
- Braze،تعيين القيم الافتراضية. تم الاسترجاع في 14 أكتوبر 2026.
- Braze،كتل المحتوى. تم الاسترجاع في 14 أكتوبر 2026.
- Braze،إلغاء الرسائل. تم الاسترجاع في 14 أكتوبر 2026.
- Braze،ما الجديد في Braze، تم التحقق من تغييرات Liquid. تم الاسترجاع في 14 أكتوبر 2026.
CustomerIK هي شريك تنفيذ لـ Braze، وتعمل في مجالات الإعداد، والتكامل التقني، وعمليات التسويق، وإدارة بيانات العملاء.
إذا كنت تعمل على بناء مكتبة Liquid مشتركة وترغب في الحصول على مراجعة إضافية لها، فلنتحدث.
.svg)
