דלג לתוכן הראשי

ייבוא מרוכז (CSV / JSON)

ייבוא מרוכז מאפשר לטעון אל Joryio נתונים מקובץ: פרופילי משתמשים, אירועים היסטוריים או רשומות של הישויות המותאמות שלכם. פתחו את Data → Bulk Import ‏(/users/import) בלוח הבקרה, גררו קובץ CSV או JSON ומפו את העמודות. Joryio תעבד את הקובץ ברקע בזמן שתעקבו אחר ההתקדמות.

לא אותו דבר כמו Data Import

דף זה עוסק בהעלאת קבצים. מחבר Data Import הנפרד תחת Data → Data Import מושך נתוני משתמשים ממחסני נתונים (Snowflake, BigQuery) דרך חיבור שמגדירים פעם אחת. השתמשו ב-Bulk Import לקבצים חד-פעמיים - ייצוא CRM, רשימה ישנה או השלמת אירועי עבר; השתמשו ב-Data Import כשמקור האמת נמצא במחסן נתונים.

דרישות קובץ​

פורמטים.csv (השורה הראשונה = כותרות עמודות; מופרד בפסיקים, בנקודה-פסיק או בטאבים; UTF-8, עם או בלי BOM) או .json (מערך של אובייקטים - כל מבנה אחר נדחה).
גודל העלאהעד 100 MB לקובץ דרך לוח הבקרה.
שורותעד 1,000,000 שורות לייבוא (בצד השרת; שורות מעבר לתקרה לא מעובדות).
מקביליותייבוא אחד בכל רגע לכל סביבת עבודה - התחלת ייבוא שני בזמן שאחד מעובד נדחית.

הקבצים מועלים ישירות לאחסון דרך כתובת URL שנחתמה מראש, ולאחר מכן תהליך רקע מעבד את המשימה. הקבצים שהועלו נמחקים בתום העיבוד, ובכל מקרה תוקפם פג לאחר 24 שעות.

סוגי ייבוא​

בחרו את הסוג לפני ההעלאה - הבחירה קובעת אילו יעדי מיפוי יהיו זמינים:

  • Users - יצירה או עדכון של פרופילי אנשי קשר.
  • Events - טעינת אירועים היסטוריים למאגר האנליטיקה.
  • Entities - טעינת רשומות לאחת מהישויות המותאמות שלכם (בחרו את הישות הרצויה).

מיפוי עמודות​

הייבוא מתבצע בשני שלבים.

שלב 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מזהי קשר. אימייל עובר לאותיות קטנות וניקוי רווחים; טלפון מנורמל ל-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 נכתבת לאיש הקשר שהשורה התאימה או יצרה, אבל לא משמשת למציאת איש קשר.
  • התאמה מעדכנת את הפרופיל הקיים (נכתבים רק השדות שקיימים בשורה - מאפיינים שאינם בקובץ נשארים כפי שהם).

סיכום הייבוא מדווח על שתי התוצאות בנפרד: Created ו־Updated. אפשר לייבא שוב את אותו קובץ בבטחה: הרשומות הקיימות פשוט מתעדכנות.

כשכמה אנשי קשר חולקים אימייל​

כתובת אימייל אינה ייחודית בסביבת עבודה - זוג או משפחה יכולים לחלוק כתובת אחת, ואדם אחד יכול להופיע תחת שני מזהי משתמש. כששורה כוללת אימייל בלי externalId, ויותר מאיש קשר אחד משתמש באימייל הזה:

  • מתעדכן בדיוק איש קשר אחד: זה שהיה פעיל לאחרונה - איש הקשר שהפרופיל שלו השתנה לאחרונה (בתיקו, זה שנוצר אחרון). אותו קובץ בוחר תמיד באותו איש קשר.
  • האחרים נשארים כפי שהם. ייבוא אף פעם לא ממזג אנשי קשר ואף פעם לא מעדכן את כולם - אחרת שם בשורה היה דורס את השם של אדם אחר.
  • ביטול הרשמה בשורה חל על כל אנשי הקשר עם האימייל הזה, כמתואר באנשי קשר כפולים.
  • הרשמה בשורה חלה רק על איש הקשר שעודכן. הרשמה מחדש היא לכל איש קשר בנפרד; שאר אנשי הקשר שומרים על הסטטוס שלהם.
  • סיכום הייבוא מציג כמה שורות התאימו לכמה אנשי קשר, והדוח להורדה מפרט כל אחת מהן כ-notice - לא שגיאה, כי השורה יובאה.

כדי לעדכן איש קשר מסוים במדויק, כללו עמודת externalId: שורה עם externalId תמיד מתאימה לאיש קשר אחד בלבד. סנכרוני מחסני נתונים (Data Import) מתאימים שורות באותו אופן.

סטטוסי הרשמה והגנה על הסכמה​

תאי הסטטוס מקבלים כמה צורות כתיבה: ‏subscribed / true / yes / 1 פירושם רשום; ‏unsubscribed / false / no / 0 / opt_out פירושם ביטול הרשמה; ‏opted_in / double_opt_in / confirmed פירושם הצטרפות מאושרת. ערכים ריקים או לא מזוהים אינם משנים את הערוץ.

כברירת מחדל (תיבת הסימון כבויה) חלים כללי הגנה על הסכמה, פר ערוץ ופר קבוצה:

  • ביטולי הרשמה בקובץ תמיד חלים.
  • מי שביטל הרשמה בעבר לעולם לא נרשם מחדש באמצעות ייבוא ללא פעולה מפורשת.
  • הצטרפות מאושרת (opt-in) לעולם אינה מוחלשת להרשמה רגילה.

סימון "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 הפעיל: מגבלות על גודל, מספר מפתחות ועומק, וכן הסתרת PII.
  • אפשר להריץ את הייבוא שוב בבטחה: הרצה חוזרת של אותה משימה אינה יכולה להוסיף את אותם אירועים פעמיים.

אירועים מיובאים נכנסים לאותו זרם אירועים כמו אירועים בזמן אמת, ולכן זמינים לסגמנטים ולאנליטיקה.

ייבוא ישויות​

בחרו תחילה את ישות היעד; השדות שלה יהפכו ליעדי המיפוי. בלי מיפויים, העמודות מותאמות ישירות לשמות השדות של הישות. המערכת מדלגת עם שגיאה על שורות שחסר בהן שדה חובה. שורה שכוללת עמודת _id או id מבצעת upsert (מעדכנת רשומה קיימת או יוצרת אותה); אחרת נוספת רשומה חדשה. ניהול הגרסאות והמחיקה הרכה פועלים לפי הגדרות הישות.

מעקב אחר ייבוא​

טבלת Recent Imports מציגה כל משימה עם הסוג, הפורמט, סרגל ההתקדמות, הסטטוס ומי שהתחיל אותה. הטבלה מתרעננת אוטומטית כל עוד משימה כלשהי פועלת. הסטטוסים האפשריים הם:

סטטוסמשמעות
Pending / Processingהמשימה נכנסת לתור ולאחר מכן מעבדת את הקובץ באצוות.
Completedהסתיים - בדקו את המונים פר-שורה.
Failedהמשימה עצמה נכשלה (למשל הקובץ שהועלה לא נמצא); הודעת השגיאה מוצגת. המערכת מנסה משימות שנכשלו פעם נוספת באופן אוטומטי לפני שהן מגיעות לכאן.
Expiredמשימה ישנה שהושלמה ושהקובץ ודוח השגיאות שלה נוקו (24 שעות).

לחצו View על משימה לחלון הפרטים: סך השורות, המונים Created / Updated / Skipped / Failed, מספר השורות שהתאימו לכמה אנשי קשר, וכשהיו שורות עם בעיות או הודעות - קישור הורד דוח שגיאות (הורד דוח כשהוא כולל גם הודעות). בדוח שורה אחת לכל רשומה: המספר שלה, הסוג (error - השורה לא נכתבה, או notice - היא נכתבה אבל כדאי לבדוק אותה) והסיבה; ערכי מזהים מוסתרים. קישור הדוח זמין 24 שעות מההשלמה.

שורה נחשבת Skipped כשהיא נכשלת באימות (מזהה חסר, משתמש לא מוכר בייבוא אירועים או שדה חובה חסר בישות); ‏Failed מציין שגיאות כתיבה בפועל.

סגמנט של אנשי הקשר מייבוא​

כל איש קשר שייבוא אנשי קשר יוצר או מעדכן מסומן בייבוא הזה. פתחו ייבוא אנשי קשר שהסתיים עם View ולחצו על צור סגמנט: Joryio יוצרת סגמנט בשם Imported: <file name> (<date>) עם תנאי יחיד - הגיע מייבוא הוא הייבוא הזה - ופותחת אותו, מוכן לתצוגה מקדימה, לחידוד או לשימוש כקהל. הכפתור מוצג רק למי שיכול ליצור סגמנטים.

אותו תנאי זמין בכל סגמנט, קהל קמפיין וקהל מסע, שם אפשר לבחור כמה ייבואים בבת אחת או להחריג אותם - ראו הגיע מייבוא.

אנשי קשר שיובאו לפני שהיכולת הזו שוחררה אינם מסומנים - המערכת לא תיעדה איזה ייבוא נגע בהם - ולכן סגמנט של ייבוא ישן לא תואם אף אחד; ייבאו את הקובץ שוב כדי לסמן את אנשי הקשר שלו. ייבואי אירועים וישויות אינם מסמנים אנשי קשר.

דפים קשורים​