# قوالب Liquid

<YouTube id="A7l1_gK5yOA" playlabel="فيديو يوتيوب: تعلم كيفية استخدام قوالب المحتوى في رحلات العملاء"/>

توسع قوالب Liquid بشكل كبير من إمكانيات التخصيص في Pushwoosh من خلال تطبيق منطق متطور بالإضافة إلى الاستخدام المنتظم لـ[المحتوى الديناميكي](/ar/product/personalization/dynamic-content/).

يعتمد تخصيص الرسائل في Pushwoosh على [Tags (بيانات المستخدم)](/ar/product/audience-data-and-segmentation/user-data-tags/tags). يقدم Pushwoosh مجموعة متنوعة من [Tags الافتراضية](/ar/product/audience-data-and-segmentation/user-data-tags/tags#default-tags) و[Tags المخصصة](/ar/product/audience-data-and-segmentation/user-data-tags/tags#custom-tags). باستخدامها، يمكنك تحديد الاسم الأول للمستخدم، والمدينة، وسجل الشراء، وما إلى ذلك لإرسال رسالة أكثر تخصيصًا. على سبيل المثال: `مرحباً {{First_name}}، شكراً لطلبك {{item}}`.

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

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

## الصيغة

تستخدم قوالب المحتوى المستندة إلى [Liquid by Shopify](https://shopify.github.io/liquid/) مزيجًا من [**tags**](#tags) و[**objects**](#objects) و[**filters**](#undefined) لتحميل المحتوى الديناميكي. تسمح لك قوالب المحتوى بالوصول إلى متغيرات معينة من داخل القالب وإخراج بياناتها دون الحاجة إلى معرفة أي شيء عن البيانات نفسها.

<Aside type="note">
لمعرفة المزيد عن الصيغة، يرجى الرجوع إلى [توثيق Liquid](https://shopify.github.io/liquid/basics/introduction/).
</Aside>

### Objects

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

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

<Tabs>
<TabItem label="الإدخال">
```
Hi {{Name}}! We're glad you're back!
```
</TabItem>

<TabItem label="الإخراج">
Hi Anna! We're glad you're back!
</TabItem>
</Tabs>

### Tags

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

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

<Tabs>
  <TabItem label="الإدخال">

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

  </TabItem>

  <TabItem label="الإخراج (fr)">
    Salut!
  </TabItem>

  <TabItem label="الإخراج (es)">
    Hello!
  </TabItem>
</Tabs>


### عوامل تشغيل Tags

<table data-header-hidden><thead><tr><th width="189.5" align="center">العامل</th><th>الوصف</th></tr></thead><tbody><tr><td align="center"><code>==</code></td><td>يساوي</td></tr><tr><td align="center"><code>!=</code></td><td>لا يساوي</td></tr><tr><td align="center"><code>></code></td><td>أكبر من</td></tr><tr><td align="center"><code>&#x3C;</code></td><td>أصغر من</td></tr><tr><td align="center"><code>>=</code></td><td>أكبر من أو يساوي</td></tr><tr><td align="center"><code>&#x3C;=</code></td><td>أصغر من أو يساوي</td></tr><tr><td align="center"><code>or</code></td><td>أو المنطقية</td></tr><tr><td align="center"><code>and</code></td><td>و المنطقية</td></tr><tr><td align="center"><code>contains</code></td><td>يتحقق من وجود سلسلة فرعية داخل سلسلة نصية أو مصفوفة من السلاسل النصية</td></tr></tbody></table>

<Aside type="note">
في tags التي تحتوي على أكثر من عامل `and` أو `or`، يتم فحص العوامل بالترتيب _من اليمين إلى اليسار_. لا يمكنك تغيير ترتيب العمليات باستخدام الأقواس — الأقواس هي أحرف غير صالحة في Liquid وستمنع tags الخاصة بك من العمل.
</Aside>

### Filters

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

<Tabs>
<TabItem label="الإدخال">

```

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

```

</TabItem>

<TabItem label="الإخراج">

Hello Anna

</TabItem>
</Tabs>



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

تتوفر قوالب Liquid لكل من الرسائل المرسلة من لوحة التحكم (Control Panel) و[طلبات API](/ar/developer/guides/personalization/liquid-templates#using-liquid-templates-in-messages-sent-via-api).

في Pushwoosh، تنطبق قوالب Liquid على جميع حقول المحتوى لأي رسالة قناة:

*   إشعارات Push
*   رسائل البريد الإلكتروني

لإضافة قالب Liquid إلى رسالتك، أدخله في نص الرسالة. يمكنك القيام بذلك عند العمل مع عناصر [push](/ar/product/customer-journey/journey-elements/#push) أو [email](/ar/product/customer-journey/journey-elements/#email)، مباشرة من واجهة أداة إنشاء رحلة العميل (Customer Journey Builder).

اذهب إلى **Customer Journey Builder** > **Create Campaign** > اسحب وأفلت العناصر التالية إلى لوحتك: **Audience-based Entry**، **Push** (أو **Email**)، و **Exit**. قم بتوصيل العناصر. ثم انقر على أيقونة **Push**، واختر **Custom content**، وأدخل نسختك.

لإضافة منطق Liquid، استخدم قيم tag بالصيغة التالية:

```liquid  
{% if TagName == 'value' %}  
  المحتوى الذي سيتم إرساله في هذا السيناريو  
{% else %}  
  المحتوى الذي سيتم إرساله في الحالات الأخرى  
{% endif %}
```
ثم انقر على **Apply**.

<video src="/personalization-liquid-templates-1.webm" title="واجهة أداة إنشاء رحلة العميل (Customer Journey Builder) توضح كيفية إضافة منطق قالب Liquid مع شروط if-else إلى محتوى إشعار Push" autoplay loop muted playsinline />

يجب ألا تحتوي متغيرات القالب (Pushwoosh Tags) على أي مسافات وأن تحتوي فقط على قيم أبجدية رقمية وشرطات سفلية، على سبيل المثال، `my_tag` أو `myTag` بدلاً من `My Tag`.

[تعرف على المزيد حول قوالب Liquid في رحلات العملاء](/ar/product/customer-journey/journey-elements/dynamic-content-and-liquid-templates-in-journeys)

<Aside type="tip">
 يمكنك أيضًا استخدام صيغة Liquid في طلبات `/createMessage` لتنفيذ قوالب Liquid. لهذا، ستحتاج إلى مساعدة من فريق التطوير الخاص بك. شارك [دليل قوالب Liquid](/ar/developer/guides/personalization/liquid-templates) معهم للحصول على إرشادات مفصلة.
</Aside>

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

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

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

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

- **رموز الترويج**: إدراج رموز ترويج فريدة تم إنشاؤها بواسطة خدمة الواجهة الخلفية (backend).

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

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

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

<Aside type="caution" icon="setting" title="مطلوب مساعدة المطورين">
ستحتاج إلى مساعدة فريق المطورين لديك لاستخدام المحتوى المتصل. شارك هذا الدليل معهم للبدء.
</Aside>

#### الخطوة 1. إعداد خدمة الواجهة الخلفية (backend)

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

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

<Aside type="note" title="كيف يعمل"> 

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

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

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

```
{ "code": "SPECIALOFFERFORUSER12345" }
```
</Aside>



#### الخطوة 2. إنشاء إعداد مسبق (preset) مع المحتوى المتصل في Pushwoosh
 
1.  في [محرر محتوى Push](/ar/product/content/push-presets/) أو [محرر محتوى البريد الإلكتروني](/ar/product/content/email-content/drag-and-drop-email-editor/)، أدخل صيغة المحتوى المتصل في حقل الرسالة.

**مثال** 

```
{% 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. |

![أدخل صيغة المحتوى المتصل](/connectedcontent.webp)

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

إذا كانت خدمة الواجهة الخلفية الخاصة بك تتطلب مصادقة، يمكنك تضمين مفتاح 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>`. |

<Aside type="caution" title="قيم ثابتة فقط">
متغيرات التخصيص `${}` تعمل فقط داخل عنوان URL. القيم داخل `:headers` ثابتة ولا يتم استيفاؤها.
</Aside>

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

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

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

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

```

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

![أضف نص الرسالة مع **البيانات المستردة**](/connectedcontent-1.webp)

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

<video src="/connectedcontent-2.webm" title="إرسال رسالة مع محتوى متصل" autoplay loop muted playsinline />

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

أرسل رسالة باستخدام هذا الإعداد المسبق باستخدام [نموذج إشعار فوري لمرة واحدة](/ar/product/messaging-channels/push-notifications/send-push-notifications/one-time-push/#how-to-send-a-push-notification-using-the-one-time-push-form) أو [نموذج البريد الإلكتروني](/ar/product/messaging-channels/emails/sending-emails/send-one-time-emails/) أو [رحلة العميل (customer journey)](/ar/product/customer-journey/pushwoosh-journey-overview/).

<Aside type="caution" title="هام">
إذا أعادت الخدمة حالة غير HTTP 200 OK، فلن يتم إرسال البريد الإلكتروني أو إشعار Push. هذا يضمن أن اتصالك يخرج فقط إذا تم استرداد البيانات اللازمة بنجاح.
</Aside>