יצירת אפליקציות

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

אפליקציות נוצרות בתוך סביבת עבודה, ונדרשת הרשאת כתיבה להגדרות באותה סביבת עבודה.

1. יצירת האפליקציה

1. בלוח הבקרה של Joryio, עברו אל Settings → Apps.
2. לחצו על Create App.
3. הזינו App Name - בחרו שם שקל לזהות, למשל "Production Website" או "iOS - App Store".
4. בחרו Platform: ‏Web, ‏iOS או Android. את הפלטפורמה אי אפשר לשנות אחר כך - במקרה כזה צרו אפליקציה חדשה. (אפליקציות Shopify, ‏WooCommerce ו-Magento נוצרות אוטומטית על ידי האינטגרציות שלהן, לא מהחלון הזה.)
5. לחצו ליצירה.

אם אתם משיקים בכמה פלטפורמות, צרו אפליקציה אחת לכל פלטפורמה - ראו מעקב רב-פלטפורמי. ל-React Native צרו אפליקציית iOS ואפליקציית Android.

2. העתקת מפתח ה-SDK

האפליקציה החדשה מופיעה בטבלת האפליקציות עם מפתח ה-SDK שנוצר לה, בפורמט jry_sdk_<platform>_<random>:

jry_sdk_web_4f2a9c...

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

3. חיבור ה-SDK

התקינו ואתחלו את ה-SDK שמתאים לפלטפורמת האפליקציה, עם המפתח שהעתקתם:

פלטפורמה	מדריך SDK	אתחול עם
Web	Web SDK	new JoryioSDK({ sdkKey: 'jry_sdk_web_...' })
iOS	iOS SDK	Joryio.shared.initialize(sdkKey: "jry_sdk_ios_...")
Android	Android SDK	Joryio.initialize(context, "jry_sdk_android_...")
React Native	React Native SDK	Joryio.initialize(key, apiHost) עם מפתח ה-iOS או ה-Android לפי Platform.OS

המפתח חייב להתאים לפלטפורמה - מפתח jry_sdk_web_... בתוך ה-iOS SDK לא יעקוב אחרי אירועי הגרסה הזו כאפליקציית iOS.

לאחר מכן זהו משתמשים ועקבו אחרי האירוע הראשון שלכם:

// Web SDK example - the other platforms use the equivalent calls
const joryio = new JoryioSDK({ sdkKey: 'jry_sdk_web_...' });

joryio.identify('user_123');
joryio.track('order_placed', { order_id: 'ORD-001', total: 149.99 });

4. אימות שאירועים מגיעים

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

אם שום דבר לא מופיע, עברו על רשימת הבדיקות במעקב אחר אירועים - אימות ודיבוג.

ניהול שוטף

משורת האפליקציה ב-Settings → Apps אפשר גם:

• להגדיר פרטי גישה לפוש - ‏APNS ל-iOS, ‏FCM ל-Android, או הפעלת web push ‏(VAPID) לאפליקציות web.
• להשבית אפליקציה - אירועים שנשלחים עם מפתח של אפליקציה מושבתת נדחים; אירועים היסטוריים נשמרים.
• ליצור מחדש את מפתח ה-SDK - החלפה מיידית שמבטלת את המפתח הקודם.
• להפעיל SDK Authentication - לדרוש, לפי הצורך, JWT חתום על ידכם (בכותרת X-Joryio-Auth) בכל בקשת קליטה של האפליקציה שמציינת משתמש מזוהה, ולאמת אותו מול מפתח ציבורי שאתם רושמים.
• למחוק את האפליקציה - עוצר את המעקב עבור המפתח לצמיתות; אירועים היסטוריים נשמרים.

אבטחת זהות: SDK Authentication (מומלץ)

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

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

• השרת שלכם חותם JWT קצר-מועד (RS256/ES256) שהנושא שלו הוא המשתמש המזוהה, וה־SDK שולח אותו בכותרת X-Joryio-Auth. Joryio מאמת אותו מול המפתח הציבורי שרשמתם, כך שהבקשה קשורה למשתמש מוכח. זהו המודל הסטנדרטי לאימות תעבורה של SDK בצד הלקוח.

• לאחר ההפעלה, כל בקשה שמציינת userId חייבת לשאת token תקף של אותו משתמש - בלעדיו, או עם token של משתמש אחר, היא נדחית עם 401. למבקרים אנונימיים אין token להציג, ולכן בקשות אנונימיות מתקבלות - אירועים, מאפיינים, הסכמה, רישום push, aliases ו־in-app כאחד. חריג אחד מונע מזה להפוך לדרך לעקוף את ה־token: anonymousId שכבר שייך למשתמש מזוהה אינו יכול לשמש לכתיבה לפרופיל של אותו משתמש (403 עם code: "SDK_ANONYMOUS_ID_IDENTIFIED").

• התנתקות לא מאבדת דבר. כשמשתמש מתנתק (reset()), בקשות שכבר ממתינות עבורו שומרות את הטוקן של אותו משתמש, והמשתמש הבא לעולם לא שולח אותו. ביטולים - הסרה ממנוי, תיעוד ההסרה ממעקב, ביטול רישום push - מתקבלים עם טוקן חתום כראוי עד 30 יום אחרי שתוקפו פג; כל השאר דורש טוקן בתוקף. ראו ביטולים נמסרים תמיד.

לעמדה המחמירה ביותר, הפעילו Strict SDK identity באפליקציה: היא דוחה גם כתיבות רגישות אנונימיות (הסכמה, רישום push, מאפיינים, aliases, identify) עם 403 ו־code: "SDK_STRICT_IDENTITY_REQUIRED", כך שכל אחת מהן מחייבת userId מאומת ב־SDK Authentication.

אנו ממליצים להפעיל SDK Authentication בכל אפליקציה שמאפשרת למשתמשי הקצה לנהל הסכמה או לקבל push.

בחרו userId שאי אפשר לנחש

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

משתמש תמיד יכול לקרוא את המזהה שלו מתוך התעבורה שלו. זה בלתי נמנע ואינו מזיק. מה שחשוב הוא שידיעת מזהה אחד לא תגלה לתוקף דבר על המזהה של אף אחד אחר.

הימנעו מ

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

העדיפו

• ערך אטום, אקראי, לכל משתמש - UUIDv4 שנוצר פעם אחת ונשמר על רשומת המשתמש שלכם.
• יציב לכל אורך חיי החשבון. שינוי שלו מפצל אדם אחד לשני אנשי קשר, מה ששובר היסטוריה והסכמה.

זו הגנה לעומק, לא תחליף. userId אקראי מייקר תקיפה ממוקדת; SDK Authentication מסלק את כל המחלקה הזו. אם האפליקציה שלכם מאפשרת למשתמשי הקצה לנהל הסכמה או לקבל התראות push, עשו את שניהם.

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

• סקירת אפליקציות
• מעקב רב-פלטפורמי
• מעקב אחר אירועים