> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudgen.net/llms.txt
> Use this file to discover all available pages before exploring further.

# استخدام الحملات مدى الحياة

> أرسل دفعة واحدة محفزة بالحدث إلى جهة اتصال مع كل مشغل تمت مصادقته

## ما تساعدك هذه الصفحة على فعله

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

## سبب أهمية ذلك

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

## متى تستخدم حملة مدى الحياة

استخدم حملة مدى الحياة للبريد الإلكتروني المستند إلى الحدث، مثل:

* تأكيدات الطلب
* تذكيرات الدفع
* الإعداد على أساس الحدث
* تحديثات الحساب أو الاشتراك

على عكس الحملات الفردية والقطرية، فإن الحملة مدى الحياة لا يتم إرساله إلى الجمهور المحفوظ على الفور. جمهورها هو **المحفز** دائمًا.

## إنشاء حملة وتنشيطها

<Steps>
  <Step title="Create a Lifetime campaign">
    انتقل إلى **الحملات**، وانقر على **حملة جديدة**، ثم اختر **مدى الحياة**. أضف اسم الحملة، والهدف، وتكوين العلامة التجارية، ورابط CTA الاختياري.
  </Step>

  <Step title="Define runtime parameters">
    أضف كل قيمة سيوفرها نظامك في وقت الإرسال. تقوم المعلمة بإنشاء متغير `data.*`: على سبيل المثال، `order_id` يصبح `{{data.order_id}}` في البريد الإلكتروني.
  </Step>

  <Step title="Create the email">
    قم بإنشاء الموضوع وHTML أو كتابتهما، ثم أضف متغيرات وقت التشغيل حيث تنتمي. قم بمعاينة البريد الإلكتروني وأرسل اختبارًا قبل تفعيله.
  </Step>

  <Step title="Activate the campaign">
    احفظه كمسودة، ثم انقر فوق **تنشيط**. يتحقق Nudgen من تمثيل المعلمات المطلوبة في البريد الإلكتروني وأن عقد المعلمة لم يتغير منذ الإنشاء.
  </Step>

  <Step title="Create a trigger key">
    انتقل إلى **الإعدادات** → **مفاتيح واجهة برمجة التطبيقات** وأنشئ **مفتاح واجهة برمجة تطبيقات تشغيل الفريق**. قم بتخزين سر `ndg_team_*` في الواجهة الخلفية أو المدير السري؛ لا تضعه أبدًا في رمز المتصفح أو تطبيق الهاتف المحمول.
  </Step>
</Steps>

## معلمات وقت التشغيل ومتغيرات القالب

`variableManifest` الخاص بك هو العقد بين قالب البريد الإلكتروني وكائن `data` لكل مشغل. يمكن للحملة أن تحدد ما يصل إلى 100 متغير.

| المجال         | اكتب                                                     | مطلوب | الوصف                                                                                         |
| -------------- | -------------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------- |
| `path`         | `data.<name>`                                            | نعم   | مسار متغير. يتم دعم المسارات المتداخلة مثل `data.order.total`.                                |
| `type`         | `string`، أو `number`، أو `boolean`، أو `date`، أو `url` | نعم   | اكتب المشغل الذي يجب توفيره. يجب أن يكون `date` سلسلة تاريخ صالحة ويجب أن يكون `url` HTTP(S). |
| `required`     | منطقية                                                   | نعم   | تُرجع القيم المفقودة `422` ما لم يتم تعيين الإعداد الافتراضي.                                 |
| `defaultValue` | سلسلة أو رقم أو منطقية                                   | لا    | القيمة الاحتياطية التي يجب أن تتطابق مع نوع المتغير.                                          |
| `description`  | سلسلة                                                    | لا    | اشرح القيمة حتى تتمكن أنت وNudgen AI من استخدامها بشكل صحيح.                                  |

على سبيل المثال، استخدم `{{data.order_id}}` و`{{data.total}}` و`{{data.order_url}}` في قالب. يمكنك أيضًا استخدام `contact.*` و`event.*` و`brand.*` والمتغيرات القديمة مثل `{{firstName}}` و`{{brandName}}`.

يفلت Nudgen من القيم المتغيرة المدرجة في HTML. لا تدعم القوالب JavaScript أو التعبيرات أو الحلقات. أي متغير مستخدم في `href` يجب أن يكون متغير `data.*` مُعلن بالنوع `url`.

## إدارة دورة الحياة

| الحالة           | ماذا يعني                                        |
| ---------------- | ------------------------------------------------ |
| **مسودة**        | قم بتكوين الحملة واختبار بريدها الإلكتروني.      |
| **نشط**          | يقبل Nudgen المشغلات المصادق عليها.              |
| **متوقف مؤقتًا** | Nudgen لا يقبل المشغلات الجديدة. يمكنك استئنافه. |
| **مؤرشفة**       | الحملة مغلقة نهائيا ولا يمكن تفعيلها مرة أخرى.   |

الانتقالات الصالحة هي `draft → active → paused → active` و`active|paused → archived`.

<Note>
  يؤدي الإيقاف المؤقت أو الأرشفة إلى إلغاء عمليات التنفيذ التي لا تزال معلقة أو في قائمة الانتظار. قد يستمر إرسال عملية تنفيذ قيد المعالجة بالفعل.
</Note>

كل عملية تنفيذ تلتقط لقطات لمحتوى الحملة وترسل الإعدادات عندما يتلقى Nudgen المشغل. يؤثر تحرير الحملة النشطة فقط على المشغلات اللاحقة، وليس عمليات التنفيذ الموجودة بالفعل.

## المشغل من الواجهة الخلفية لديك

استدعاء نقطة نهاية المشغل من خادم موثوق به بعد التحقق من صحة الحدث المصدر. استخدم مفتاح واجهة برمجة تطبيقات تشغيل الفريق، وليس رمز الوصول الشخصي (PAT).

```bash theme={null}
curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/triggers" \
  -H "Authorization: Bearer $NUDGEN_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "eventId": "order_123",
  "eventName": "order.created",
  "occurredAt": "2026-08-23T10:00:00Z",
  "contact": {
    "email": "an@example.com",
    "externalId": "customer_456",
    "name": "An Nguyen",
    "metadata": { "company": "Nudgen" }
  },
  "data": {
    "order_id": "order_123",
    "total": 490000,
    "order_url": "https://example.com/orders/order_123"
  }
}
JSON
```

احتفظ بنفس `eventId` عند إعادة محاولة إجراء حدث. يقوم Nudgen بإرجاع التنفيذ الحالي باستخدام `200` و`duplicate: true` بدلاً من إرسال دفعة أخرى. يؤدي التنفيذ الجديد إلى إرجاع `201`.

## التكامل بأمان

* قم بالتشغيل من مستهلك خطاف الويب أو الواجهة الخلفية، وتحقق من خطاف الويب الوارد قبل استدعاء Nudgen.
* أعد محاولة أخطاء الشبكة، `429`، و`503` مع التراجع الأسي ونفس الشيء `eventId`.
* لا تقم بتسجيل رؤوس `Authorization` أو الحمولات التي تحتوي على بيانات اتصال حساسة.
* قم بتدوير مفاتيح التشغيل بانتظام وإلغاء المفتاح على الفور إذا كنت تشك في كشفه.
* أنشئ حملة واحدة لكل نوع حدث وعقد متغير بحيث تظل القوالب وعمليات تدقيق التنفيذ واضحة.

## مراقبة عمليات التنفيذ

افتح الحملة في لوحة المعلومات لرؤية عمليات التنفيذ الأخيرة وحالاتها. يمكن أن يكون التنفيذ `pending`، أو `queued`، أو `processing`، أو `sent`، أو `skipped`، أو `cancelled`، أو `failed`، أو `delivery_unknown`.

`skipped` تعني أن جهة الاتصال قد تم إلغاء اشتراكها أو ارتدادها، لذلك يقوم Nudgen بتسجيل الحدث ولكنه لا يرسل أو يستهلك الحصة. `delivery_unknown` يعني أن المزود ربما يكون قد قبل البريد الإلكتروني ولكن نتيجة التسليم النهائية كانت غير مؤكدة؛ لا يقوم Nudgen بإعادة المحاولة تلقائيًا لتجنب إرسال مكرر.

للحصول على استعلامات الإعداد الآلي والتشغيل والتنفيذ، راجع [Developer API](/ar/agents/api).

## المستندات ذات الصلة

<CardGroup cols={2}>
  <Card title="Campaigns overview" icon="list" href="/ar/campaigns/overview">
    قارن بين الحملات اللقطة الواحدة والتنقيط والحملات مدى الحياة.
  </Card>

  <Card title="Developer API" icon="code" href="/ar/agents/api">
    إدارة الحملات والمشغلات مدى الحياة من خلال واجهة برمجة التطبيقات.
  </Card>
</CardGroup>