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

בדומה לשימוש ב-gtag, אפשר להשתמש ב-Google Analytics Measurement Protocol כדי לשלוח פרטים שהמשתמשים מספקים ביחד עם 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.

תוכן בקשת POST בפורמט 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.

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

בניגוד ל-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
      }]
    }
  })
});