שליחת פרטים שהמשתמשים סיפקו עם 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. מטעמי פרטיות, לפני שמעלים כתובות אימייל, מספרי טלפון, שמות פרטיים, שמות משפחה וכתובות רחובות צריך לבצע גיבוב (hash) באמצעות האלגוריתם SHA-256. הערך המגובב צריך להיות מקודד בפורמט הקסדצימלי (אובייקט מחרוזת שמכיל רק ספרות הקסדצימליות), כמו 88d7ecb5c5b21d7b1.

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

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

גוף פוסט ב-JSON

מפתח סוג תיאור
user_id string מזהה ייחודי של משתמש. מידע נוסף על המזהה הזה זמין במאמר User-ID לניתוח נתונים מפלטפורמות שונות.
user_data אובייקט שדות משופרים של נתוני משתמש לזיהוי המשתמש.
user_data.sha256_email_address[] מערך מחרוזות כתובת האימייל של המשתמש לאחר גיבוב וקידוד. מנורמל כך:
user_data.sha256_phone_number[] מערך מחרוזות מספר הטלפון של המשתמש לאחר גיבוב וקידוד. מנורמל כך:
  • הסר את כל התווים שאינם ספרות
  • הוספת הקידומת +
  • לבצע גיבוב (hash) באמצעות אלגוריתם SHA256
  • לקודד בפורמט הקסדצימלי של מחרוזת.
user_data.address[] מערך מזהה משתמש על סמך המיקום הפיזי שלו.
user_data.address[].sha256_first_name string השם הפרטי של המשתמש לאחר גיבוב וקידוד. מנורמל כך:
  • הסרת ספרות ותווי סמלים
  • אות ראשונה קטנה בכל המילים
  • מסירים רווחים בהתחלה ובסוף
  • לבצע גיבוב (hash) באמצעות אלגוריתם SHA256
  • לקודד בפורמט הקסדצימלי של מחרוזת.
user_data.address[].sha256_last_name string שם המשפחה של המשתמש לאחר גיבוב וקידוד. מנורמל כך:
  • הסרת ספרות ותווי סמלים
  • אות ראשונה קטנה בכל המילים
  • מסירים רווחים בהתחלה ובסוף
  • לבצע גיבוב (hash) באמצעות אלגוריתם SHA256
  • לקודד בפורמט הקסדצימלי של מחרוזת.
user_data.address[].sha256_street string רחוב ומספר המשתמש שעברו גיבוב ומקודד. מנורמל כך:
  • הסרת תווי הסמלים
  • אות ראשונה קטנה בכל המילים
  • מסירים רווחים בהתחלה ובסוף
  • לבצע גיבוב (hash) באמצעות אלגוריתם SHA256
  • לקודד בפורמט הקסדצימלי של מחרוזת.
user_data.address[].city string העיר בכתובת של המשתמש. מנורמל כך:
  • הסרת ספרות ותווי סמלים
  • אות ראשונה קטנה בכל המילים
  • מסירים רווחים בהתחלה ובסוף.
user_data.address[].region string המדינה או האזור בכתובת של המשתמש. מנורמל כך:
  • הסרת ספרות ותווי סמלים
  • אות ראשונה קטנה בכל המילים
  • מסירים רווחים בהתחלה ובסוף.
user_data.address[].postal_code string המיקוד בכתובת של המשתמש. מנורמל כך:
  • הסרת . ו-~ תווים
  • מסירים רווחים בהתחלה ובסוף.
user_data.address[].country string קוד המדינה של כתובת המשתמש. הפורמט צריך להיות תואם לתקן ISO 3166-1 alpha-2.

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

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

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

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

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

Node.js

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.

Node.js

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 לכתובת פיזית) על-ידי שימוש בערך של מערך במקום במחרוזת. אם אתם אוספים יותר מערך אחד, ציון ערכים מרובים יכול להגדיל את הסיכוי להתאמה.

Node.js

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
      }]
    }
  })
});