استخدام قوالب Liquid

توسع قوالب Liquid بشكل كبير من إمكانيات التخصيص في Pushwoosh من خلال تنفيذ منطق متطور بالإضافة إلى استخدام المحتوى الديناميكي العادي.

يعتمد تخصيص الرسائل في Pushwoosh على Tags (بيانات المستخدم). يقدم Pushwoosh مجموعة متنوعة من Tags الافتراضية وTags المخصصة. باستخدامها، يمكنك تحديد الاسم الأول للمستخدم، والمدينة، وسجل الشراء، وما إلى ذلك لإرسال رسالة أكثر تخصيصًا، على سبيل المثال: مرحبًا {First_name}، شكرًا لطلبك {item}.

تضيف قوالب Liquid المزيد من المنطق إلى المحتوى الديناميكي. على سبيل المثال، إذا كان Tag اشتراك المستخدم يحتوي على “free”، يمكنك إرسال رسالة لهم: “احصل على خصم 10%”.

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

الصيغة

تستخدم قوالب المحتوى المستندة إلى Liquid by Shopify مزيجًا من tags وobjects وfilters لتحميل المحتوى الديناميكي. تتيح لك قوالب المحتوى الوصول إلى متغيرات معينة من داخل القالب وإخراج بياناتها دون الحاجة إلى معرفة أي شيء عن البيانات نفسها.

ملاحظة

لمعرفة المزيد عن الصيغة، يرجى الرجوع إلى توثيق Liquid.

Objects

تحدد objects المحتوى الذي سيتم عرضه للمستخدم. يجب أن تكون objects محاطة بأقواس معقوفة مزدوجة: {{ }}

على سبيل المثال، عند تخصيص رسالة، أرسل {{Name}} في نصها لإضافة أسماء المستخدمين إلى محتوى الرسالة. سيحل اسم المستخدم (قيمة Name tag) محل كائن Liquid في الرسالة التي سيراها المستخدم.

الإدخال

مرحبًا {{Name}}! يسعدنا عودتك!

الإخراج

مرحبًا آنا! يسعدنا عودتك!

Tags

تنشئ tags المنطق وتدفق التحكم للقوالب. لا تنتج المحددات المئوية للأقواس المعقوفة {% و %} والنص الذي تحيط به أي إخراج مرئي عند عرض القالب. يتيح لك هذا تعيين متغيرات وإنشاء شروط أو حلقات دون إظهار أي من منطق Liquid للمستخدم.

على سبيل المثال، باستخدام if tag، يمكنك تغيير لغة الرسالة بناءً على اللغة المحددة على جهاز المستخدم:

الإدخال

{% if Language == 'fr' %}
Salut!
{% else %}
Hello!
{% endif %}

الإخراج (fr)

Salut!

الإخراج (es)

Hello!

عوامل تشغيل Tags

عامل التشغيل	الوصف
==	يساوي
!=	لا يساوي
>	أكبر من
<	أصغر من
>=	أكبر من أو يساوي
<=	أصغر من أو يساوي
or	أو المنطقية
and	و المنطقية
contains	يتحقق من وجود سلسلة فرعية داخل سلسلة نصية أو مصفوفة من السلاسل النصية

ملاحظة

في tags التي تحتوي على أكثر من عامل تشغيل and أو or، يتم فحص عوامل التشغيل بالترتيب من اليمين إلى اليسار. لا يمكنك تغيير ترتيب العمليات باستخدام الأقواس — الأقواس هي أحرف غير صالحة في Liquid وستمنع tags الخاصة بك من العمل.

Filters

تعدل filters إخراج كائن أو متغير Liquid. يتم استخدامها داخل الأقواس المعقوفة المزدوجة {{ }} وتعيين المتغيرات، ويتم فصلها بحرف الأنبوب |. يمكن استخدام فلاتر متعددة على إخراج واحد، ويتم تطبيقها من اليسار إلى اليمين.

الإدخال

{{ Name | capitalize | prepend:"Hello " }}

الإخراج

Hello Anna

استخدام قوالب Liquid في الرسائل المرسلة عبر API

استخدم صيغة Liquid في طلبات createMessage لتنفيذ قوالب Liquid. تتوفر القوالب لمعلمة “content” في طلب createMessage، بالإضافة إلى أي معلمة أخرى تدعم المحتوى الديناميكي، على وجه الخصوص، معلمات “title” و “subtitle” و “image” الخاصة بالمنصة.

باستخدام قوالب المحتوى، يمكنك إما تحديد البيانات في طلبات API الخاصة بك (بتمرير معلمة “template_bindings”) أو الحصول على البيانات من قيم Tag المخزنة على أجهزة المستخدمين (بعدم استخدام معلمة “template_bindings”). بهذه الطريقة، يمكنك بناء حملات إشعارات تستند إلى المستخدم تحتوي على محتوى وثيق الصلة للغاية.

ملاحظة

يرجى ملاحظة أنه على عكس المحتوى الديناميكي، يجب أن تكون المتغيرات في القوالب محاطة بأقواس معقوفة مزدوجة على النحو التالي: {{myVariable}}.

لتعريف منطق القالب باستخدام Tags التي تحتوي على مسافات في أسمائها، استخدم التقنية التالية:

مثال

{% capture my_tag %}{{My Tag}}{% endcapture %}
{% if my_tag == 'value' %}
المحتوى الذي سيتم إرساله في هذه الحالة
{% else %}
المحتوى الذي سيتم إرساله في حالة أخرى
{% endif %}

حالات استخدام قوالب Liquid

ستجد هنا العديد من حالات الاستخدام التي تكون فيها قوالب Liquid مفيدة.

إشعارات متعددة اللغات

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

إدخال Liquid

{% if Language == 'es' %}
¡Hola!
{% else %}
Hello!
{% endif %}

طلب API

{
  "request": {
    "application": "XXXXX-XXXXX", // رمز تطبيق Pushwoosh
    "auth": "yxoPUlw.....IyEX4H", // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "notifications" : [ // معلمات رسالة الإشعار
      {
       "content": "{% raw %}
{% if language == 'es' %}¡Hola!{% else %}hello!{% endif %}
{% endraw %}",
        "template_bindings": { // اختياري. عند عدم تمرير template_bindings في الطلب، يتم استخدام قيم Tag من الجهاز.
         "language" : "es"
        }
      }
    ]
  }
}

الإخراج

إذا كانت اللغة ‘es’: ¡Hola!

إذا كانت اللغة ‘en’: Hello!

طلب ترقية الاشتراك

شجع عملائك على ترقية اشتراكهم بناءً على خطتهم الحالية.

إدخال Liquid

{% if Subscription == 'Basic' %}
    قم بالترقية إلى الخطة الفضية للحصول على المزيد من ميزات المنتج ودعم على مدار الساعة طوال أيام الأسبوع.
{% elsif Subscription == 'Silver' %}
    قم بالترقية إلى الخطة الذهبية للحصول على دعم ذي أولوية وميزات متقدمة.
{% else %}
    يرجى الاتصال بمديرك لتجديد اشتراكك.
{% endif %}

طلب API

{
  "request": {
    "application": "XXXXX-XXXXX", // رمز تطبيق Pushwoosh
    "auth": "yxoPUlw.....IyEX4H", // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "notifications" : [ // معلمات رسالة الإشعار
      {
       "content": "{% raw %}
{% if Subscription == 'Basic' %}Upgrade to Silver for getting more product features and 24/7 support.{% elsif Subscription == 'Silver' %}Upgrade to Gold for priority support and advanced features.{% else %}Please contact your manager to renew your subscription. {% endif %}
{% endraw %}",
        "template_bindings": { // اختياري. عند عدم تمرير template_bindings في الطلب، يتم استخدام قيم Tag من الجهاز.
         "language" : "es"
        }
      }
    ]
  }
}

الإخراج

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

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

للمستخدمين الذين لديهم خطط أخرى: يرجى الاتصال بمديرك لتجديد اشتراكك.

Tags من نوع قائمة

تعتبر قوالب المحتوى مفيدة جدًا للتعامل مع Tags من نوع القائمة.

حجم متغير

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

إدخال Liquid

{% if WishList.size >= 3 %}
احصل على خصم 20% على عملية الشراء التالية!
{% elsif WishList.size == 2 %}
احصل على خصم 10% على عملية الشراء التالية!
{% else %}
مرحبًا، ألق نظرة على الملابس الخارجية الجديدة!
{% endif %}

طلب API

{
  "request": {
    "application": "XXXXX-XXXXX", // رمز تطبيق Pushwoosh
    "auth": "yxoPUlw.....IyEX4H", // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "notifications" : [ // معلمات رسالة الإشعار
      {
       "content": "{% raw %}
{% if WishList.size >= 3 %}Get 20% off your next purchase!{% elsif WishList.size == 2 %}Get a 10% discount on your next purchase!{% else %}Hey, take a look at new outwears!{% endif %}
{% endraw %}",
        "template_bindings": {
         "WishList" : ["Skinny Low Ankle Jeans", "Linen Trenchcoat", "High Waisted Denim Skirt", "Strappy Tiered Maxi Dress"]
        }
      }
    ]
  }
}

حجم قائمة الأمنيات ≥ 3

حجم قائمة الأمنيات = 2

المتغير يحتوي على

حالة أخرى قد تحتاج إلى تغطيتها هي التعامل مع قيم List Tags وتقديم المحتوى الأكثر صلة بناءً على القيم التي يحتوي عليها Tag.

إدخال Liquid

{% if WishList contains 'Skinny Low Ankle Jeans' %}
احصل على خصم 20% على المنتجات في قائمة أمنياتك!
{% else %}
مرحبًا، ألق نظرة على بنطال Skinny Low Ankle Jeans الجديد كليًا!
{% endif %}

طلب API

{
  "request": {
    "application": "C90C0-0E786",
    "auth": "yxoPUlw.....IyEX4H", // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "notifications" : [ // معلمات رسالة الإشعار
      {
       "content": "{% raw %}
{% if WishList contains 'Skinny Low Ankle Jeans' %}Get 20% off your next purchase!{% else %}Hey, take a look at the brand new Skinny Low Ankle Jeans!{% endif %}
{% endraw %}",
        "template_bindings": {
         "WishList" : ["Skinny Low Ankle Jeans", "Linen Trenchcoat", "High Waisted Denim Skirt", "Strappy Tiered Maxi Dress"]
        }
      }
    ]
  }
}

المتغير يحتوي على بيانات

المتغير لا يحتوي على بيانات

صيغ الجمع

باستخدام قوالب المحتوى، يمكنك تعديل محتوى الرسالة وفقًا لسلوك المستخدمين. على سبيل المثال، يمكنك تعديل نص الرسالة ليحتوي على كلمات بصيغة الجمع في حال كان List Tag يحتوي على أكثر من قيمة واحدة.

إدخال Liquid

    احصل على خصم 20% على العنصر
{% if WishList.size > 1 %}
    ات في قائمة أمنياتك!
{% else %}
     في قائمة أمنياتك!
{% endif %}

طلب API

{
  "request": {
    "application": "C90C0-0E786",
    "auth": "yxoPUlw.....IyEX4H", // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "notifications" : [ // معلمات رسالة الإشعار
      {
       "content": "Get 20% off item{% raw %}
{% if WishList.size > 1 %}s in your WishList!{% else %} in your Wishlist!{% endif %}
{% endraw %}",
        "template_bindings": { // اختياري. عند عدم تمرير template_bindings في الطلب، يتم استخدام قيم Tag من الجهاز.
         "WishList" : ["Skinny Low Ankle Jeans", "Linen Trenchcoat", "High Waisted Denim Skirt", "Strappy Tiered Maxi Dress"]
        }
      }
    ]
  }
}

صيغة الجمع

صيغة المفرد

المنطقة الزمنية

يقوم قالب المناطق الزمنية بتحويل التاريخ والوقت وفقًا للمنطقة الزمنية المحددة.

إدخال Liquid

{{ MyDate | timezone: MyTimezone | date: \"%Y-%m-%d %H:%M\" }}

طلب API

مثال

{
  "request" : {
    "auth" : "3H9bk8w3.....Acge2RbupTB", // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "application" : "XXXXX-XXXXX", // رمز تطبيق Pushwoosh
    "notifications" : [ // معلمات رسالة الإشعار
      {
        "content": "Current Date: {{ MyDate | timezone: MyTimezone | date: \"%Y-%m-%d %H:%M\" }}",
        "template_bindings": { // اختياري. عند عدم تمرير template_bindings في الطلب، يتم استخدام قيم Tag من الجهاز.
         "MyDate" : "2019-07-23 15:00",
         "MyTimezone" : "Asia/Dubai"
        }
      }
    ]
  }
}

الإخراج

المحتوى المتصل (Connected content)

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

حالات الاستخدام الرئيسية

• توصيات المنتجات: عرض قوائم منتجات مخصصة مصممة لكل مستخدم.

• رموز الترويج: إدراج رموز ترويجية فريدة تم إنشاؤها بواسطة خدمة خلفية.

المتطلبات الأساسية

• لاستخدام المحتوى المتصل، يجب أن يكون لديك خدمة خلفية خاصة بك تقوم بإنشاء وتوفير البيانات المطلوبة (مثل رموز الترويج، توصيات المنتجات) بناءً على User ID أو HWID أو custom tags. يقوم Pushwoosh بعد ذلك بجلب هذه البيانات قبل إرسال الرسالة.

دليل التنفيذ خطوة بخطوة

الخطوة 1. إعداد الخدمة الخلفية

يجب أن تقوم الخدمة الخلفية بما يلي:

• قبول طلب يحتوي على معلمات خاصة بالمستخدم (مثل userId). يدعم المحتوى المتصل UserID أو HWID أو أي custom tags قمت بإعدادها في مشروعك.
• إرجاع استجابة JSON بالبيانات المطلوبة. يمكن بعد ذلك إدراج هذا المحتوى ديناميكيًا في الرسائل.

كيف يعمل

تعمل الخدمة الخلفية كمزود بيانات، حيث تستجيب لطلبات HTTP بمعلومات خاصة بالمستخدم.

1. يرسل Pushwoosh طلبًا إلى الواجهة الخلفية الخاصة بك، ويمرر معرفات خاصة بالمستخدم كمعلمات استعلام.
2. تعالج الواجهة الخلفية الخاصة بك الطلب وتسترد البيانات المطلوبة.
3. تعيد الواجهة الخلفية الخاصة بك استجابة JSON.
4. قبل إرسال رسالة، يجلب Pushwoosh استجابة JSON من خدمة الواجهة الخلفية ويستخدم القيم المرتجعة (على سبيل المثال، code) في محتوى الرسالة ديناميكيًا.

مثال على الاستجابة

{ "code": "SPECIALOFFERFORUSER12345" }

الخطوة 2. إنشاء إعداد مسبق (Preset) مع محتوى متصل في Pushwoosh

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

مثال

{% connected_content http://your-backend-url.com?userId={{ ${userid} }} :save result %}

تفصيل الصيغة

connected_content	يجلب بيانات JSON من عنوان URL الخلفي المحدد.
http://your-backend-url.com	نقطة النهاية الخلفية التي تعيد البيانات المطلوبة بتنسيق JSON.
userId={{ ${userid} }}	معلمة استعلام ديناميكية تمرر معرف المستخدم إلى الواجهة الخلفية.
:save result	يخزن استجابة JSON التي تم جلبها في متغير result لاستخدامه في قوالب Liquid.

المصادقة (اختياري)

إذا كانت خدمة الواجهة الخلفية الخاصة بك تتطلب مصادقة، يمكنك تضمين مفتاح API أو رمز مميز في طلب المحتوى المتصل لضمان الوصول الآمن.

{% connected_content http://your-backend-url.com?userId={{ ${userid} }}&auth=YOUR_API_KEY :save result %}

يمكنك أيضًا إرسال بيانات المصادقة (أو أي بيانات أخرى) كرؤوس HTTP باستخدام المعلمة الاختيارية :headers — وهي كائن JSON لأسماء وقيم الرؤوس.

{% connected_content http://your-backend-url.com?userId={{ ${userid} }} :headers {"Authorization": "Bearer YOUR_TOKEN", "X-Api-Key": "YOUR_API_KEY"} :save result %}

:headers {...}	كائن JSON لرؤوس HTTP المرسلة مع الطلب، على سبيل المثال Authorization: Bearer <token>.

قيم ثابتة فقط

تعمل متغيرات التخصيص ${} فقط داخل عنوان URL. القيم داخل :headers ثابتة ولا يتم استيفاؤها.

استخدام tags في المحتوى المتصل

لتضمين custom tags، أدخلها كمعلمات استعلام في طلب المحتوى المتصل ({{ tag_name }}).

{% connected_content http://your-backend-url.com?userId={{ ${userid} }}{{ Language }} :save result %}

2. بعد ذلك، أضف نص الرسالة الذي يتضمن البيانات المستردة، مثل هذا:

مرحبًا، {{userid}}، احصل على رمز الترويج الشخصي الخاص بك - {{result.code}}

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

الخطوة 3. إرسال رسالة باستخدام الإعداد المسبق الذي تم تكوينه

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

هام

إذا أعادت الخدمة حالة غير HTTP 200 OK، فلن يتم إرسال البريد الإلكتروني أو الإشعار. هذا يضمن أن اتصالك يخرج فقط إذا تم استرداد البيانات اللازمة بنجاح.