كائن Journey

تقوم جميع دوال دورة الحياة (lifecycle) والإنشاء والتحديث (create, and update) بإرجاع كائن journey بنفس الهيكل العام:

الشكل

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

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

Info

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

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

JourneyParams

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

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

SilentHours

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

الحقل	النوع	الوصف
push_params	SilentHoursParams	ساعات الصمت لإشعارات الدفع (push).
inapp_params	SilentHoursParams	ساعات الصمت للرسائل داخل التطبيق.
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 (تخط الرسالة، واستمر في الـ journey فورًا)، أو WaitAndDrop (انتظر انتهاء النافذة، ثم استمر دون إرسال).

EntryCapping

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

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

ConversionWindow

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

Point

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

الحقل	النوع	الوصف
uuid	string	معرف فريد للنقطة داخل الـ journey. يجب أن يكون معرف 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

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

الحقل	النوع	الوصف
identity.key	string	مفتاح الفرع. يجب أن يتبع قواعد مفاتيح المخرجات أدناه.
identity.order	int	ترتيب عرض الفرع.
info.title	string	تسمية فرع اختيارية.
info.next_point_uuid	string	معرف UUID للنقطة التالية التي يتصل بها هذا الفرع. اختياري — تركه فارغًا ينهي الـ journey للمستخدم، بنفس طريقة نقطة الإنهاء (terminator) الصريحة.

مفاتيح المخرجات

الفرع الافتراضي (الأول) يسمى دائمًا "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 (delay)	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	دخول: المستخدمون المطابقون لـ 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).
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	تقسيم المستخدمين حسب شرط (segment، tags، أو event).
POINT_TYPE_AB_SPLITTER	ab_splitter	تقسيم المستخدمين إلى مجموعات A/B.
POINT_TYPE_FILTER	filter	السماح فقط للمستخدمين المطابقين لمرشح بالاستمرار.
POINT_TYPE_SET_TAGS	set_tags	تحديث tags المستخدم.
POINT_TYPE_WEBHOOK	web_hook	إرسال طلب HTTP صادر.
POINT_TYPE_GOAL_EVENT	goal_event	تتبع هدف تحويل.
POINT_TYPE_AUDIENCE_SYNC	audience_sync	مزامنة المستخدمين مع جمهور خارجي.
POINT_TYPE_EXIT	terminator	الخروج من الـ journey.

ملاحظة

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

مثال على نقطة

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

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "وضع علامة كمتفاعل",
  "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 enum

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

CampaignType enum

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

PointType enum

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

UserIDTrackChangePolicy enum

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

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

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

مرجع النقطة

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

دورة الحياة