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

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

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

ב-Measurement Protocol נעשה שימוש באותו אלגוריתם גיבוב ונירמול בתור מדידה משופרת ב-Google Ads API . מטעמי פרטיות, כתובות אימייל, מספרי טלפון, שמות פרטיים, שמות משפחה וכתובות הבית חייבות לעבור גיבוב (hash) באמצעות הפונקציה אלגוריתם 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[] מערך מחרוזות מספר הטלפון של המשתמש לאחר גיבוב (hash) ומקודד. מנורמל כמו
  • מסירים את כל התווים שאינם ספרות
  • הוספת הקידומת +
  • גיבוב (hash) באמצעות אלגוריתם SHA256
  • לקודד בפורמט של מחרוזת הקסדצימלית.
user_data.address[] מערך מזהה משתמש על סמך מיקום פיזי.
user_data.address[].sha256_first_name מחרוזת השם הפרטי של המשתמש לאחר גיבוב וקידוד. מנורמל כמו
  • הסרת ספרות ותווים של סמלים
  • אות ראשונה קטנה בכל המילים
  • מסירים רווחים בהתחלה ובסוף
  • גיבוב (hash) באמצעות אלגוריתם SHA256
  • לקודד בפורמט של מחרוזת הקסדצימלית.
user_data.address[].sha256_last_name מחרוזת שם המשפחה של המשתמש לאחר גיבוב וקידוד. מנורמל כמו
  • הסרת ספרות ותווים של סמלים
  • אות ראשונה קטנה בכל המילים
  • מסירים רווחים בהתחלה ובסוף
  • גיבוב (hash) באמצעות אלגוריתם SHA256
  • לקודד בפורמט של מחרוזת הקסדצימלית.
user_data.address[].sha256_street מחרוזת הרחוב ומספר המשתמש, לאחר גיבוב וקידוד. מנורמל כמו
  • הסרת תווי הסמלים
  • אות ראשונה קטנה בכל המילים
  • מסירים רווחים בהתחלה ובסוף
  • גיבוב (hash) באמצעות אלגוריתם 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).

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

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

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

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

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

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