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

אירועים הם חומר הגלם של כל דבר ב-Joryio: סגמנטים, טריגרים של מסעות, מסנני קמפיינים ואנליטיקה - כולם פועלים על האירועים שהאפליקציות שלכם שולחות. מדריך זה מרכז את המוסכמות והמנגנונים המשותפים לכל ה-SDKs - Web, iOS, Android ו-React Native. להתקנה ולהגדרות ספציפיות לפלטפורמה, ראו את דפי ה-SDK הנפרדים.

איך המעקב עובד

כל SDK עוקב אחרי אותו מסלול:

1. אתם קוראים ל-track(eventName, properties) באפליקציה.
2. ה-SDK מוסיף את האירוע לתור מקומי (עם שמירה למצב לא-מקוון) ושולח אותו באצוות - כברירת מחדל כל 5 שניות או כל 50 אירועים, המוקדם מביניהם.
3. האצווה נשלחת אל POST /v1/track/batch, עם אימות באמצעות מפתח ה-SDK של האפליקציה (בפורמט jry_sdk_<platform>_<random>, מפתח אחד לכל אפליקציה - ראו סקירת אפליקציות).
4. השרת מזהה את המשתמש (אנונימי או מזוהה), שומר את האירועים ומפיץ אותם לסגמנטים, לטריגרים של מסעות ולאנליטיקה.

אצווה יכולה להכיל עד 500 אירועים. חותמת הזמן נקבעת על ידי ה-SDK בזמן הקריאה; השרת מקבל epoch במילישניות או מחרוזת ISO-8601, ומשתמש בזמן השרת אם חותמת הזמן חסרה או לא תקינה (כך ששעון מכשיר שגוי לעולם לא גורם לדחיית אירוע).

מוסכמות שמות לאירועים

שם אירוע הוא מחרוזת של עד 255 תווים. מעבר לכך, Joryio לא כופה פורמט - אבל עקביות חשובה, כי שמות האירועים הם הדרך שבה תמצאו אירועים אחר כך בבניית סגמנטים, בטריגרים של מסעות וב-Event Explorer.

המלצות:

• השתמשו ב-Title Case עם רווחים. האירועים המובנים של Joryio עוקבים אחר טקסונומיית אירועי המסחר המקובלת בתעשייה (עצם + פועל בזמן עבר, Title Case): ‏Product Viewed, ‏Product Added, ‏Checkout Started, ‏Order Completed מאינטגרציות החנות, כך ששמות Title Case לאירועים מותאמים (Trial Started, ‏Signup Completed) שומרים על קטלוג אחיד. גם snake case עובד - אבל בחרו מוסכמה אחת והיצמדו אליה; ערבוב יוצר אירועים שנראים כפולים.
• תנו שם לפעולה, לא לממשק. Order Completed ישרוד עיצוב מחדש; Green Button Clicked לא.
• השתמשו בעצם + פועל בזמן עבר. Subscription Upgraded, Video Played, Search Performed.
• שמרו את השונות במאפיינים, לא בשמות. אירוע Product Viewed אחד עם מאפיין category עדיף על חמישים אירועי Viewed <Category> - סגמנטים וטריגרים מתאימים קודם לפי שם האירוע ורק אחר כך מסננים לפי מאפיינים.
• הימנעו מאירועים כלליים מדי. Clicked בלי מאפיינים לא אומר לכם שום דבר שאפשר לפעול לפיו.

שמות אירועים רגישים לאותיות גדולות/קטנות: order_placed ו-Order_Placed הם שני אירועים שונים.

מאפיינים וסוגי נתונים

מאפיינים הם אובייקט JSON שמצורף לכל אירוע. כל ערך JSON תקין מתקבל:

סוג	דוגמה	הערות
מחרוזת	"currency": "USD"	השתמשו בה גם לתאריכים, כמחרוזות ISO-8601
מספר	"total": 149.99	מספרים שלמים ועשרוניים
בוליאני	"first_order": true
מערך	"item_ids": ["SKU-1", "SKU-2"]
אובייקט	"shipping": { "method": "express" }	מותר קינון של אובייקטים

מגבלות בצד השרת לכל אירוע:

מגבלה	ערך
אורך שם האירוע	255 תווים
גודל כולל של המאפיינים (JSON מסודר)	50 KB
מספר מפתחות ברמה העליונה	200
עומק קינון	5 רמות
אירועים בבקשת אצווה אחת	500

אירועים שחורגים מהמגבלות נדחים. לשמות מאפיינים חלה אותה עצה כמו לשמות אירועים: בחרו מוסכמה (product_id, לא לפעמים productId) ושמרו על סוגים יציבים - order_id שהוא מחרוזת באירוע אחד ומספר באירוע אחר הופך את הסינון ללא אמין.

מאפיינים עם קידומת $ (כמו $platform, $session_id, $app_id) מתווספים אוטומטית - חלקם על ידי ה-SDKs ($device_id, נתוני מכשיר ב-Session Start) וחלקם על ידי צינור הקליטה של Joryio בעת קבלת האירוע ($app_id, $session_id, $is_identified). התייחסו לקידומת הזו כשמורה ואל תשתמשו בה למאפיינים שלכם.

כללי שמות למאפייני משתמש

למפתחות של מאפיינים (האובייקט שמועבר ל־setAttributes / setAttribute) יש שתי מגבלות נוספות מעבר לעצות לעיל, ומפתח שמפר אחת מהן נשמט - שאר הקריאה נשמרת כרגיל:

אסור	הסיבה
. בכל מקום במפתח	הנקודה נקראת כמפריד נתיב, לא כתו. "profile.email" היה נשמר כמבנה מקונן profile: { email }, ולכן סגמנט על profile.email לא היה מוצא דבר - בלי שום דרך להבין למה.
$ בתחילת המפתח	שמור, בדיוק כמו במאפייני אירוע למעלה.
מפתח ריק	אין מה לשמור.

המפתחות נשמטים ולא משתנים - בכוונה: שינוי profile.email ל־profile_email היה מדווח על הצלחה ושומר את הנתונים במקום שלעולם לא תשאילו. המפתחות שנשמטו מופיעים בלוג של השרת, וה־SDK מתריע עליהם בקונסולה בזמן האינטגרציה.

identify מול track

לשתי הקריאות המרכזיות יש תפקידים שונים:

• identify(userId) אומר מי המשתמש. הוא קושר את המכשיר/סשן הנוכחי למזהה המשתמש הקבוע שלכם וממזג היסטוריה אנונימית לתוך הפרופיל. מאפיינים שנקבעים עם setAttributes מתארים את המשתמש (אימייל, תוכנית, שם) ונשמרים בפרופיל.
• track(eventName, properties) אומר מה קרה. המאפיינים מתארים את האירוע, לא את המשתמש, ואינם ניתנים לשינוי לאחר שנרשמו.

כללי אצבע:

• קראו ל-identify מוקדם ככל האפשר - בהתחברות, ובעליית האפליקציה אם סשן משוחזר. השתמשו באותו מזהה משתמש בכל הפלטפורמות כדי שפעילות web ומובייל תנחת על פרופיל אחד (ראו מעקב רב-פלטפורמי).
• לפני identify, אירועים נרשמים תחת מזהה אנונימי. כשאתם מזהים את המשתמש מאוחר יותר, השרת ממזג את ההיסטוריה האנונימית לתוך הפרופיל המזוהה, כך שאירועים מלפני ההרשמה (ביקור ראשון, ייחוס) לא הולכים לאיבוד.
• השתמשו ב-alias(userId) בהרשמה כדי לקשר במפורש את המשתמש האנונימי לחשבון החדש, ואז identify(userId).
• שימו נתונים של המקרה הבודד במאפייני אירוע (total, coupon), ועובדות קבועות על האדם במאפייני הפרופיל (plan, lifetime_value).
• קראו ל-reset() בהתנתקות כדי שהמשתמש הבא במכשיר לא יירש את הפרופיל.

אותו אירוע בכל SDK

קריאת track זהה בכוונה בצורתה בכל ה-SDKs. הנה אותו אירוע Order Completed בכל ארבע הפלטפורמות.

Web (JS)

import JoryioSDK from '@joryio/web-sdk';

const joryio = new JoryioSDK({ sdkKey: 'jry_sdk_web_...' });

joryio.track('Order Completed', {
  order_id: 'ORD-2024-001',
  total: 149.99,
  currency: 'USD',
  item_count: 3,
  coupon: 'SAVE10',
});

iOS (Swift)

Joryio.shared.track("Order Completed", properties: [
    "order_id": "ORD-2024-001",
    "total": 149.99,
    "currency": "USD",
    "item_count": 3,
    "coupon": "SAVE10"
])

Android (Kotlin)

Joryio.track("Order Completed", mapOf(
    "order_id" to "ORD-2024-001",
    "total" to 149.99,
    "currency" to "USD",
    "item_count" to 3,
    "coupon" to "SAVE10"
))

React Native

import Joryio from '@joryio/react-native-sdk';

Joryio.track('Order Completed', {
  order_id: 'ORD-2024-001',
  total: 149.99,
  currency: 'USD',
  item_count: 3,
  coupon: 'SAVE10',
});

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

לפעילות מסחר אלקטרוני סטנדרטית (צפיות במוצרים, עגלות, checkout, הזמנות) העדיפו את כלי המעקב המובנים למסחר אלקטרוני ב-SDKs - הם שולחים את שמות האירועים המתוקננים שיכולות המסחר האלקטרוני של Joryio מצפות להם. ראו את מדריך מעקב המסחר האלקטרוני המשותף לכל ה-SDKs.

מה קורה בצד השרת

לאחר שאצווה מתקבלת, כל אירוע:

• נשמר במאגר האנליטיקה, מוצמד לפרופיל המשתמש שזוהה (מזוהה או אנונימי).
• נבחן מול טריגרים של מסעות. מסע שטריגר הכניסה שלו תואם את שם האירוע (ואת מסנני המאפיינים) מצרף את המשתמש מיידית - כך מתחילים מסעות "עגלה נטושה" או "ברוכים הבאים".
• מזין סגמנטים. תנאי סגמנט מבוססי-אירוע ("ביצע Order Completed ב-30 הימים האחרונים") מתעדכנים מזרם האירועים, וקמפיינים שמכוונים לסגמנטים האלה קולטים את השינוי.
• מופיע באנליטיקה - ב-Event Explorer, במשפכים ובאנליטיקה של כל אפליקציה.
• יכול לעדכן את הפרופיל. לחלק מהאירועים יש השפעות צד שמנוהלות בצד השרת: לדוגמה, אירועי Session Start מרעננים את רשומת המכשיר של המשתמש ומעדכנים מאפייני פרופיל כמו country (הנגזרת מכתובת ה-IP של הבקשה).

שתי התנהגויות בצד השרת שכדאי להכיר:

• סימון בוטים. בקשות מ-user agents של בוטים מוכרים מסומנות (האירועים מתויגים, והאנליטיקה מסננת אותם); קריאות שמשנות פרופיל כמו identify ו-setAttributes מדולגות עבור בוטים. תעבורה מדפדפנים headless באוטומציית הבדיקות שלכם עשויה לכן לא ליצור פרופילים.
• אימות סלחני. שדות נוספים שאינם מוכרים במטען הבקשה מוסרים במקום להידחות, כך שאי-התאמה בגרסת SDK אינה גורמת לאובדן האירועים שלכם.

אימות ודיבוג

בדיקה שאירוע הגיע

1. הפעילו את האירוע באפליקציה.
2. בלוח הבקרה של Joryio, פתחו את Analytics → Event Explorer. סננו לפי שם האירוע - האירוע אמור להופיע שניות לאחר שה-SDK שולח את האצווה (מרווח שליחה ברירת מחדל: 5 שניות).
3. לתצוגה לפי אפליקציה, פתחו את Settings → Apps ולחצו על View Analytics באפליקציה - מוצגים סך האירועים, חותמת הזמן של האירוע האחרון ושמות האירועים המובילים, מה שמאשר במהירות אם משהו ממפתח ה-SDK הזה בכלל מגיע.

אם אירועים לא מופיעים

• כפו שליחה מיידית. אירועים נשלחים באצוות; קראו ל-flush() (זמין בכל SDK) כדי לשלוח מיד במקום לחכות לטיימר.
• הפעילו רישום ניפוי שגיאות. בכל SDK יש אפשרות enableDebug שרושמת כל אירוע שנכנס לתור וכל בקשת רשת עם התשובה שלה.
• בדקו את מפתח ה-SDK. הוא חייב להתאים לפלטפורמת האפליקציה - jry_sdk_web_... ל-Web SDK, jry_sdk_ios_... ל-iOS, jry_sdk_android_... ל-Android. מפתח שנוצר מחדש מבטל את הישן מיידית.
• ודאו שהאפליקציה פעילה ב-Settings → Apps - אירועים שנשלחים עם מפתח של אפליקציה מושבתת נדחים.
• עקבו אחרי תשובת הרשת. תשובת אצווה כוללת success, ובכשל חלקי גם failedIndices שמציין אילו אירועים באצווה לא נשמרו. מאפיינים גדולים מדי (מעל 50 KB, מעל 200 מפתחות, או קינון עמוק מ-5 רמות) הם הסיבה הנפוצה לאירועים שנדחים.
• ב-Web בלבד: נקודות הקצה של ה-SDK מאפשרות כל origin‏ (Access-Control-Allow-Origin: *), כך ששגיאות CORS מעידות בדרך כלל על apiEndpoint שגוי או תוסף דפדפן חוסם - בדקו בקונסול. ודאו גם שהאתר רץ על HTTPS כדי ששמירת התור ב-localStorage תעבוד.
• בודקים באמצעות אוטומציה? זכרו את סימון הבוטים למעלה - אמתו עם דפדפן או מכשיר אמיתי.

קישורים רלוונטיים

• Web SDK · iOS SDK · Android SDK · React Native SDK
• אירועים מותאמים אישית
• מעקב רב-פלטפורמי