كائن Journey

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

الشكل

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

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

Info

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

الحقل	النوع	الوصف
uuid	string	معرف Journey.
title	string	اسم Journey.
status	JourneyStatus	الحالة الحالية.
created_at	string	الطابع الزمني للإنشاء (ISO 8601).
updated_at	string	الطابع الزمني لآخر تحديث (ISO 8601).
is_first_activated	bool	ما إذا كانت الرحلة قد بدأت مرة واحدة على الأقل.
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	ساعات الهدوء لإشعارات الدفع.
inapp_params	SilentHoursParams	ساعات الهدوء للرسائل داخل التطبيق.
email_params	SilentHoursParams	ساعات الهدوء للبريد الإلكتروني.
sms_params	SilentHoursParams	ساعات الهدوء للرسائل القصيرة.
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

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

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

يتم احتساب الحد من لحظة دخول المستخدم إلى Journey، ويتم تتبعه لكل User ID، لذا تشترك جميع أجهزة المستخدم الواحد في إدخال واحد. أثناء استمرار الفترة، ترفض نقطة الدخول محاولات الدخول الإضافية وتعتبرها أخطاء بدلاً من إنشاء مسافر.

ثلاثة سلوكيات يجب مراعاتها عند تغيير هذه الإعدادات:

• مغادرة Journey مبكرًا لا يزيل الحد. ينتظر المستخدم الفترة الكاملة حتى بعد الوصول إلى نقطة خروج.
• ينطبق period المتغير على الإدخالات التي تتم بعد التحديث. يحتفظ المستخدمون الذين دخلوا سابقًا بالفترة التي كانت سارية عند دخولهم.
• يؤدي تعيين is_enabled إلى false إلى رفع الحد لكل مستخدم على الفور.

ملاحظة

تكتب لوحة التحكم نفس الحقل من حد دخول الحملة، والذي يوفر 0 (مرة واحدة في العمر)، 1440 (مرة في اليوم)، 10080 (مرة في الأسبوع)، 43800 (مرة في الشهر)، و 131500 (مرة كل ثلاثة أشهر).

ConversionWindow

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

Point

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

الحقل	النوع	الوصف
uuid	string	معرف فريد للنقطة داخل Journey. يجب أن يكون RFC 4122 UUID أساسي: 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 للنقطة التالية التي يتصل بها هذا الفرع. اختياري — تركه فارغًا ينهي الرحلة للمستخدم، تمامًا مثل نقطة الإنهاء الصريحة.

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

يُسمى الفرع الافتراضي (الأول) دائمًا "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	إرسال إشعار دفع.
POINT_TYPE_SEND_EMAIL	send_email	إرسال بريد إلكتروني.
POINT_TYPE_SEND_SMS	send_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	الخروج من Journey.

ملاحظة

تم توثيق حمولات 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 enum

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

CampaignType enum

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

PointType enum

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

UserIDTrackChangePolicy enum

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

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

ذات صلة

مرجع النقطة

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

دورة الحياة