كائن الرحلة (Journey)

تقوم جميع طرق دورة الحياة، والإنشاء والتحديث بإرجاع كائن رحلة بنفس الهيكل العام:

الشكل

{
  "info": { ... },        // بيانات وصفية للقراءة فقط (في الاستجابات فقط)
  "params": { ... },      // تكوين على مستوى الرحلة (إنشاء / تحديث)
  "points": [ ... ],      // عُقد اللوحة واتصالاتها
  "comments": [ ... ]     // تعليقات اللوحة
}

عندما تقوم بـ إنشاء أو تحديث رحلة، فإنك ترسل title، وparams، وpoints، وcomments. تُرجع الاستجابات info (الذي يحتوي على params) بالإضافة إلى points وcomments.

المعلومات (Info)

بيانات وصفية للرحلة للقراءة فقط. يتم إرجاعها بواسطة كل طريقة من طرق v3. ليست جزءًا من جسم الطلب.

الحقل	النوع	الوصف
uuid	string	معرف الرحلة (Journey ID).
title	string	اسم الرحلة.
status	JourneyStatus	الحالة الحالية.
created_at	string	الطابع الزمني للإنشاء (ISO 8601).
updated_at	string	الطابع الزمني لآخر تحديث (ISO 8601).
is_first_activated	bool	ما إذا كانت الرحلة قد بدأت مرة واحدة على الأقل.
params	JourneyParams	تكوين على مستوى الرحلة.
category_uuid	string	UUID للفئة، أو فارغ إذا لم تكن مصنفة.
pointCounts	map<string, uint32>	عدد النقاط حسب النوع.
campaign_type	CampaignType	كيف يدخل المستخدمون الرحلة.
stop_reason	string	سبب توقف الرحلة، إن وجد.
last_edited_by	User	المستخدم الذي قام بآخر تعديل للرحلة.
dynamic_entry	bool	ما إذا كان الدخول الديناميكي ممكّنًا.

معلمات الرحلة (JourneyParams)

تكوين على مستوى الرحلة. يتم إرساله عند الإنشاء/التحديث ويتم إرجاعه داخل info.params.

الحقل	النوع	الوصف
application_code	string	رمز التطبيق (Application code) الذي تنتمي إليه الرحلة. مطلوب عند الإنشاء.
silent_hours	SilentHours	الساعات التي يتم خلالها منع الرسائل، لكل قناة.
capping	EntryCapping	قيود على عدد المرات التي يمكن للمستخدم إعادة الدخول فيها إلى الرحلة.
conversion_window	ConversionWindow	نافذة زمنية لإسناد تحويلات الأهداف.
user_id_track_change_policy	UserIDTrackChangePolicy	كيفية التعامل مع تغيير معرف المستخدم (User ID) في منتصف الرحلة.

ساعات الصمت (SilentHours)

يمنع الإرسال خلال ساعات الهدوء. يتم تكوينه لكل قناة: تأخذ كل قناة SilentHoursParams خاصة بها:

الحقل	النوع	الوصف
push_params	SilentHoursParams	ساعات الصمت لإشعارات الدفع (push notifications).
inapp_params	SilentHoursParams	ساعات الصمت للرسائل داخل التطبيق (in-app messages).
email_params	SilentHoursParams	ساعات الصمت للبريد الإلكتروني.
sms_params	SilentHoursParams	ساعات الصمت للرسائل النصية القصيرة (SMS).
whatsapp_params	SilentHoursParams	ساعات الصمت لتطبيق WhatsApp.
line_params	SilentHoursParams	ساعات الصمت لتطبيق LINE.

كل SilentHoursParams هو:

الحقل	النوع	الوصف
enabled	bool	ما إذا كانت ساعات الصمت تنطبق على هذه القناة.
from_time	Time	بداية فترة الهدوء: { "hour": 0–23, "minute": 0–59 }.
to_time	Time	نهاية فترة الهدوء.
week_days	bool[]	سبعة قيم منطقية للأيام التي تنطبق فيها الفترة (الاثنين = الفهرس 0).
behavior	enum	ما يجب فعله عندما تقع رسالة داخل ساعات الصمت: WaitAndSend (انتظر، ثم أرسل عند انتهاء الفترة)، DropAndGo (تخط الرسالة، واستمر في الرحلة فورًا)، أو WaitAndDrop (انتظر حتى انتهاء الفترة، ثم استمر دون إرسال).

تحديد سقف الدخول (EntryCapping)

يحد من عدد المرات التي يمكن لنفس المستخدم الدخول فيها إلى الرحلة.

الحقل	النوع	الوصف
is_enabled	bool	ما إذا كان تحديد سقف الدخول مفعّلاً.
period	uint64	الحد الأدنى لعدد الثواني بين مرات دخول المستخدم.

نافذة التحويل (ConversionWindow)

الحقل	النوع	الوصف
seconds	uint64	المدة التي بعدها لا يزال إكمال هدف المستخدم يُحتسب كتحويل بعد دخوله الرحلة.

النقطة (Point)

النقطة هي عقدة على لوحة الرحلة: نقطة دخول، رسالة، تأخير، مقسّم، وهكذا.

الحقل	النوع	الوصف
uuid	string	معرف فريد للنقطة داخل الرحلة. يجب أن يكون UUID أساسيًا وفقًا لـ RFC 4122: 32 رقمًا سداسيًا عشريًا في مجموعات 8-4-4-4-12.
title	string	اسم العرض للنقطة.
point_type	PointType	نوع العقدة.
outputs	array of PointOutput	الاتصالات بالنقاط التالية في المسار.
position	Position	إحداثيات اللوحة.
point_data	object	مفتاح واحد متداخل بالضبط، يطابق point_type (انظر جدول أنواع النقاط).

ملاحظة

يجب أن تكون جميع معرفات UUID (info.uuid، كل uuid للنقاط، وnext_point_uuid لكل مخرج) معرفات UUID أساسية وفقًا لـ RFC 4122 (مجموعات سداسية عشرية 8-4-4-4-12).

مخرجات النقطة (PointOutput)

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

الحقل	النوع	الوصف
identity.key	string	مفتاح الفرع. يجب أن يتبع قواعد مفاتيح المخرجات أدناه.
identity.order	int	ترتيب عرض الفرع.
info.title	string	تسمية فرع اختيارية.
info.next_point_uuid	string	UUID للنقطة التالية التي يتصل بها هذا الفرع.

مفاتيح المخرجات (Output keys)

يُسمى الفرع الافتراضي (الأول) دائمًا "default". تُسمى الفروع الإضافية "output1"، "output2"، … (البادئة output متبوعة بفهرس يبدأ من 1). يكسر نوعان من النقاط هذه القاعدة، كما هو موضح أدناه.

نوع النقطة	مفاتيح المخرجات المتوقعة
نقاط الدخول (START_BY_SEGMENT، START_BY_API، EVENT)، INAPP، SET_TAGS، WEBHOOK، AUDIENCE_SYNC، ونقاط الرسائل بدون مقسّم (SEND_PUSH، SEND_EMAIL، SEND_SMS، SEND_WHATSAPP، SEND_LINE، SEND_KAKAO، SEND_TELEGRAM، SEND_DATA)	default
GOAL_EVENT، EXIT	لا شيء (لا توجد مخرجات)
FILTER	default، output1
BOOLEAN_SPLITTER	default، ثم output1 … outputN (فرع إضافي واحد لكل شرط. التقسيم البسيط بنعم/لا هو default + output1)
WAIT (تأخير)	default. يضيف التأخير الديناميكي مع تقسيم الفروع output1
WAIT_EVENT	default هو فرع الحدث-لم-يتم-تشغيله. output1 (أو، مع نص برمجي للشروط، فرع واحد لكل شرط) هو المسار الذي تم تشغيله
SEND_PUSH مع مقسّم	default، output1 (و output2 عندما يكون كل من مقسّم الرسالة والتسليم مفعّلين)
SEND_EMAIL / SEND_SMS / SEND_LINE / SEND_WHATSAPP مع مقسّم	default، output1
SEND_WHATSAPP مع إعداد مسبق للرد السريع	default، بالإضافة إلى فرع واحد لكل رد سريع. المفتاح هو قيمة الرد السريع نفسها
AB_SPLITTER	output0، output1، output2، … (واحد لكل متغير. لا يوجد فرع default)

الموضع (Position)

الحقل	النوع	الوصف
x	float	الإحداثي الأفقي على اللوحة.
y	float	الإحداثي الرأسي على اللوحة.

أنواع النقاط و point_data

point_data هو واحد من: يحمل كائنًا متداخلاً واحدًا بالضبط يتم تحديد مفتاحه بواسطة point_type للنقطة.

point_type	مفتاح point_data	الغرض
POINT_TYPE_START_BY_SEGMENT	start_by_segment	الدخول: المستخدمون الذين يطابقون شريحة.
POINT_TYPE_EVENT	message_bus	الدخول: المستخدمون الذين يطلقون حدثًا.
POINT_TYPE_START_BY_API	start_by_api	الدخول: المستخدمون الذين يتم إدخالهم عبر استدعاء Start by API.
POINT_TYPE_WAIT	delay	انتظر لفترة ثابتة أو ديناميكية.
POINT_TYPE_WAIT_EVENT	wait_event	انتظر حتى يقع حدث.
POINT_TYPE_SEND_PUSH	send_push	إرسال إشعار دفع (push notification).
POINT_TYPE_SEND_EMAIL	send_email	إرسال بريد إلكتروني.
POINT_TYPE_SEND_SMS	send_sms	إرسال رسالة نصية قصيرة (SMS).
POINT_TYPE_SEND_WHATSAPP	send_whatsapp	إرسال رسالة WhatsApp.
POINT_TYPE_SEND_TELEGRAM	send_telegram	إرسال رسالة Telegram.
POINT_TYPE_SEND_KAKAO	send_kakao	إرسال رسالة Kakao.
POINT_TYPE_SEND_LINE	send_line	إرسال رسالة LINE.
POINT_TYPE_SEND_DATA	send_data	إرسال رسالة بيانات صامتة.
POINT_TYPE_INAPP	inapp	عرض رسالة داخل التطبيق.
POINT_TYPE_BOOLEAN_SPLITTER	boolean_splitter	تقسيم المستخدمين حسب شرط (شريحة، علامات، أو حدث).
POINT_TYPE_AB_SPLITTER	ab_splitter	تقسيم المستخدمين إلى مجموعات A/B.
POINT_TYPE_FILTER	filter	السماح فقط للمستخدمين الذين يطابقون مرشحًا بالاستمرار.
POINT_TYPE_SET_TAGS	set_tags	تحديث علامات المستخدم.
POINT_TYPE_WEBHOOK	web_hook	إرسال طلب HTTP صادر.
POINT_TYPE_GOAL_EVENT	goal_event	تتبع هدف تحويل.
POINT_TYPE_AUDIENCE_SYNC	audience_sync	مزامنة المستخدمين مع جمهور خارجي.
POINT_TYPE_EXIT	terminator	الخروج من الرحلة.

ملاحظة

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

مثال على نقطة

نقطة “تعيين العلامات” مع اتصال واحد تالٍ:

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Tag as engaged",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}

تعليق الرحلة (JourneyComment)

الحقل	النوع	الوصف
id	string	UUID للتعليق.
message	string	نص التعليق.
position	Position	إحداثيات اللوحة.
index	int	ترتيب العرض.
created_at	string	الطابع الزمني للإنشاء (ISO 8601).
deleted	bool	ما إذا كان التعليق محذوفًا.

التعدادات (Enums)

تعداد JourneyStatus

STATUS_DRAFT, STATUS_RUNNING, STATUS_FINISHED, STATUS_ARCHIVED, STATUS_PAUSED, STATUS_UNKNOWN.

تعداد CampaignType

• TriggerBased: يدخل المستخدمون بناءً على حدث.
• AudienceBased: يدخل المستخدمون من شريحة.
• APIBased: يدخل المستخدمون عبر استدعاء Start by API.
• Mixed: أكثر من نوع دخول واحد.
• Unknown: لم يتم تحديد نوع الدخول.

تعداد PointType

انظر جدول أنواع النقاط أعلاه للحصول على القائمة الكاملة ومفتاح point_data الذي يرتبط به كل نوع.

تعداد UserIDTrackChangePolicy

يتحكم في ما يحدث للمستخدم الذي يكون في منتصف الرحلة عندما يتغير معرف المستخدم (User ID) الخاص به:

• DEFAULT: السلوك الافتراضي.
• TRACK: استمر في تتبع المستخدم تحت المعرف الجديد.
• DROP: أزل المستخدم من الرحلة عندما يتغير معرفه.

مواضيع ذات صلة

مرجع النقطة

الإنشاء والتحديث

دورة الحياة