تخطّ إلى المحتوى الرئيسي

الاستيراد المجمع (CSV / JSON)

يتيح لك الاستيراد المجمع تحميل البيانات إلى Joryio من ملف: ملفات المستخدمين الشخصية أو الأحداث التاريخية أو صفوف الكيانات المخصصة. افتح البيانات → الاستيراد المجمع (/users/import) في لوحة التحكم، وأسقط ملف CSV أو JSON، واربط أعمدته، وتعالجه Joryio في الخلفية بينما تتابع التقدم.

ليس هو نفسه استيراد البيانات

تغطي هذه الصفحة رفع الملفات. يسحب موصل استيراد البيانات المنفصل ضمن البيانات → استيراد البيانات بيانات المستخدمين من مستودعات البيانات (Snowflake وBigQuery) عبر اتصال تضبطه مرة واحدة. استخدم الاستيراد المجمع للملفات لمرة واحدة، مثل تصدير CRM أو قائمة قديمة أو إعادة ملء الأحداث؛ واستخدم استيراد البيانات عندما يكون مصدر الحقيقة في مستودع بيانات.

متطلبات الملف​

التنسيقات.csv (الصف الأول = رؤوس الأعمدة؛ مفصول بفواصل أو فواصل منقوطة أو علامات جدولة؛ بترميز UTF-8 مع BOM أو بدونه) أو .json (مصفوفة من الكائنات؛ يُرفض أي تنسيق آخر).
حجم الرفعحتى 100 MB لكل ملف من لوحة التحكم.
الصفوفحتى 1,000,000 صف لكل عملية استيراد (على الخادم؛ ولا تُعالج الصفوف بعد الحد).
التزامنعملية استيراد واحدة في كل مرة لكل مساحة عمل؛ يُرفض بدء أخرى أثناء معالجة واحدة.

تُرفع الملفات مباشرة إلى التخزين عبر URL موقع مسبقًا، ثم يعالج عامل في الخلفية المهمة. تُحذف الملفات المرفوعة بعد المعالجة وتنتهي بعد 24 ساعة في جميع الحالات.

أنواع الاستيراد​

اختر النوع قبل الرفع؛ إذ يغير أهداف الربط المتاحة:

  • المستخدمون - أنشئ ملفات جهات الاتصال أو حدّثها.
  • الأحداث - أعد ملء أحداث تاريخية في مخزن التحليلات.
  • الكيانات - حمّل صفوفًا إلى أحد كياناتك المخصصة (تختار أيها).

ربط الأعمدة​

يتم الاستيراد على خطوتين.

الخطوة 1 - اختيار الملف. اختر نوع الاستيراد (وفي الكيانات اختر الكيان)، ثم اسحب ملف .csv أو .json أو تصفّح إليه، وانقر التالي. يقرأ Joryio أسماء الأعمدة في متصفحك: صف العناوين في ملف CSV، أو مفاتيح أول 50 كائنًا في مصفوفة JSON. الملف الذي لا يحتوي على صف عناوين، أو ملف JSON ليس مصفوفة من الكائنات، يعرض خطأ هنا بدلًا من المتابعة.

الخطوة 2 - ربط الأعمدة. صف لكل عمود في ملفك، مع ما يصل إلى ثلاث قيم نموذجية من الصفوف الأولى وقائمة منسدلة الاستيراد كـ. يبدأ كل عمود مربوطًا مسبقًا حسب اسمه (انظر الجدول أدناه). العمود الذي لا يُعرف اسمه يبدأ كـسمة مخصصة باسم العمود - وتتحول النقطة في الاسم إلى _، لأن النقطة كانت ستخزن مسارًا متداخلًا. يمكنك تغيير أي ربط، أو إعادة تسمية سمة مخصصة، أو اختيار عدم الاستيراد لاستبعاد عمود. يعيدك رجوع إلى الخطوة 1 مع الاحتفاظ بملفك واختياراتك.

يبقى زر بدء الاستيراد معطّلًا حتى يتمكن الربط من استيراد شيء:

  • في استيراد المستخدمين يُربط عمود بـالبريد الإلكتروني أو المعرّف الخارجي - تُتخطى الصفوف التي لا تحتوي على أي منهما، لذا فإن ربط الهاتف وحده لن يستورد شيئًا؛
  • في استيراد الأحداث يُربط اسم الحدث ومعه معرّف المستخدم أو البريد الإلكتروني؛
  • في استيراد الكيانات تُربط كل الحقول الإلزامية؛
  • لا يُربط عمودان بالهدف نفسه، والاسم المخصص ليس فارغًا ولا يحتوي على . ولا يبدأ بـ $.

تُرسل الأعمدة التي تستوردها فقط: العمود المضبوط على عدم الاستيراد لا يُكتب.

أسماء الأعمدة المعروفة​

تتجاهل المقارنة حالة الأحرف والمسافات و_ و-، لذا فإن First Name وfirst_name وfirst-name وFirstName اسم واحد.

اسم العموديُستورد كـ
email, e-mail, email_addressالبريد الإلكتروني
phone, phone_number, mobile, mobile_number, mobile_phone, cell, cell_phone, telephone, telالهاتف
external_id, externalId, user_id, userIdالمعرّف الخارجي
first_name, firstname, given_name, fname, forenameالاسم الأول (attributes.firstName)
last_name, lastname, surname, family_name, lnameاسم العائلة (attributes.lastName)
email_subscribe, email_subscription_status, sms_opt_in, whatsapp_consent, viber_status, ...حالة اشتراك القناة - اسم قناة (email, sms, whatsapp, push, viber) تليه كلمة حالة (status, subscribe, subscription, subscribed, consent, opt_in, opted_in)

العمود الذي يدل اسمه على العكس - email_unsubscribe, sms_opt_out, email_opted_out - لا يُكتشف أبدًا كحالة اشتراك. في مثل هذا العمود تعني "yes" أن الشخص ألغى اشتراكه، لذا فإن قراءته كموافقة ستؤدي إلى اشتراكه. يُستورد كسمة مخصصة؛ لتطبيقه، غيّر قيمه أولًا إلى حالات (مثل unsubscribed) ثم اربطه باشتراك القناة.

لا يُقسَّم name وfull_name إلى اسم أول واسم عائلة - لا توجد قاعدة تقسم كل اسم بشكل صحيح. يُستوردان كسمة مخصصة ({{ user.full_name }} في الرسالة). عندما يحتوي الملف على عمودين للحقل نفسه (مثل phone وmobile)، يفوز الاسم الذي يظهر أولًا في القائمة أعلاه ويبقى العمود الآخر سمة مخصصة، فلا تضيع أي قيمة.

ضع الأسماء في الاسم الأول واسم العائلة: منهما تقرأ وسوم الدمج القياسية {{ user.firstName }} و{{ user.lastName }} والبحث عن جهات الاتصال والملف الشخصي. أما الاسم المخزن كسمة مخصصة مثل first_name فلا يظهر إلا عبر {{ user.first_name }}.

تُعرف الأسماء نفسها أيضًا عند استدعاء Imports API بدون fieldMapping.

الأهداف في استيراد المستخدمين​

الهدفالمعنى
externalIdمعرّف المستخدم الثابت لديك؛ وهو المعرّف المفضل.
email / phoneمعرّفات جهة الاتصال. يتحول Email إلى أحرف صغيرة وتزال مسافاته؛ ويطبع الهاتف بتنسيق E.164.
attributes.firstName, attributes.lastName, attributes.<anything>سمات الملف الشخصي. لـ attributes.<anything> اختر سمة مخصصة وعدّل الاسم.
subscriptions.email / sms / whatsapp / push / viberحالة الموافقة على مستوى القناة.
Group: <name> (<channel>)موافقة لكل مجموعة: يضبط حالة جهة الاتصال في مجموعة اشتراك/فئة موافقة محددة (تخزن كـ subscriptions.list.<listId>.<channel>). راجع إدارة الاشتراكات.

أرقام الهاتف​

أرسل أرقام الهاتف مع + ورمز الدولة

أرسل أرقام الهاتف دائمًا بالصيغة الدولية الكاملة (E.164): + ثم رمز الدولة ثم الرقم - مثل +972501234567. الرقم الذي لا يبدأ بـ + يُقرأ وفق الدولة الافتراضية لأرقام الهاتف في مساحة العمل؛ وإذا لم تُعيَّن، أو أمكن قراءة الأرقام بطريقتين، يُحفظ غير موثّق ولا يُستخدم للرسائل. كيف تُعالَج أرقام الهاتف

يُستورد الهاتف المكتوب برمز الدولة (+972501234567) كما هو. أما الهاتف دون رمز (0501234567) فيُقرأ وفق الدولة الافتراضية لأرقام الهاتف في مساحة العمل؛ وإن لم تُحدَّد فلا يُحوَّل. الهاتف الذي ليس رقمًا صالحًا يُحتفظ به ولا يُحذف: يُحفظ بوصفه الرقم غير المُتحقَّق منه لجهة الاتصال (phoneUnverified)، ولا يتغير الهاتف الحالي لجهة الاتصال، ويتضمن تقرير الاستيراد سطر notice لذلك الصف. لا تُرسل رسائل أبدًا إلى الأرقام غير المُتحقَّق منها. تتبع مزامنة مستودع البيانات القواعد نفسها. يعرض تصدير جهات الاتصال الرقم غير المُتحقَّق منه في عمود أخير هو phoneUnverified.

كيفية مطابقة المستخدمين (إزالة التكرار / التعريف)​

يجب أن يحمل كل صف مستخدم externalId أو email؛ تُتخطى الصفوف التي لا تحمل أيًا منهما وتُدرج في تقرير الأخطاء. رقم الهاتف وحده لا يكفي: يُتخطى أيضًا الصف الذي لا يحمل سوى هاتف.

  • externalId أولاً. إذا كان للصف externalId، تطابق Joryio عليه وحده ضمن مساحة العمل. يُكتب البريد الإلكتروني الموجود في الصف إلى جهة الاتصال هذه، لكنه لا يُستخدم للعثور عليها. لا توجد جهة اتصال بهذا externalId: تُنشأ جهة اتصال جديدة.
  • وإلا email. يطابق الصف على email المطبع (بأحرف صغيرة ودون مسافات في الطرفين). لا توجد جهة اتصال بهذا البريد: تُنشأ جهة اتصال جديدة. جهة واحدة بالضبط: تُحدَّث. عدة جهات: انظر أدناه.
  • الهاتف لا يطابق أبدًا. يُكتب عمود phone إلى جهة الاتصال التي طابقها الصف أو أنشأها، لكنه لا يُستخدم أبدًا للعثور على جهة اتصال.
  • يؤدي التطابق إلى تحديث الملف الحالي (تُكتب الحقول الموجودة في الصف فقط؛ وتبقى السمات غير الموجودة في الملف دون تغيير).

يعرض ملخص المهمة النتيجتين منفصلتين بوصفهما أُنشئت وحُدثت. إعادة استيراد الملف نفسه آمنة: تتحول الصفوف ببساطة إلى تحديثات.

عندما تتشارك عدة جهات اتصال بريدًا إلكترونيًا واحدًا​

عنوان البريد الإلكتروني ليس فريدًا في مساحة العمل - قد يتشارك زوجان أو عائلة عنوانًا واحدًا، أو يوجد شخص واحد تحت معرّفي مستخدم. عندما يحمل الصف بريدًا إلكترونيًا دون externalId، ولدى أكثر من جهة اتصال هذا البريد:

  • تُحدَّث جهة اتصال واحدة بالضبط: الأحدث نشاطًا - جهة الاتصال التي تغيّر ملفها الشخصي مؤخرًا أكثر من غيرها (وعند التساوي، الأحدث إنشاءً). يختار الملف نفسه جهة الاتصال نفسها في كل مرة.
  • تبقى الجهات الأخرى كما هي. لا يدمج الاستيراد جهات الاتصال أبدًا ولا يحدّثها جميعًا أبدًا - وإلا لكتب اسمٌ في الصف فوق اسم شخص آخر.
  • إلغاء الاشتراك في الصف يسري على كل جهة اتصال لديها هذا البريد، كما هو موضح في جهات الاتصال المكررة.
  • الاشتراك في الصف يسري على جهة الاتصال المحدَّثة فقط. إعادة الاشتراك تكون لكل جهة اتصال على حدة؛ وتحتفظ الجهات الأخرى بحالتها.
  • يعرض ملخص الاستيراد عدد الصفوف التي طابقت عدة جهات اتصال، ويدرج التقرير القابل للتنزيل كلًا منها بوصفه notice - وليس خطأ، لأن الصف استُورد.

لتحديث جهة اتصال محددة بدقة، أضف عمود externalId: الصف الذي يحمل externalId يطابق دائمًا جهة الاتصال تلك وحدها. تطابق مزامنات مستودعات البيانات (Data Import) الصفوف بالطريقة نفسها.

حالات الاشتراك وسلامة الموافقة​

تُحلل خلايا الحالة بمرونة: تعني subscribed / true / yes / 1 مشترك؛ وتعني unsubscribed / false / no / 0 / opt_out غير مشترك؛ وتعني opted_in / double_opt_in / confirmed اشتراكًا مؤكدًا. القيم الفارغة أو غير المعروفة تترك القناة دون تغيير.

افتراضيًا (مربع الاختيار غير محدد)، تنطبق قواعد حماية الموافقة على كل قناة ومجموعة:

  • تُطبق حالات إلغاء الاشتراك في الملف دائمًا.
  • لا يعيد الاستيراد اشتراك مستخدم ألغى الاشتراك سابقًا بصمت أبدًا.
  • لا يخفض اشتراك مؤكد إلى اشتراك عادي أبدًا.

تحديد "Override unsubscribes" (للمشرفين والمالكين فقط، بعد تحذير) يجعل الملف مصدر الحقيقة - فيمكنه إعادة اشتراك من ألغوا سابقاً وخفض الموافقات المؤكدة. أنت تؤكد أن لديك موافقة للتواصل مع هؤلاء المستخدمين. وفي كل الأحوال، يُكتب كل تغيير يجريه الاستيراد في سجل اشتراكات جهة الاتصال بالمصدر import.

جهات الاتصال المكررة و"Override unsubscribes"​

يتبع الاستيراد القواعد في جهات الاتصال التي تشترك في بريد إلكتروني أو هاتف:

  • "Override unsubscribes" معطّل افتراضياً. بدونه، تُتجاهل قيمة subscribed لجهة اتصال ألغت اشتراكها سابقاً - أو بريدها أو هاتفها محظور بسبب إلغاء جهة أخرى - وتُحتسب بقيت ملغاة.
  • عند تحديد الخيار، يُعاد اشتراك هذه الجهة - هي وحدها. وتبقى الجهات الأخرى بالبريد أو الهاتف نفسه ملغاة.
  • عند تحديد الخيار، يُتجاوز إلغاء STOP أيضاً - لجهة الاتصال هذه وحدها، ويُسجَّل في سجلها مع مهمة الاستيراد. في SMS تعرض صفحة الاستيراد تحذيراً بجانب خانة الاختيار ويعدّ الملخص جهات الاتصال هذه: This contact opted out by texting STOP. Your SMS provider may keep blocking messages until they text START.
  • لا يرفع الاستيراد أبداً ارتداداً دائماً أو شكوى بريد عشوائي، أو حظراً على مستوى المؤسسة (لا يرفعها إلا دعم Joryio). تُعدّ هذه الصفوف بشكل منفصل.
  • إلغاءات الاشتراك في الملف تصل إلى كل تكرار. تُلغى أيضاً كل جهة اتصال في مساحة العمل بالبريد أو الهاتف نفسه، مع سجل.

عند انتهاء الاستيراد، يعرض الملخص عدد جهات الاتصال التي تم تجاوزها (ومنها عدد جهات اتصال SMS التي أرسلت STOP)، وعدد التي بقيت ملغاة، أو بقيت بسبب ارتداد دائم أو شكوى، أو بسبب حظر على مستوى المؤسسة. تتبع مزامنات مستودع البيانات القواعد نفسها. ولا تعيد مزامنات المتاجر (Shopify وWooCommerce وMagento) اشتراك أي أحد أبداً.

استيراد الأحداث​

الحقول المستهدفة: userId (يطابق externalId) وemail وeventName وtimestamp وproperties.<key> لخصائص الحدث. القواعد التي يطبقها العامل:

  • يحتاج كل صف إلى eventName و**userId أو email**؛ ويجب أن يكون المستخدم موجودًا بالفعل في مساحة العمل، وإلا يُتخطى الصف (استورد المستخدمين أولًا).
  • timestamp اختياري؛ تفشل قيمة لا يمكن تحليلها الصف، وتُثبت القيم غير المعقولة (أكثر من نحو سنتين ماضيتين أو ساعة مستقبلية) إلى الآن؛ وهي القاعدة نفسها لتتبع الأحداث الحية.
  • تحصل الخصائص على حدود الحماية نفسها لمسار /track الحي: حدود الحجم وعدد المفاتيح والعمق وإخفاء معلومات التعريف الشخصية.
  • عمليات الاستيراد آمنة لإعادة المحاولة؛ لا يمكن لإعادة تشغيل المهمة نفسها أن تدرج الأحداث مرتين.

تصل الأحداث المستوردة إلى تدفق الأحداث نفسه للأحداث الحية، ولذلك تكون مرئية للشرائح والتحليلات.

استيراد الكيانات​

اختر الكيان المستهدف أولًا؛ تصبح حقوله أهداف الربط. من دون ربط، تطابق الأعمدة أسماء حقول الكيان مباشرة. تُتخطى الصفوف التي تفتقد حقل كيان مطلوبًا مع خطأ. إذا حمل الصف عمود _id / id فإنه يحدّث أو ينشئ (يحدّث السجل الحالي أو ينشئه)؛ وإلا فيدرج سجلًا جديدًا. يتبع التحكم بالإصدارات والحذف الناعم إعدادات الكيان نفسه.

مراقبة عملية استيراد​

يعرض جدول عمليات الاستيراد الأخيرة كل مهمة مع نوعها وتنسيقها وشريط التقدم والحالة ومن بدأها، ويتحدث تلقائيًا أثناء تشغيل أي مهمة. الحالات:

الحالةالمعنى
معلق / قيد المعالجةفي الطابور، ثم يعالج الملف على دفعات.
مكتملانتهى؛ راجع عدادات كل صف.
فشلفشلت المهمة ذاتها (مثل عدم العثور على الملف المرفوع)؛ وتظهر رسالة الخطأ. تُعاد محاولة المهام الفاشلة مرة تلقائيًا قبل أن تصل إلى هنا.
منتهية الصلاحيةمهمة مكتملة قديمة نُظف ملفها وتقرير أخطائها (24 ساعة).

انقر عرض في مهمة لفتح نافذة التفاصيل: إجمالي الصفوف وعدادات أُنشئت / حُدثت / متخطاة / فاشلة، وعدد الصفوف التي طابقت عدة جهات اتصال، وعند وجود صفوف فيها مشكلات أو إشعارات يظهر رابط تنزيل تقرير الأخطاء (تنزيل التقرير عندما يتضمن إشعارات أيضًا). يحتوي التقرير على سطر لكل صف: رقمه ونوعه (error - لم يُكتب الصف، أو notice - كُتب لكنه يستحق المراجعة) والسبب؛ وتُحجب قيم المعرّفات. يبقى رابط التقرير متاحًا 24 ساعة بعد الاكتمال.

يكون الصف متخطى عند فشل التحقق (معرّف مفقود أو مستخدم غير معروف في استيراد حدث أو حقل كيان مطلوب مفقود)؛ بينما يحسب فاشل أخطاء الكتابة الفعلية.

شريحة لجهات اتصال عملية استيراد​

كل جهة اتصال ينشئها أو يحدّثها استيراد جهات اتصال تُوسَم بتلك العملية. افتح عملية استيراد جهات اتصال مكتملة عبر View وانقر إنشاء شريحة: تنشئ Joryio شريحة باسم Imported: <file name> (<date>) بشرط واحد - جاء من استيراد هو هذه العملية - وتفتحها، جاهزة للمعاينة أو التحسين أو الاستخدام كجمهور. يظهر الزر فقط لمن يملك صلاحية إنشاء الشرائح.

الشرط نفسه متاح في كل شريحة وجمهور حملة وجمهور رحلة، حيث يمكنك اختيار عدة عمليات استيراد معًا أو استبعادها - راجع جاء من استيراد.

جهات الاتصال المستوردة قبل إطلاق هذه الميزة غير موسومة - لم يكن النظام يسجل أي عملية استيراد لمستها - لذلك لا تطابق شريحة عملية استيراد قديمة أحدًا؛ استورد الملف مرة أخرى لوسم جهات اتصاله. استيراد الأحداث والكيانات لا يَسِم جهات الاتصال.

صفحات ذات صلة​