측정 프로토콜을 사용하여 User-ID와 함께 사용자 제공 데이터 전송

gtag를 사용할 때와 마찬가지로, 행동 및 전환 측정 개선을 위해 Google 애널리틱스 4용 Google 애널리틱스 측정 프로토콜을 통해 User-ID와 사용자 제공 데이터를 전송할 수 있습니다.

측정 프로토콜 요청과 사용자 제공 데이터를 전송하려면 JSON 페이로드에 user_data 매개변수를 추가하세요. user_data가 제공될 때는 user_id 매개변수가 있어야 합니다.

측정 프로토콜은 Google Ads API 향상된 측정 기능과 동일한 정규화 및 해싱 알고리즘을 사용합니다. 개인 정보 보호 문제를 위해 데이터를 업로드하기 전에 SHA-256 알고리즘을 사용하여 이메일 주소, 전화번호, 이름, 성 및 상세 주소를 해싱해야 합니다. 해싱된 값은 16진수 문자열 형식(16진수만 포함하는 문자열 객체)으로 인코딩되어야 합니다(예: 88d7ecb5c5b21d7b1).

해싱 결과를 표준화하려면 해당 값을 해싱하기 전에 다음을 따릅니다.

  • 선행 및 후행 공백을 삭제합니다.
  • 텍스트를 소문자로 변환합니다.
  • 전화번호는 E164 표준에 따른 형식으로 작성합니다.
  • gmail.com 및 googlemail.com 이메일 주소의 도메인 이름 앞에 있는 모든 마침표(.)를 삭제합니다.

JSON POST 본문

키 유형 설명
user_id string 사용자의 고유 식별자입니다. 이 식별자에 관한 자세한 내용은 교차 플랫폼 분석용 User-ID를 참고하세요.
user_data 객체 사용자를 식별하는 고급 사용자 데이터 필드입니다.
user_data.sha256_email_address[] 문자열 배열 사용자의 해싱 및 인코딩된 이메일 주소입니다. 다음과 같이 정규화됩니다.
user_data.sha256_phone_number[] 문자열 배열 사용자의 해싱 및 인코딩된 전화번호입니다. 다음과 같이 정규화됩니다.
  • 숫자가 아닌 모든 문자 삭제
  • + 접두사 추가
  • SHA256 알고리즘으로 해싱
  • 16진수 문자열 형식으로 인코딩
user_data.address[] 배열 실제 위치를 기반으로 사용자를 식별합니다.
user_data.address[].sha256_first_name string 사용자의 해싱 및 인코딩된 이름입니다. 다음과 같이 정규화됩니다.
  • 숫자 및 기호 문자 삭제
  • 소문자
  • 선행 및 후행 공백 삭제
  • SHA256 알고리즘으로 해싱
  • 16진수 문자열 형식으로 인코딩
user_data.address[].sha256_last_name string 사용자의 해싱 및 인코딩된 성입니다. 다음과 같이 정규화됩니다.
  • 숫자 및 기호 문자 삭제
  • 소문자
  • 선행 및 후행 공백 삭제
  • SHA256 알고리즘으로 해싱
  • 16진수 문자열 형식으로 인코딩
user_data.address[].sha256_street string 사용자의 해싱 및 인코딩된 도로 및 번지입니다. 다음과 같이 정규화됩니다.
  • 기호 문자 삭제
  • 소문자
  • 선행 및 후행 공백 삭제
  • SHA256 알고리즘으로 해싱
  • 16진수 문자열 형식으로 인코딩
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 표준에 따라 형식이 지정됩니다.

전송 및 페이로드의 형식이 지정되는 방법에 대한 자세한 내용은 측정 프로토콜 참조 문서를 참고하세요.

사용자 제공 데이터 전송

자동으로 민감한 사용자 제공 데이터를 해싱하는 gtag와 달리 측정 프로토콜을 사용하는 경우 개발자가 API를 호출하기 전에 SHA256이라는 안전한 단방향 해싱 알고리즘을 사용하여 민감한 사용자 제공 데이터를 해싱한 다음 16진수 형식으로 인코딩해야 합니다.

이름이 sha256 접두사로 시작하는 모든 사용자 데이터 필드는 해싱되었고 16진수로 인코딩된 값으로만 채워져야 합니다.

다음은 필요한 암호화 및 인코딩 단계를 실행하는 코드의 예시입니다.

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 등)는 배열 대신 단일 값으로 전달될 수 있습니다.

다음은 측정 프로토콜을 호출하고 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
      }]
    }
  })
});