שילוב Web SDK

Joryio Web SDK מאפשר לעקוב אחרי התנהגות משתמשים, לשלוח אירועים ולנהל פרופילי משתמשים באתר שלכם.

התקנה

דרך npm/yarn

npm install @joryio/web-sdk
# or
yarn add @joryio/web-sdk

דרך CDN

ניתן לטעון את ה־SDK מה־CDN של Joryio דרך שני נתיבים - גרסה מקובעת (מומלץ לסביבת ייצור) או ערוץ latest (שדרוג אוטומטי, לפיתוח / פנימי).

<!-- מקובעת: בטוחה לסביבת ייצור, מטמון בלתי משתנה. משדרגים על ידי שינוי ה־URL. -->
<script src="https://cdn.joryio.com/sdk/web/1.0.0/joryio.min.js"></script>

<!-- Latest: משודרג אוטומטית בתוך ~5 דקות מכל שחרור SDK. -->
<script src="https://cdn.joryio.com/sdk/web/latest/joryio.min.js"></script>

מתי להשתמש בכל אחד

• מקובעת (/1.0.0/) - אתרי ייצור שבהם אתם רוצים שליטה דטרמיניסטית על מתי ה־SDK משודרג. החבילה מוגשת עם מטמון בלתי משתנה לשנה, כך שמבקרים חוזרים מורידים אותה פעם אחת ואין בקשת רשת בטעינות הדף הבאות.
• Latest - לוחות בקרה פנימיים, staging, ולקוחות קטנים שמוכנים לקבל עדכוני SDK אוטומטית. החבילה נשמרת במטמון למשך 5 דקות עם חלון stale-while-revalidate של שעה אחת כך שגרסאות חדשות מופצות בתוך דקות מרגע השחרור.

שדרוג אינטגרציה מקובעת. כאשר Joryio משחררת גרסת SDK חדשה, העלו את המספר ב־snippet:

<!-- לפני -->
<script src="https://cdn.joryio.com/sdk/web/1.0.0/joryio.min.js"></script>
<!-- אחרי -->
<script src="https://cdn.joryio.com/sdk/web/1.1.0/joryio.min.js"></script>

הדפדפן מתייחס ל־URL החדש כקובץ חדש, שומר אותו במטמון בלתי משתנה ומריץ את ה־SDK החדש. רשומות מטמון ישנות נשארות עד שה־TTL שלהן פג או שהמשתמש מנקה את המטמון.

אימות הגרסה שרצה אצלכם. כל תגובת SDK כוללת שתי כותרות אבחון:

כותרת	דוגמה	משמעות
X-SDK-Version-Served	1.0.0	גרסת ה־SDK שפרוסה כרגע אצל Joryio.
X-SDK-Version-Requested	1.0.0	הגרסה שה־URL של ה־snippet ביקש (רק בנתיבים מקובעים).

פתחו DevTools → Network → מצאו את joryio.min.js → Response Headers. אם Requested שונה מ־Served, ה־snippet שלכם מפנה ל־URL של גרסה ישנה יותר מהגרסה הפעילה - המבקרים שלכם עשויים לקבל את החבילה החדשה מהמטמון תחת ה־URL הישן.

התחלה מהירה

1. אתחול ה־SDK

אתחלו את ה־SDK באמצעות מפתח ה־SDK שלכם. תוכלו למצוא את המפתח בלוח הבקרה של Joryio תחת Settings → Apps.

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

// Initialize the SDK
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_your_sdk_key_here',
  enableDebug: false, // Enable debug logging in development
});

בטעינה מה־CDN במקום npm, אותה מחלקה זמינה כ־window.Joryio:

const joryio = new Joryio({
  sdkKey: 'jry_sdk_web_your_sdk_key_here',
});

2. זיהוי משתמשים

זהו משתמשים כשהם נרשמים או מתחברים:

// Identify a user
joryio.identify('user_123');

// Set profile attributes separately
joryio.setAttributes({
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  plan: 'premium',
  signupDate: '2024-01-15',
});

3. מעקב אירועים

עקבו אחרי פעולות משתמשים:

// Track a custom event
joryio.track('Product Viewed', {
  product_id: 'prod_123',
  product_name: 'Premium Plan',
  price: 99.99,
  currency: 'USD',
});

// Track page views
joryio.track('Page Viewed', {
  page: '/pricing',
  title: 'Pricing Page',
  category: 'Marketing',
});

אפשרויות תצורה

אפשרות	סוג	ברירת מחדל	תיאור
sdkKey	string	נדרש	מפתח ה־SDK מלוח הבקרה של Joryio
apiEndpoint	string	https://api-eu1.joryio.com	דריסה של כתובת הבסיס של ה־API (ברירת המחדל https://api-eu1.joryio.com); נדרש רק לבדיקות או לפריסות ייעודיות.
enableDebug	boolean	false	הפעלת יומני ניפוי שגיאות במסוף
batchFlushInterval	number	5000	תדירות שליחת אירועים באצווה (מילישניות). אירועים מתווספים לתור ונשלחים כל 5 שניות כדי לצמצם בקשות רשת.
batchSize	number	50	כמות אירועים מקסימלית בתור לפני שליחה אוטומטית. אם מצטברים 50 אירועים לפני הטיימר, הם נשלחים מיד למניעת איבוד נתונים.
sendImmediately	boolean	false	שליחת כל אירוע מיד ללא אצווה (לא מומלץ לסביבת ייצור)
sessionTimeout	number	1800000	פסק זמן סשן במילישניות (ברירת מחדל: 30 דקות). סשן חדש מתחיל לאחר תקופת חוסר פעילות זו.
trackSessionStart	boolean	true	מעקב אוטומטי אחרי אירוע "Session Start" בתחילת סשן חדש.
trackPageViews	boolean	false	מעקב אוטומטי אחרי "Page Viewed" בטעינת עמוד
captureUTM	boolean	true	לכידה אוטומטית של פרמטרי UTM מה־URL לשיוך קמפיינים
resetSessionOnNewCampaign	boolean	false	פתיחת סשן חדש כאשר פרמטרי UTM משתנים (שימושי לאנליטיקה ברמת קמפיין)
trackDeviceProperties	boolean	true	הוספת מידע מכשיר לאירוע Session Start
persistQueue	boolean	true	שמירת תור האירועים ב־localStorage כדי לשרוד רענונים
inApp.allowHtmlJsInAppMessages	boolean	false	מאפשר הודעות In-App מסוג HTML, שמריצות JavaScript שנכתב על ידי המחבר ב־iframe מבודד בדף שלכם. הודעות Native מוצגות בכל מקרה. ראו הודעות In-App.

אצווה ושליחה

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

• שליחה אוטומטית: כל batchFlushInterval מילישניות (ברירת מחדל 5 שניות)
• שליחה לפי גודל: שליחה מידית כאשר מצטברים batchSize אירועים (ברירת מחדל 50)
• שליחה ידנית: joryio.flush() שולחת אירועים בתור מיידית
• בעת יציאה מהעמוד: אירועים נשלחים אוטומטית דרך sendBeacon כשהמשתמש עוזב
• תקרת תור: התור המקומי מחזיק עד 1,000 אירועים; מעבר לכך (למשל בתקופות ארוכות ללא חיבור) האירועים הישנים ביותר נמחקים מהתור עם אזהרה בקונסול

// Send events immediately instead of batching
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sendImmediately: true  // Send each event immediately
});

// Or configure batching behavior
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  batchFlushInterval: 10000,  // Flush every 10 seconds
  batchSize: 20  // Or when 20 events accumulate
});

// Or manually flush at any time
joryio.track('Important Event', {...});
joryio.flush(); // Send now

ניהול סשנים

סשנים עוקבים אחרי פעילות רציפה ומנוהלים אוטומטית:

• פסק זמן סשן: ברירת מחדל 30 דקות ללא פעילות (sessionTimeout)
• סשן חדש מתחיל כאשר:
  1. המשתמש טוען את העמוד לראשונה
  2. פסק זמן הסשן חלף ללא אירועים
  3. המשתמש קורא joryio.reset() (למשל, ביציאה)
  4. מזוהה קמפיין חדש (אם resetSessionOnNewCampaign מופעל)

הגדרת פסק זמן סשן:

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sessionTimeout: 3600000  // 1 hour in milliseconds
});

// Or shorter session timeout
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sessionTimeout: 600000  // 10 minutes
});

טיפ

סשנים מנוהלים אוטומטית לפי פעילות המשתמש. כל אירוע מאפס את הטיימר של חוסר פעילות.

מעקב Session Start

ברירת מחדל: ה־SDK עוקב אוטומטית אחרי אירוע "Session Start" בכל פעם שמתחיל סשן חדש. האירוע הזה:

• יכול לשמש כטריגר בקמפיינים ובמסעות
• כולל הקשר סשן מלא (פרמטרי UTM, referrer, עמוד נחיתה, וכאשר trackDeviceProperties פעיל - נתוני מכשיר)
• נשמר בפרופיל המשתמש כמו כל אירוע אחר, כך שסגמנטים ואנליטיקה יכולים לספור סשנים לכל משתמש

דוגמת אירוע Session Start:

// Automatically tracked when user visits your site
{
  event: "Session Start",
  properties: {
    utm_source: "google",       // If UTM parameters present
    utm_medium: "cpc",
    utm_campaign: "spring_sale",
    referrer: "https://google.com",
    landing_page: "https://example.com/..."
  },
  userId: "user_123",           // If identified
  anonymousId: "anon_456",
  sessionId: "sess_789"
}

נתוני סשן אוטומטיים

Web SDK מעשיר אירועי Session Start בנתוני מכשיר וסביבה:

• $user_agent
• $timezone
• $screen_width / $screen_height
• $viewport_width / $viewport_height
• $language / $languages
• $platform
• $browser
• $device_id
• country (ISO-3166-1 alpha-2, נגזר מה־IP בתחילת סשן)

מקרי שימוש:

1. מסעות קבלת פנים: השתמשו ב־Session Start כטריגר של מסע כדי להגיע למשתמשים כשהם מגיעים לאתר.

2. סגמנטים מבוססי סשנים: אירועי Session Start נשמרים לכל משתמש, כך שתנאי סגמנט מבוססי אירועים יכולים לספור אותם - למשל, "ביצע Session Start לפחות 10 פעמים" (משתמשים כבדים) או "לא ביצע Session Start ב־7 הימים האחרונים" (חידוש מעורבות).

3. שיוך קמפיינים: סננו באנליטיקה על Session Start וקבצו לפי utm_campaign כדי לראות אילו קמפיינים מייצרים הכי הרבה סשנים.

כיבוי מעקב Session Start:

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  trackSessionStart: false  // Disable automatic session start events
});

הודעות In-App

ה־SDK מציג עבורכם הודעות In-App. קמפיינים מתאימים מופיעים מעצמם, וחשיפות, קליקים וסגירות נמדדים אוטומטית.

אסימוני שליחה (delivery tokens)

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

אינך צריך לעשות דבר - ה-SDK מטפל בזה עבורך. התיעוד כאן נועד להסביר מה קורה ללקוח שאינו שולח אסימון:

POST /v1/in-app/track   (no deliveryToken)
{ "success": false, "error": "A delivery token is required" }

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

אתרים שטוענים את החבילה המתארחת מ-/sdk/web/latest/joryio.min.js מקבלים זאת אוטומטית.

שני סוגי תוכן

תוכן	מה זה	איך זה מוצג
Native	נתונים מובנים - כותרת, טקסט, תמונה, כפתורים	אלמנטים רגילים ב־DOM, שנכנסים כטקסט. ללא iframe וללא הרצת סקריפט.
HTML	קוד HTML, CSS ו־JavaScript שנכתב על ידי המחבר	iframe מבודד בדף שלכם.

הפעלת הודעות HTML

הודעות HTML כבויות כברירת מחדל. הודעת HTML מריצה JavaScript שנכתב על ידי המחבר באתר שלכם, ולכן ההפעלה היא החלטה של הצוות שלכם - לא משהו שמפעילים ממערכת השיווק:

joryio.init({
  sdkKey: 'jry_sdk_web_YOUR_KEY',
  inApp: {
    allowHtmlJsInAppMessages: true,   // ברירת מחדל: false
  },
});

השארת ההגדרה כבויה אינה מבטלת הודעות In-App. הודעות Native ימשיכו להופיע, כי הן נתונים שנכתבים כטקסט ב־DOM - ללא מפרש כלשהו. קמפייני HTML מדולגים ונרשמים לקונסולה.

אם ה־Content Security Policy שלכם אוסר סקריפטים מוטבעים או תוכן ב־iframe, השאירו את ההגדרה כבויה וכתבו את הקמפיינים כהודעות Native.

עיצוב הודעות Native מה-CSS שלכם

הודעת Native היא DOM אמיתי בעמוד שלכם, לא iframe, ולכן אפשר לעצב אותה כמו כל רכיב אחר שלכם. הרנדרר מייצר נקודות אחיזה יציבות:

.joryio-inapp-native                     /* הכרטיס */
.joryio-inapp-native h2                  /* כותרת */
.joryio-inapp-native p                   /* גוף ההודעה */
.joryio-inapp-native img                 /* תמונה */
.joryio-inapp-native button.primary      /* הכפתור הראשון */
.joryio-inapp-native button.secondary    /* השאר */
.joryio-inapp-close                      /* כפתור הסגירה */
.joryio-inapp-backdrop                   /* שכבת ההכהיה */
.joryio-inapp-modal / -banner / -slideup / -fullscreen   /* לפי סוג */

עדיף להשתמש במשתנים ולא בסלקטורים. כל מה שקמפיין יכול להגדיר נקרא ממשתנה CSS, ולכן הגדרה על :root נותנת סגנון בית שקמפיין עדיין יכול לדרוס להודעה מסוימת:

:root {
  --joryio-inapp-bg: #0A1240;
  --joryio-inapp-fg: #FFFFFF;
  --joryio-inapp-primary: #00C8B7;
  --joryio-inapp-primary-fg: #041028;
  --joryio-inapp-radius: 18px;
  --joryio-inapp-font: 'Inter', system-ui, sans-serif;
  --joryio-inapp-size: 15px;
  --joryio-inapp-align: start;      /* start | center | end */
  --joryio-inapp-title-weight: 700;
}

סדר הקדימות, מהגבוה לנמוך:

1. מה שהקמפיין הגדיר ב-Style (optional) - נכתב inline על הכרטיס
2. הערכים שלכם ב-‎--joryio-inapp-*
3. ברירות המחדל של ה-SDK, שהן צבעי מערכת

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

אם בכל זאת תשתמשו בסלקטורים, שימו לב שגיליון הסגנון של ה-SDK מוזרק בזמן ההצגה ולכן מגיע אחרי שלכם בסדר המסמך, ומנצח בתיקו. הוסיפו ספציפיות - ‏.joryio-inapp .joryio-inapp-native {…} - במקום כלל של מחלקה בודדת.

כיווניות מטופלת עבורכם: הכרטיס נושא dir="auto", ולכן הודעה בעברית או בערבית מיושרת לימין ומציבה את הכפתור הראשי בימין, גם בתוך עמוד שכולו משמאל לימין.

סוגי הודעות

1. Modal - במרכז המסך עם רקע מוצל
2. Banner - בראש הדף
3. Slide-Up - התראה קטנה מלמטה
4. Full-Screen - הודעה שתופסת את כל המסך
5. Custom - הדף שלכם קובע את המיקום

Callbacks

joryio.init({
  sdkKey: 'jry_sdk_web_YOUR_KEY',
  inApp: {
    onMessageDisplay: (message) => console.log('shown', message.id),
    onMessageClick: (message, action) => console.log('clicked', action),
    onMessageDismiss: (message) => console.log('dismissed', message.id),
  },
});

תיעוד API

Initialize

const joryio = new JoryioSDK(config)

אתחול ה־SDK עם ההגדרות שלכם. הבנאי מחזיר מופע יחיד - בנייה שנייה מחזירה את המופע הקיים.

Identify

joryio.identify(userId)

שיוך מזהה משתמש לסשן הנוכחי.

פרמטרים:

• userId (string): מזהה ייחודי למשתמש

דוגמה:

joryio.identify('user_123');
joryio.setAttributes({
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
});

Track

joryio.track(eventName, properties?)

מעקב אחרי אירוע מותאם עם מאפיינים לפי הצורך.

פרמטרים:

• eventName (string): שם האירוע
• properties (object, optional): מאפייני אירוע

דוגמה:

joryio.track('Order Completed', {
  order_id: 'order_789',
  total: 149.99,
  items: 3,
});

מעקב צפיות עמוד

אפשר להפעיל מעקב אוטומטי אחר צפיות עמוד:

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

Alias

joryio.alias(newUserId)

שיוך משתמש אנונימי למזהה משתמש ידוע (שימושי אחרי הרשמה).

פרמטרים:

• newUserId (string): מזהה המשתמש החדש לשיוך

דוגמה:

// Before signup (anonymous tracking)
joryio.track('Viewed Landing Page');

// After signup
joryio.alias('user_123');
joryio.identify('user_123');
joryio.setAttributes({ email: 'user@example.com' });

Add Alias

joryio.addAlias(aliasLabel, aliasName)

הוספת כינוי עם תווית למשתמש המזוהה הנוכחי.

דוגמה:

joryio.addAlias('crm', 'crm_98765');

Reset

joryio.reset()

ניקוי סשן המשתמש הנוכחי (שימושי בעת התנתקות). מנקה גם נתוני UTM כולל attribution ראשון ואחרון.

דוגמה:

// On user logout
function handleLogout() {
  joryio.reset();
  // ... other logout logic
}

קבלת מזהה אנונימי

joryio.getAnonymousId()

מחזיר את המזהה האנונימי הנוכחי - המזהה ש־Joryio מקצה לכל מבקר לפני שהוא מזוהה. הוא נוצר באתחול הראשון, נשמר ב־localStorage, ויציב לאורך טעינות עמודים למשך כל חיי המבקר האנונימי (reset() יוצר אותו מחדש בעת התנתקות). זהו בדיוק ה־anonymousId המצורף לכל אירוע ש־track() שולח, כך שאפשר להשתמש בו כדי לקשר אירוע צד־שרת או רשומת הסכמה לאותו פרופיל.

מחזיר:

• string - המזהה האנונימי (תמיד קיים)

קראו אותו לאחר שה־SDK נטען

עם ה־snippet האסינכרוני, window.joryio הוא תור פקודות עד שה־SDK מסיים להיטען, וקריאה בתור אינה יכולה להחזיר ערך. קראו את המזהה על המופע המזוהה לאחר הטעינה, או מתוך ready() (למטה).

דוגמה:

joryio.ready(function (sdk) {
  const anonId = sdk.getAnonymousId();
  fetch('/consent', { method: 'POST', body: JSON.stringify({ anonymousId: anonId }) });
});

קבלת מזהה משתמש

joryio.getUserId()

מחזיר את מזהה המשתמש המזוהה הנוכחי, או null אם המבקר עדיין אנונימי (כלומר identify() לא נקרא).

מחזיר:

• string | null

דוגמה:

joryio.ready(function (sdk) {
  const userId = sdk.getUserId(); // null עד שתקראו ל־joryio.identify(...)
});

Ready

joryio.ready(callback)

מריץ את callback(sdk) לאחר שה־SDK נטען ואותחל. זו הדרך הבטוחה לקרוא ערך (כגון getAnonymousId() / getUserId()) שקריאת stub בתור אינה יכולה להחזיר לפני הטעינה. ה־callback מקבל את מופע ה־SDK; אם ה־SDK כבר נטען, הוא רץ מיד.

דוגמה:

joryio.ready(function (sdk) {
  console.log('anon:', sdk.getAnonymousId(), 'user:', sdk.getUserId());
});

Get UTM Data

joryio.getUTMData()

קבלת פרמטרי UTM נוכחיים, first touch ו־last touch.

החזרה:

• אובייקט עם current, firstTouch, ו־lastTouch

דוגמה:

const utmData = joryio.getUTMData();
console.log(utmData.current?.utm_source); // "google"
console.log(utmData.firstTouch?.utm_campaign); // "awareness_campaign"
console.log(utmData.lastTouch?.utm_campaign); // "conversion_campaign"

Update UTM

joryio.updateUTM()

עדכון ידני של פרמטרי UTM מה־URL הנוכחי. שימושי עבור SPA שמשנות URL ללא רענון.

דוגמה:

// React Router
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    joryio.updateUTM();
  }, [location]);
}

// Vue Router
router.afterEach(() => {
  joryio.updateUTM();
});

מאפייני מערך

joryio.addToArray(key, value)
joryio.removeFromArray(key, value)

ניהול מאפייני מערך בצורה יעילה.

פרמטרים:

• key (string): שם המאפיין
• value (any): ערך להוספה או להסרה

דוגמה:

// Add tags to user
joryio.addToArray('tags', 'vip');
joryio.addToArray('tags', 'premium');
// Result: tags = ['vip', 'premium']

// Add duplicate (no-op, prevents duplicates)
joryio.addToArray('tags', 'vip');
// Result: tags = ['vip', 'premium'] (unchanged)

// Remove tag
joryio.removeFromArray('tags', 'vip');
// Result: tags = ['premium']

// Common use cases
joryio.addToArray('interests', 'technology');
joryio.addToArray('purchasedProducts', 'prod_123');
joryio.addToArray('featureFlags', 'beta-access');

התנהגות:

• addToArray() מוסיף ערך רק אם אינו קיים (מונע כפילויות)
• addToArray() יוצר מערך חדש אם המאפיין לא קיים
• removeFromArray() מסיר את כל המופעים של הערך
• השינויים מסתנכרנים אוטומטית לצד השרת, גם למשתמשים מזוהים וגם לאנונימיים

נתוני סשן אוטומטיים

ה-Web SDK מעשיר באופן אוטומטי אירועי Session Start בנתוני מכשיר וסביבה. הערכים נשמרים בפרופיל המשתמש וברשומות המכשיר:

• $user_agent
• $timezone
• $screen_width / $screen_height
• $viewport_width / $viewport_height
• $language / $languages
• $platform
• $browser
• $device_id
• country (ISO-3166-1 alpha-2, נגזר מה־IP בתחילת סשן)

מאפייני אירוע

מאפיינים סטנדרטיים

כל אירוע שנשמר נושא את המאפיינים הבאים - $device_id מצורף על ידי ה־SDK, והשאר מתווספים על ידי צינור הקליטה של Joryio בעת קבלת האירוע:

• $device_id: מזהה מכשיר יציב לכל דפדפן (מצורף על ידי ה־SDK)
• $session_id: מזהה סשן נוכחי
• $anonymous_id: מזהה משתמש אנונימי (לפני זיהוי)
• $app_id: מזהה האפליקציה שלכם
• $app_name: שם האפליקציה שלכם
• $platform: תמיד 'web' עבור Web SDK
• $is_identified: האם המשתמש מזוהה

הקידומת $ שמורה - אל תשתמשו בה למאפיינים משלכם.

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

אפשר להוסיף כל מאפיין מותאם לאירועים:

joryio.track('Video Played', {
  video_id: 'vid_123',
  video_title: 'Product Demo',
  duration: 120,
  autoplay: false,
  // Any other custom data
});

שיטות עבודה מומלצות

1. אתחול מוקדם

אתחלו את ה־SDK מוקדם ככל האפשר באפליקציה:

// In your main app file
import JoryioSDK from '@joryio/web-sdk';

const joryio = new JoryioSDK({
  sdkKey: process.env.JORYIO_SDK_KEY,
  enableDebug: process.env.NODE_ENV === 'development',
});

2. מעקב אחרי אירועים משמעותיים

התמקדו באירועים חשובים לעסק:

// Good: Specific, actionable events
joryio.track('Trial Started', { plan: 'premium' });
joryio.track('Feature Used', { feature: 'export', format: 'csv' });

// Avoid: Overly generic events
joryio.track('Button Clicked'); // Too generic

3. שימוש בשמות עקביים

השתמשו במוסכמת שמות עקבית לאירועים ולמאפיינים:

// Good: Clear, consistent naming
joryio.track('Subscription Upgraded', {
  from_plan: 'basic',
  to_plan: 'premium',
  billing_cycle: 'monthly',
});

// Avoid: Inconsistent naming
joryio.track('upgraded_subscription', {
  FromPlan: 'basic',
  'to-plan': 'premium',
});

4. ניהול מחזור חיי משתמש

טפלו נכון בזיהוי משתמשים וניהול סשנים:

// On login
function handleLogin(userId, userInfo) {
  joryio.identify(userId);
  joryio.setAttributes({
    email: userInfo.email,
    name: userInfo.name,
  });
}

// On logout
function handleLogout() {
  joryio.reset();
}

// On signup
function handleSignup(userId, userInfo) {
  joryio.alias(userId);
  joryio.identify(userId);
  joryio.setAttributes(userInfo);
}

פתרון תקלות

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

1. בדקו את מפתח ה־SDK - ודאו שהוא מתחיל ב־jry_sdk_web_
2. בדקו את המסוף - הפעילו מצב debug כדי לראות יומנים מפורטים
3. בדקו שהאתחול הושלם - ודאו ש־new JoryioSDK(config) רץ לפני קריאה לשיטות אחרות

שגיאות CORS

נקודות הקצה של ה־SDK מחזירות Access-Control-Allow-Origin: *, כך שלא נדרש אישור דומיין. אם אתם עדיין רואים שגיאות CORS, בדקו ש־apiEndpoint מצביע על כתובת הבסיס הנכונה (https://api-eu1.joryio.com) ושהבקשה לא נחסמת על ידי תוסף דפדפן או פרוקסי שמסיר כותרות CORS.

בעיות מעקב סשן

ה־SDK משתמש ב־localStorage לשמירת סשן. ודאו:

• האתר שלכם מוגש ב־HTTPS (נדרש להקשרים מאובטחים)
• המשתמשים לא השביתו localStorage
• אתם לא קוראים ל־reset() בטעות

צעדים הבאים

• Web SDK: מעקב UTM ושיוך קמפיינים - שיוך קמפיינים, first/last touch ולכידת UTM
• מעקב מסחר אלקטרוני - אירועי מוצרים, עגלה, תשלום והזמנות
• מעקב אירועים מותאמים
• הגדרת מאפייני משתמש
• יצירת סגמנטים
• בניית קמפיינים
• E-Commerce API