Tracker.js

tracker.js הוא החלק הדפדפני של Agent Analytics. השתמשו בו כשאתם רוצים צפיות דף, אירועים מותאמים אישית וניסויים בצד הלקוח בלי לשלוח SDK כבד.

עיון ה-API מתייחס עכשיו ל-GET /tracker.js כנקודת הקצה של הסקריפט בלבד. מדריך ההגדרה והיכולות נמצא כאן.

סניפט בסיסי

הוסיפו את זה לפני </body>:

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="my-site"
        data-token="aat_..."></script>

מאפיינים נדרשים:

data-project: שם הפרויקט שלכם
data-token: טוקן הפרויקט הציבורי (aat_*)

הטרקר שולח אוטומטית page_view ראשוני עם URL ו-referrer מנוקים, pathname, hostname, כותרת, גודל מסך, דפדפן, מערכת הפעלה, מכשיר, שפה, אזור זמן, מספר session, ימים מאז הביקור הראשון ו-UTM attribution מתוך allowlist. אין צורך בעוגיות.

חוזה פרטיות

Agent Analytics מפריד בין חוזה ברירת המחדל בדפדפן לבין opt-ins מפורשים:

תחום	התנהגות ברירת מחדל	Opt-ins מפורשים
צפיות דף	נשלח `page_view` ראשוני אחד בטעינה. `url` ו-`referrer` מנוקים ל-`origin + pathname`; שדות ה-URL האוטומטיים לא שולחים query strings או fragments. `path` הוא ה-pathname הנוכחי.	מאזיני route ב-SPA דורשים `data-track-spa="true"`. עמודים וירטואליים ידניים אפשר לשלוח עם `aa.page(name)` או `aa.track('page_view', ...)`.
Attribution	רק `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` ו-`utm_term` נקראים מה-query string. הם נשמרים ל-session הנוכחי ול-first touch. פרמטרי query אחרים לא נאספים אוטומטית.	הוסיפו שדות campaign מותאמים אישית בעצמכם עם `aa.track(...)` רק כשהם בטוחים ומכוונים.
שדות דפדפן	נכללים משפחת/גרסת דפדפן, מערכת הפעלה, סוג מכשיר גס, שפה, אזור זמן, hostname, כותרת וגודל מסך. הטרקר לא משתמש ב-fingerprinting חזק, טעינת סקריפטים דינמית, `eval`, `document.write` או איסוף ערכי טפסים.	ביצועים, Web Vitals, שגיאות, עומק גלילה, 404, הורדות, מטא-דאטה של שליחת טפסים, קישורים יוצאים וקליקים כלליים כבויים עד שמוגדרים מאפייני `data-track-*` המתאימים.
קליקים וטפסים	קליקים דקלרטיביים של `data-aa-event` שולחים רק את שם האירוע ומאפייני `data-aa-event-*` שהוספתם במפורש.	`data-track-clicks="true"` עוקב אחרי מטא-דאטה של קישורים/כפתורים, אבל לא אחרי טקסט הקליק הגלוי. `data-track-forms="true"` עוקב אחרי מטא-דאטה של טפסים, אבל לא אחרי ערכי טפסים.
זהות	מזהים אנונימיים ומזהי session נשמרים ב-browser storage בטווח טוקן/שם הפרויקט. מפתחות ישנים ללא scope לא מועברים, ולכן אחרי שדרוג עשוי להיווצר מזהה אנונימי חדש בטווח הפרויקט.	`aa.identify(userId, traits)` הוא explicit-only. השתמשו ב-app/account ID יציב בתור `userId`; העבירו אימייל רק כ-`traits.email` ברמה העליונה כשנדרש lookup לתמיכה בצד השרת.
Email lookup	אימייל לא נאסף אוטומטית ולא צריך לשמש כ-`userId`.	כאשר `traits.email` מועבר ל-`identify`, האימייל הגולמי נשלח ב-HTTPS באותה קריאת identify כדי שהשרת יחשב אינדקס HMAC lookup בטווח הפרויקט. אימייל גולמי מוסר כברירת מחדל משורות event ומ-profile traits.
זהות חוצת-דומיינים	כברירת מחדל אין link decoration.	`data-link-domains` מקשט קישורים חוצי-דומיינים מותרים עם פרמטר `_aa` קצר של מזהה אנונימי, ואז מסיר אותו ביעד.
Consent ו-DNT	המעקב מתחיל מיד אלא אם מגדירים consent או DNT.	`data-require-consent="true"` מחזיק אירועים בבאפר עד `aa.grantConsent()`. `data-do-not-track="true"` מכבד את אות ה-DNT של הדפדפן.

תעבורה אוטומטית שמגיעה לטרקר מסוננת מהאנליטיקה הרגילה שלכם. השתמשו ב-Bot Traffic אם אתם רוצים לבדוק את הבקשות האוטומטיות בנפרד.

אם הסוכן שלכם יכול לערוך קוד, בקשו ממנו להוסיף עבורכם את הסניפט. אם לא, השתמשו ב-הפרויקט הראשון ב-5 דקות כדי ליצור את הפרויקט, לקבל את הסניפט ולאמת את ה-page view הראשון.

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

Attribute	מה זה עושה
`data-link-domains="example.com"`	מחבר זהות אנונימית בין דומיינים או תתי-דומיינים אחים
`data-do-not-track="true"`	מכבד את אות Do Not Track של הדפדפן
`data-heartbeat="15"`	מודד זמן פעיל בדף בזמן שהטאב גלוי
`data-track-outgoing="true"`	עוקב אחרי קליקים על קישורים חיצוניים בתור `outgoing_link`
`data-track-clicks="true"`	עוקב אחרי קליקים על `<a>` ו-`<button>` בתור `$click`
`data-track-errors="true"`	לוכד שגיאות JS לא מטופלות ו-promise rejections בתור `$error`
`data-track-performance="true"`	מוסיף מדדי Navigation Timing ל-`page_view`
`data-track-vitals="true"`	מוסיף Core Web Vitals ל-`page_view`
`data-track-downloads="true"`	עוקב אחרי קליקים על קישורי הורדה בתור `$download`
`data-track-forms="true"`	עוקב אחרי שליחת טפסים בתור `$form_submit`
`data-track-404="true"`	עוקב אחרי דפי 404 בתור `$404`
`data-track-scroll-depth="true"`	מוסיף עומק גלילה מקסימלי ל-`page_view`
`data-track-spa="true"`	מאזין לשינויי route בצד הלקוח ושולח אירועי `page_view` של שינוי route
`data-require-consent="true"`	מחזיק אירועים בבאפר עד שניתן consent

דוגמה:

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="my-site"
        data-token="aat_..."
        data-track-outgoing="true"
        data-track-performance="true"
        data-track-vitals="true"
        data-track-errors="true"
        data-track-scroll-depth="true"
        data-heartbeat="15"></script>

אירועים דקלרטיביים

למעקב קליקים פשוט, לרוב לא צריך JavaScript מותאם אישית. הוסיפו data-aa-event ישירות ל-HTML:

<button data-aa-event="signup_cta_clicked" data-aa-event-plan="pro">
  Sign up for Pro
</button>

זה ישלח אירוע signup_cta_clicked עם { plan: "pro" }.

ברוב המקרים זהו גם המסלול הקל ביותר לסוכנים. הם יכולים להוסיף מאפיינים ל-markup קיים במקום לחווט onclick handlers או לערוך קוד אפליקציה.

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

חשיפות

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

<section data-aa-impression="pricing_table"
         data-aa-impression-plan="pro">
  ...
</section>

כשהאלמנט הופך לגלוי, הטרקר שולח אירוע $impression.

API של `window.aa`

השתמשו ב-JavaScript API כשהאירוע תלוי במצב runtime:

window.aa?.track('checkout_started', { plan: 'pro' });
window.aa?.identify('user_123', { email: '[email protected]', plan: 'pro' });
window.aa?.set({ plan: 'pro', team: 'acme' });

שיטות שימושיות:

aa.track(event, properties): שליחת אירוע מותאם אישית
aa.page(name): שליחת page view ידנית
aa.identify(id, traits): קישור התנהגות אנונימית למזהה משתמש יציב ועדכון אינדקס lookup פרטי למסעות תמיכה
aa.set(properties): צירוף מאפיינים גלובליים לאירועים עתידיים
aa.experiment(name, variants): שיוך וריאנטים בצד הלקוח בצורה דטרמיניסטית
aa.grantConsent() / aa.revokeConsent(): ניהול מצב consent

אפליקציות עם הזדהות: `signup`, `login` ו-`identify`

באפליקציות עם חשבונות, הצעד הדפדפני הנכון אחרי auth הוא:

window.aa?.identify(account.id, {
  email: account.email,
  plan: account.plan,
  team: account.team,
});

קראו ל-aa.identify(account.id, traits) מיד אחרי שה-auth מצליח ולפני aa.set(...) או כל אירוע דפדפני אחר אחרי ההתחברות. כך הפעילות הנוכחית בדפדפן נתפרת לאותו מזהה משתמש קנוני שגם השרת צריך להשתמש בו. השתמשו במזהה משתמש/חשבון יציב כארגומנט הראשון, לא בכתובת אימייל. העבירו אימייל רק כ-traits.email כאשר צריך lookup עתידי לצורכי תמיכה.

כאשר traits.email קיים, האימייל הגולמי נשלח ב-HTTPS בזמן identify כדי ש-Agent Analytics יחשב אינדקס HMAC scoped בצד השרת. אימייל גולמי לא נשמר בשורות event או ב-profile traits כברירת מחדל; הנחיות לדפדפן לבצע SHA-256 ולשלוח email_hash אינן חלק מהחוזה הציבורי.

גבולות מומלצים לאירועים:

שלחו signup פעם אחת בדיוק, כשנוצר החשבון. עדיף בנתיב השרת שיוצר את החשבון.
שלחו login כשחשבון קיים מסיים auth. עדיף גם כאן ב-callback של auth או בנתיב שיוצר את הסשן.
השתמשו באירועים צד-לקוח כמו signup_started, signup_cta_clicked או checkout_started לשלבים מוקדמים יותר ב-UI, לפני שהחשבון בכלל קיים.

ההפרדה הזאת שומרת על funnel אמין ודואגת לכך שאירועי הדפדפן ואירועי ה-auth מהשרת ינחתו על אותו user_id.

ניתוב SPA ועמודים וירטואליים

כברירת מחדל, Agent Analytics שולח רק את ה-page view הראשוני. מעקב route אוטומטי ב-SPA הוא עכשיו opt-in מפורש, כי הוא מאזין לשינויי URL ומבצע patch ל-history.pushState() / history.replaceState().

כדי להפעיל page views אוטומטיים לשינויי route, הוסיפו data-track-spa="true":

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="my-site"
        data-token="aat_..."
        data-track-spa="true"></script>

עם ה-opt-in הזה, Agent Analytics שולח page_view כשה-URL בדפדפן משתנה דרך history.pushState(), history.replaceState(), אירועי popstate או hashchange. זה מכסה את רוב ה-client-side routers, כולל SPAs מבוססי hash.

אם ה-UI משתנה בלי שינוי ב-path, ב-query string או ב-hash, הטרקר לא מנסה לנחש שמסך חדש הופיע. במקרה כזה צריך לשלוח page_view ידני.

סדר ההעדפה ליישום:

שינויי URL אמיתיים
ניתוב hash
page_view וירטואלי ידני

השתמשו ב-aa.page(name) כשה-URL הנוכחי בדפדפן כבר תואם למסך שאתם רוצים לתייג. הוא שולח page_view עם מאפיין page, אבל path ו-url עדיין מגיעים מהמיקום הנוכחי של הדפדפן.

לעמודים וירטואליים אמיתיים בלי שינוי URL, שלחו page_view ידני ועקפו בעצמכם את שדות הניתוב:

window.aa?.track('page_view', {
  page: 'Checkout Step 2',
  path: '/checkout/step-2',
  url: `${location.origin}/checkout/step-2`
});

אל תשלבו מעקב דפים ידני עם מעברי router ש-Agent Analytics כבר מודד אוטומטית, אחרת תספרו את אותו שינוי מסך פעמיים.

אם אתם רוצים workflow מבוסס-פרומפטים לבחירה בין מעקב router למעקב עמודים וירטואליים, השתמשו ב-מעקב SPA ועמודים וירטואליים.

מתכונים נפוצים

זהות חוצת-דומיינים

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="my-site"
        data-token="aat_..."
        data-link-domains="example.com,app.example.com,docs.example.com"></script>

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="my-site"
        data-token="aat_..."
        data-do-not-track="true"
        data-require-consent="true"></script>

window.aa?.grantConsent();
window.aa?.revokeConsent();

כאשר consent מאושר, אירועים שנאגרו נשלחים אוטומטית. אם המאגר כולל יותר מ-100 אירועים, ה-tracker מפצל אותו לכמה בקשות /track/batch של עד 100 אירועים בכל בקשה.

ניסויים

<h1 data-aa-experiment="hero_text"
    data-aa-variant-b="Try it free today!">
  Start your free trial
</h1>

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

פיתוח מקומי

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