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

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

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

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

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

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

גוף הפוסט ב-JSON

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

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

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

בניגוד ל-gtag, שמגבב באופן אוטומטי פרטים רגישים שהמשתמשים סיפקו, ב-Measurement Protocol המפתח צריך לגבב את הפרטים הרגישים שהמשתמשים סיפקו באמצעות אלגוריתם גיבוב מאובטח וחד-כיווני שנקרא 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 valueUtf8 = encoder.encode(value);
  // Compute the hash (digest) using the SHA-256 algorithm.
  const hashSha256 = await subtle.digest('SHA-256', valueUtf8);
  // Convert buffer to byte array.
  const hashArray = Array.from(new Uint8Array(hashSha256));
  // Return a hex-encoded string.
  return hashArray.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 measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

// 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=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    client_id: "CLIENT_ID",
    user_id: "USER_ID",
    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 measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    client_id: "CLIENT_ID",
    user_id: "USER_ID",
    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
      }]
    }
  })
});