שליחת פרטים שהמשתמשים סיפקו עם User-ID באמצעות Measurement Protocol

בדומה לשימוש ב-gtag, אפשר להשתמש ב-Google Analytics Measurement Protocol ל-Google Analytics 4 כדי לשלוח פרטים שהמשתמשים סיפקו יחד עם User-ID, וכך לשפר את ההתנהגות ואת מעקב ההמרות.

כדי לשלוח פרטים שהמשתמשים סיפקו יחד עם בקשת Measurement Protocol, מוסיפים את הפרמטר user_data למטען הי��עודי (Payload) של JSON. הפרמטר user_id חייב להיות נוכח בכל פעם שמציינים user_data.

ב-Measurement Protocol נעשה שימוש באותו אלגוריתם גיבוב (hashing) ונירמול כמו בתכונה מדידה משופרת ב-Google Ads API. מטעמי שמירה על הפרטיות, צריך לבצע גיבוב של כתובות אימייל, מספרי טלפון, שמות פרטיים, שמות משפחה וכתובות של רחובות באמצעות האלגוריתם SHA-256 לפני שמעלים אותם. הערך המגובב צריך להיות מקודד בפורמט של מחרוזת הקסדצימלית (אובייקט מחרוזת שמכיל רק ספרות הקסדצימליות), כמו 88d7ecb5c5b21d7b1.

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

• מסירים רווחים לבנים בתחילת הטקסט ובסופו.
• ממירים את הטקסט לאותיות קטנות.
• מזינים מספרי טלפון בפורמט שתואם לתקן E164
• מסירים את כל הנקודות (.) שלפני שם הדומיין בכתובות אימייל gmail.com ו-googlemail.com.

גוף הפוסט בפורמט JSON

מידע נוסף על הפורמט של התעבורה והמטען הייעודי (Payload) זמין במאמרי העזרה של Measurement Protocol.

שליחת פרטים שהמשתמשים סיפקו

בניגוד ל-gtag, שמבצע גיבוב אוטומטי של פרטים רגישים שהמשתמשים סיפקו, מפתח Measurement Protocol נדרש לבצע גיבוב של פרטים רגישים שהמשתמשים סיפקו באמצעות אלגוריתם גיבוב חד-כיווני מאובטח שנקרא SHA256, ולקודד אותו בפורמט הקסדצימלי לפני שליחת הקריאה ל-API.

כל השדות של נתוני המשתמשים שמתחילים בקידומת sha256 בשם שלהם צריכים להכיל רק ערכים מגובבים (hashed) וקידוד הקסדצימלי.

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

const { subtle } = require('crypto').webcrypto;

async function populateSensitiveUserData(value) {
  const encoder = new TextEncoder();
  // Convert a string value to UTF-8 encoded text.
  const value_utf8 = encoder.encode(value);
  // Compute the hash (digest) using the SHA-256 algorithm.
  const hash_sha256 = await subtle.digest('SHA-256', value_utf8);
  // Convert buffer to byte array.
  const hash_array = Array.from(new Uint8Array(hash_sha256));
  // Return a hex-encoded string.
  return hash_array.map(b => b.toString(16).padStart(2, "0")).join('');
};

// Test the encryption function by calling it.
async function main() {
  return await populateSensitiveUserData('<value>');
}

main()
  .then(v => console.log(v))
  .catch(err => console.error(err));

בתור קיצור דרך, אפשר להעביר ערך יחיד במקום מערך בכל השדות החוזר��ם באובייקט user_data (כמו address, sha256_email_address, sha256_phone_number).

הקוד לדוגמה הבא מפעיל את ה-Measurement Protocol ומעביר את נתוני המשתמשים יחד עם User-ID.

const measurement_id = 'G-XXXXXXXXXX';
const api_secret = '<secret_value>';

// Populate mock User Data using the `populateSensitiveUserData` function defined
// above.
const yourEmailSha256Variable = await populateSensitiveUserData('test@yourdomain.com');
const yourPhoneSha256Variable  = await populateSensitiveUserData('+15555555555');
const yourFirstNameSha256Variable  = await populateSensitiveUserData('john');
const yourLastNameSha256Variable  = await populateSensitiveUserData('doe');
const yourStreetAddressSha256Variable  = await populateSensitiveUserData('123 main street');

// Populate mock unencrypted user data.
const yourCityVariable = 'san francisco';
const yourRegionVariable = 'california';
const yourPostalCodeVariable = '94000';
const yourCountryVariable = 'US';

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',
    user_id: "XXX",
    events: [{
      name: 'purchase'
    }],
    user_data: {
      sha256_email_address: yourEmailSha256Variable,
      sha256_phone_number: yourPhoneSha256Variable,
      address: {
        sha256_first_name: yourFirstNameSha256Variable,
        sha256_last_name: yourLastNameSha256Variable,
        sha256_street: yourStreetAddressSha256Variable,
        city: yourCityVariable,
        region: yourRegionVariable,
        postal_code: yourPostalCodeVariable,
        country: yourCountryVariable
      }
    }
  })
});

ערכים מרובים

מפתחים יכולים לספק ערכים מרובים (עד 3 למספר טלפון ולכתובת אימייל ו-2 לכתובת פיזית) על-ידי שימוש בערך של מערך במקום במחרוזת. אם אתם אוספים יותר מערך אחד, ציון ערכים מרובים יכול להגדיל את הסיכוי להתאמה.

const measurement_id = 'G-XXXXXXXXXX';
const api_secret = '<secret_value>';

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',
    user_id: "XXX",
    events: [{
      name: 'purchase'
    }],
    user_data: {
      sha256_email_address: [yourEmailSha256Variable1, yourEmailSha256Variable2],
      sha256_phone_number: [yourPhoneSha256Variable1, yourPhoneSha256Variable2],
      address: [{
        sha256_first_name: yourFirstNameSha256Variable1,
        sha256_last_name: yourLastNameSha256Variable1,
        sha256_street: yourStreetAddressSha256Variable1,
        city: yourCityVariable1,
        region: yourRegionVariable1,
        postal_code: yourPostalCodeVariable1,
        country: yourCountryVariable1
      },{
        sha256_first_name: yourFirstNameSha256Variable2,
        sha256_last_name: yourLastNameSha256Variable2,
        sha256_street: yourStreetAddressSha256Variable2,
        city: yourCityVariable2,
        region: yourRegionVariable2,
        postal_code: yourPostalCodeVariable2,
        country: yourCountryVariable2
      }]
    }
  })
});