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

פונקציות עזר

מדריך זה מתאר את פונקציות העזר הזמינות ב-MSQ Pixel SDK. כל הפונקציות זמינות דרך האובייקט הגלובלי window.msq_pixel (מופע של המחלקה MSQ), שנוצר אוטומטית על ידי הסקריפט.

getUrlParam(name)​

מאחזרת את הערך של פרמטר URL לפי שם. הבדיקה נעשית הן ב-location.search והן ב-location.hash. הערך מוחזר לאחר decodeURIComponent, או null אם הפרמטר לא נמצא.

שימוש ישיר​

// window.msq_pixel נוצר אוטומטית על ידי הסקריפט
var gclid = msq_pixel.getUrlParam("gclid");
console.log('gclid:', gclid);

שימוש בכללים​

var msq_phone_replace_rules = [{
  function: 'getUrlParam',
  params: {
    name: 'gclid'
  },
  callback: function(result) {
    console.log('Callback:', result);
  }
}];

pushUrlParam(name)​

קוראת את הפרמטר מה-URL ושומרת אותו ב-properties וב-sessionStorage (באמצעות pushAndStoreIfEmpty). מקבלת רק את שם הפרמטר — הערך נקרא אוטומטית מה-URL.

שימוש ישיר​

// יקרא את utm_source מה-URL וישמור אותו
msq_pixel.pushUrlParam("utm_source");

שימוש בכללים​

var msq_phone_replace_rules = [{
  function: 'pushUrlParam',
  params: {
    name: 'utm_source'
  },
  callback: function(result) {
    console.log('Callback:', result);
  }
}];
איסוף אוטומטי

פרמטרי URL נפוצים (gclid, gclsrc, dclid, wbraid, gbraid, fbclid, utm_*) נאספים אוטומטית בעת אתחול ה-SDK, אין צורך לקרוא ל-pushUrlParam עבורם.

pushAndStoreIfEmpty(name, value)​

שומרת ערך ב-properties וב-sessionStorage (מפתח פנימי MSQParam) רק אם עדיין לא קיים שם ערך שמור. שימושי לשמירת מידע מעקב בין דפים.

שימוש ישיר​

msq_pixel.pushAndStoreIfEmpty("utm_campaign", "spring_sale");

שימוש בכללים​

var msq_phone_replace_rules = [{
  function: 'pushAndStoreIfEmpty',
  params: {
    name: 'utm_campaign',
    value: 'spring_sale'
  },
  callback: function(result) {
    console.log('Callback:', result);
  }
}];

push(property, value)​

מגדירה (או מחליפה) ערך ב-properties של הפיקסל — ללא שמירה ב-sessionStorage.

msq_pixel.push('custom_param', 'custom_value');

pushAndAppend(property, value)​

אם המאפיין כבר קיים, הופכת אותו למערך ומוסיפה את הערך (ללא כפילויות). אם לא — מתנהגת כמו push.

msq_pixel.pushAndAppend('tags', 'campaign_a');
msq_pixel.pushAndAppend('tags', 'campaign_b');
// tags = ['campaign_a', 'campaign_b']

getProperty(property)​

מחזירה את הערך הנוכחי של property מהפיקסל, או null אם לא קיים.

var utm = msq_pixel.getProperty('utm_source');

onDomUpdate(reason)​

טריגר מותאם ל-SPA frameworks (React, Vue, Angular). קוראים לפונקציה זו לאחר שה-DOM התעדכן כדי להריץ מחדש את msq_phone_replace_rules (עם debounce של 100ms כך שקריאות רצופות אינן מציפות את המערכת).

// לאחר navigation ב-SPA
msq_pixel.onDomUpdate('route changed to /contact');

אם msq_phone_replace_rules לא מוגדר, הפונקציה פשוט שולחת פיקסל חדש (sendMsqPixel).

process() ו-process_async()​

  • msq_pixel.process() — מריץ את כל שלבי הדחיפה (page info, GA4, Facebook, Google Ads) ושולח את הפיקסל.
  • msq_pixel.process_async() — מחכה לטעינת סקריפטי google (עד 20 ניסיונות כל 350ms כברירת מחדל), ואז קורא ל-process(). זוהי ברירת המחדל כאשר setting_wait4async לא מוגדר במפורש כ-false.

דוגמה משולבת​

// הגדרות הפיקסל
var msq_pixel_settings = {
  setting_api_key: 'YOUR_API_KEY',
  setting_debug: true
};

// כללים משולבים
var msq_phone_replace_rules = [
  // קודם, שמור את utm_source אם לא קיים
  {
    function: 'pushAndStoreIfEmpty',
    params: {
      name: 'utm_source',
      value: 'organic'
    }
  },
  // אחר כך, בצע החלפת מספר אם יש gclid
  {
    function: 'referrer_search_and_replace',
    params: {
      conditions_filter: 'url LIKE "%gclid%"',
      search_for_number: '055-4300000',
      replace_number: '055-4311111',
      maskyoo: '055-4311111',
      stop_on_success: true
    },
    callback: function(result) {
      // קבל את ה-gclid לשימוש נוסף
      var gclid = msq_pixel.getUrlParam("gclid");
      console.log('Replacement done. gclid:', gclid);
    }
  }
];

טיפים​

  • אין צורך ליצור מופע ידני של MSQ — הסקריפט יוצר את window.msq_pixel אוטומטית לאחר טעינה.
  • השתמשו ב-callback בכללים לבדיקת תוצאות הפעולות.
  • pushAndStoreIfEmpty שימושי במיוחד לשמירת מידע מעקב בין דפים (sessionStorage).
  • ב-SPA frameworks, קראו ל-msq_pixel.onDomUpdate() לאחר כל שינוי route כדי להריץ מחדש את הכללים.

השפעות על המערכת​

פונקציות ה‑framework מאפשרות שליטה פרוגרמטית על הפיקסל:

  • איסוף פרמטרים — pushUrlParam ו‑pushAndStoreIfEmpty שומרים UTM/מזהים ב‑sessionStorage כך שיחיו לאורך הסשן ולא ייעלמו בין דפים
  • push / pushAndAppend — מוסיפים properties לפיקסל שיישלחו לשרת; נגישים אחר כך דרך get_cdr_metadata_by_call_uuid
  • onDomUpdate() — חיוני ל‑SPA (React/Vue/Angular) כדי שההחלפה תרוץ מחדש לאחר ניווט פנימי ללא reload
  • process() / process_async() — שליטה ידנית על עיתוי שליחת הפיקסל; חשוב כאשר צריך לחכות לאתחול של סקריפטים אחרים
  • CDR עשיר — properties שנדחפים כאן מופיעים כמטא‑דאטה של השיחה שתתקבל בעקבות הביקור
  • debug — שימוש ב‑callbacks בכללים עוזר לאתר שינויי זרימה; יחד עם setting_debug נוצרת שקיפות מלאה

ראו גם​