쿠키 및 동의 관리(JavaScript SDK)

이 가이드에서는 기존 JavaScript SDK를 사용할 때 Amplitude가 쿠키, 로컬 저장소, 옵트인/옵트아웃 옵션, 동의 관리(프랑스에 대한 CNIL 규정 포함)와 어떻게 작동하는지에 대해 설명합니다.

Amplitude 쿠키

"쿠키"는 브라우저가 사용자의 기기에 저장하는 웹사이트의 데이터 조각입니다. 웹사이트는 기능적 또는 기술적 목적으로 저장된 데이터에 액세스하기 위해 나중에 쿠키를 검색합니다. 초기화 후, Amplitude SDK는 접두어로 AMP_ 시작하여 프로젝트 API 키의 처음 10자리로 끝나는 쿠키를 생성합니다. 이 접두어는 SDK의 constants.js COOKIE_PREFIX파일에서 상수로 사용자 지정할 수 있습니다. SDK는 amplitude-client.js에서 쿠키의 값을 정의합니다.

예를 들어 다음과 같이 접두사에 기본값을 사용하는 경우:

amplitude.getInstance().init("a2dbce0e18dfe5f8e...");

Amplitude Browser 2.0 SDK는 프로젝트 API 키의 처음 10자리가 뒤에 오는 형식의 쿠키를 AMP_생성합니다.

이전 SDK 버전에서는 cookieName옵션을 사용하여 초기화 시 이 쿠키의 키를 사용자 지정할 수 있었습니다. 이 방법은 더 이상 작동하지 않지만 이전 SDK 버전을 사용하는 경우 쿠키 이름이 표준 이름과 다를 수 있습니다.

키 뒤에 임의의 base64 접미사가 붙은 다른 쿠키가 나타날 경우 SDK는 해당 쿠키를 사용하여 사용자가 쿠키를 활성화했는지 여부를 테스트합니다. amplitude_cookie_testSDK는 테스트가 완료되면 이 쿠키를 삭제합니다. 자세한 내용은 SDK의 base-cookie.js 파일을 참조하십시오.

때때로 SDK가 amplitude_test_cookie쿠키를 삭제하지 않는 경우도 있습니다. 이 경우 쿠키는 쿠키 목록에 남아 있지만 사용되지 않습니다. 이 쿠키의 키는 SDK의 constants.js 파일에 COOKIE_TEST_PREFEX있는 상수를 사용하여 사용자 지정할 수 있습니다.

SDK는 쿠키를 사용하여 다음 메타데이터를 추적합니다.

• deviceId: 무작위로 생성된 문자열입니다.
• userId: 사용자가 로그인할 때 앱이 이 값을 Amplitude에 전송하면 SDK는 이를 쿠키에 저장합니다. 사용자를 고유하게 식별하려면 이 값을 설정하십시오. Amplitude는 이를 저장하기 전에 이 값을 Base64로 인코딩합니다.
• optOut: 이 기기를 Amplitude 추적에서 비활성화하는 플래그입니다. 이 플래그가 설정되어 있으면 Amplitude는 사용자에 대한 추가 정보를 저장하지 않습니다.
• sessionId: 각 세션에 대해 무작위로 생성된 문자열입니다.
• lastEventTime: 마지막 이벤트의 시간으로, 만료 시기를 결정하고 새 세션 ID를 생성하는 데 사용됩니다.
• eventId: 이벤트를 구별하는 식별자의 증분 시퀀스입니다.
• identifyId: identify 호출을 구별하는 식별자의 증분 시퀀스입니다.
• sequenceNumber: 이벤트 및 identify 호출의 순서를 지정하는 시퀀스 번호입니다.

Amplitude JavaScript SDK가 로드될 때, Amplitude를 확인하기 위해 쿠키를 검사합니다device_id(사용자가 이전 방문에서 이를 생성하여 다시 방문하는 경우device_id에 존재함). 발견되면 SDK는 해당 값을 사용합니다. 그렇지 않은 경우(신규 사용자 또는 최근에 쿠키를 삭제한 사용자의 경우), SDK는 임의로 생성하여 device_id이를 쿠키에 저장합니다.

쿠키 크기

쿠키 크기는 최소 60바이트에서 약 120바이트까지 다양할 수 있습니다. Amplitude는 두 개의 쿠키(amp_* 및 amp_*.organization.domain)를 저장할 수 있기 때문에 프로젝트 API 키당 Amplitude 쿠키의 안전한 평균 크기를 120바이트로 가정하십시오.

만료 시간

Amplitude SDK에는 쿠키가 만료될 때까지의 일수를 설정할 수 있는 cookieExpiration옵션이 있습니다. SDK 버전 7.0 이전의 기본값은 10년이었습니다. SDK 버전 7.0 이후의 경우 cookieExpiration 기본값은 1년입니다. 대부분의 브라우저는 통과하여 설정된 쿠키의 수명을 document.cookie1일 및 7일 대상 구간으로 제한합니다.

Amplitude 쿠키 삭제

프로그래밍 방식으로 Amplitude 쿠키를 제거하려면 JavaScript SDK의 clearStorage() 방법을 사용하십시오. 이 방법은 전체 쿠키를 지우고 쿠키에 저장된 전체 메타데이터를 삭제합니다.

사용되지 않는 쿠키

다음 쿠키 키는 최신 SDK 버전에서 사용되지 않습니다.

• amplitude_id_<API_KEY>.your_org_domain: 이전 버전의 Amplitude JavaScript SDK에서는 기본 쿠키 키가 amplitude_id였습니다. 이 문제는 6.0.0 이전 버전의 SDK를 사용하는 프로젝트에서 발생할 수 있습니다. 이 경우 쿠키 키는 amplitude_id_<PROJECT_API_KEY>.organization.domain입니다.

• amplitude_test.your_org_domain: Amplitude SDK는 이 쿠키를 사용하여 쿠키가 사용 가능한지 여부를 보다 철저하게 테스트합니다. 기본적으로 키는 amplitude_cookie_test이며, SDK는 테스트 후에 이 쿠키를 제거합니다.

LocalStorage를 사용하여 쿠키 비활성화(옵트아웃 쿠키)

쿠키에는 Amplitude가 올바르게 작동하는 데 필요한 데이터가 포함되어 있습니다. deviceId, sessionId, 및 마지막 이벤트의 타임스탬프를 저장합니다. 대신 이 정보를 사용자의 로컬 저장소에 저장하려면 SDK의 options.js 파일에서 disableCookies를 true로 설정하십시오.

로컬 스토리지에 저장된 데이터

쿠키에서 관리되는 정보 외에도 Amplitude는 다음과 같은 목적으로 로컬 스토리지를 사용합니다.

• 온라인 이벤트: SDK의 options.js에 있는 saveEvents옵션이 이 저장소를 제어합니다(기본값은 true). Amplitude는 수신한 모든 이벤트를 저장하고 성공적인 업로드 후 이를 삭제합니다. false로 설정된 경우 업로드가 완료되기 전에 사용자가 다른 페이지로 이동하면 이벤트가 손실될 수 있습니다.
• 오프라인 이벤트: SDK의 options.js savedMaxCount옵션은 오프라인 이벤트 수를 설정합니다(기본값은 1000개). Amplitude가 1000개 이상의 이벤트를 오프라인으로 기록하는 경우 SDK는 스토리지에서 가장 오래된 이벤트를 제거합니다.
• 실패한 이벤트: SDK는 재시도를 위해 전체 실패한 이벤트를 여기에 저장합니다.

Amplitude는 이 데이터를 다음 키에 저장합니다.

• amplitude_unsent_<PROJECT_API_KEY>: 전송되지 않은 이벤트를 저장합니다. SDK의 options.js에 있는 unsentIdentifyKey옵션을 사용하여 해당 이름을 사용자 지정할 수 있습니다.
• amplitude_unsent_identify_<PROJECT_API_KEY>: 전송되지 않은 ID 호출을 저장합니다. SDK의 options.js에 있는 unsentKey옵션을 사용하여 해당 이름을 사용자 지정할 수 있습니다.

자동 캡처된 다른 속성은 쿠키 대신 LocalStorage를 사용해도 영향을 받지 않습니다. 자세한 내용은 사용자 속성 정의를 참조하십시오.

이 작업은 쿠키 저장을 비활성화하지만 Amplitude는 동일한 데이터를 사용자의 브라우저의 로컬 저장소에 저장합니다. 이는 완전히 거부하려는 사용자에게는 유효한 옵션이 아닙니다.

쿠키 및 로컬 스토리지 / 세션 스토리지 비활성화(옵트아웃 스토리지)

귀하가 쿠키를 비활성화하고 사용자가 로컬 저장소 및 세션 저장소를 비활성화하면 SDK가 기존 ID를 찾을 수 없기 때문에 Amplitude는 사용자가 방문할 때마다 새로운 ID를 생성합니다device_id. 사용자가 로그인하거나 다른 식별 정보를 제공하면 Amplitude의 사용자 식별 시스템은 다양한 device_id값을 해당 사용자 ID와 연결합니다. 사용자는 매번 방문할 때마다 로그인해야 Amplitude가 식별자를 병합할 수 있습니다.

추적 비활성화(추적 옵트아웃)

사용자는 쿠키를 거부하여 Amplitude가 쿠키에 전체 데이터를 저장하지 못하도록 방지할 수 있으며, 추적을 완전히 거부하여 Amplitude가 이벤트나 브라우징 기록을 저장하지 않도록 설정할 수도 있습니다. Amplitude SDK는 이러한 요청을 충족하기 위해 optOut제공합니다. 프로그래밍 방식으로 추적을 거부하려면 amplitude.setOptOut(true)를 호출하십시오.

브라우저의 "추적 금지" 설정(DNT 플래그)

일부 브라우저에는 전체 추적을 차단하기 위한 "추적 금지" 설정이 있습니다. Amplitude는 이 설정을 준수하지 않습니다. DNT 표준은 광범위하게 지원되지 않으며, 이 표준이 비활성화하는 범위도 명확하지 않습니다. 이 설정을 적용하려면 DNT 플래그를 테스트하기 위해 자체 코드를 작성한 다음 SDK에서 optOut옵션을 설정하십시오.

쿠키 동의 관리

일부 관할권에서는 데이터를 수집하기 전에 사용자가 필수적이지 않은 쿠키에 동의하도록 요구합니다. 귀하가 수집하여 Amplitude에 전송하는 개인 데이터에 대해 필요한 동의를 얻고 필요한 공개를 할 책임은 궁극적으로 귀하에게 있습니다. 또한 귀하는 귀하의 특정 사용 사례와 귀하가 쿠키를 사용하는 관할권에 따라 귀하의 쿠키 정책에서 Amplitude 쿠키를 어떻게 분류할지를 결정할 책임이 있습니다.

이러한 관할 구역 중 하나에서 Amplitude SDK를 사용하는 경우, 사용자가 쿠키 사용에 동의할 때까지 SDK를 초기화하지 마십시오. Amplitude 기능(예: 쿠키 저장소, 로컬 저장소 및 이벤트 추적)은 SDK 초기화 시에 활성화되거나 비활성화됩니다.

이를 지원하기 위해 JavaScript SDK는 deferInitialization옵션(기본값은 null)을 제공합니다. true로 설정된 경우 이 옵션은 쿠키 저장(또는 로컬 스토리지에 항목 저장)과 모든 추적을 포함한 핵심 SDK 기능을 명시적으로 활성화할 때까지 비활성화합니다. SDK 인스턴스는 amplitude.getInstance().enableTracking()를 호출할 때까지 저장 및 추적 없이 로드됩니다.

amplitude.getInstance().enableTracking()를 호출하면 SDK는 deferInitialization를 false로 설정하며 Amplitude는 client.js에 표시된 것처럼 사용자가 구성한 옵션 값으로 쿠키를 생성합니다.

/**
 * Enable tracking through logging events and dropping a cookie
 * Intended to be used with the deferInitialization configuration flag
 * This will drop a cookie and reset initialization deferred
 * @public
 */
AmplitudeClient.prototype.enableTracking = function enableTracking() {
  // This will call init (which drops the cookie) and will run any pending tasks
  this._initializationDeferred = false;
  f(this);
  this.runQueuedFunctions();
};
/**
 * Saves deviceId, userId, event meta data to amplitude cookie
 * @private
 */
var _saveCookieData = function _saveCookieData(scope) {
  const cookieData = {
    deviceId: scope.options.deviceId,
    userId: scope.options.userId,
    optOut: scope.options.optOut,
    sessionId: scope._sessionId,
    lastEventTime: scope._lastEventTime,
    eventId: scope._eventId,
    identifyId: scope._identifyId,
    sequenceNumber: scope._sequenceNumber,
  };
  if (scope._useOldCookie) {
    scope.cookieStorage.set(
      scope.options.cookieName + scope._storageSuffix,
      cookieData,
    );
  } else {
    scope._metadataStorage.save(cookieData);
  }
};

이는 amplitude-client.js에 표시된 것처럼 이미 Amplitude 쿠키를 보유한 사용자에게는 영향을 주지 않습니다. 어느 시점에서 사용자는 동의를 제공했으며, 이는 Amplitude가 합법적으로 쿠키를 생성하는 데 필요한 전체 것입니다. 해당 사용자를 추적에서 제외하려면 해당 사용자에 대해 이미 존재하는 전체 Amplitude 쿠키를 제거해야 합니다.

Amplitude 애널리틱스 쿠키의 존재 여부에 따라 Amplitude가 사용자의 이벤트를 추적할지 여부가 결정됩니다. 쿠키를 보유한 사용자의 경우 다음 사항을 고려하십시오.

1. 수동으로 짧은 수명을 설정한 경우, Amplitude 애널리틱스 쿠키가 만료될 때 또는 사용자가 로그인할 때 cookieExpiration이를 실행해야 할 수도 있습니다amplitude.getInstance().enableTracking().

2. 사용자가 전체 쿠키를 삭제하면 다음에 앱을 방문할 때 동의 배너를 다시 볼 수 있습니다. Amplitude 애널리틱스 쿠키가 아직 존재하지 않으므로, 쿠키 동의 관리 섹션에 설명된 대로 프로세스가 진행되며 deferInitialization = true를 사용할 때 스토리지 및 추적 옵션의 초기화가 기다립니다.

3. 사용자가 과거에 Amplitude 애널리틱스 쿠키에 동의했지만 그 동의가 전체 이유로든 만료된 경우(웹사이트 쿠키 삭제, 동의 추적 만료), Amplitude는 사용자에게 동의를 다시 요청합니다. 사용자가 이를 거부할 경우, 귀하는 Amplitude 애널리틱스 쿠키를 명시적으로 삭제해야 합니다. 그렇지 않은 경우 SDK는 사용자의 의지에 반하여 사용자의 정보를 계속 수집합니다.

프로젝트별 SDK 초기화 옵션 가져오기

전체 사이트 중 Amplitude JavaScript SDK를 사용하는 사이트에서 어떤 초기화 옵션이 설정되어 있는지 확인할 수 있습니다. 사이트에 액세스하는 데 사용하는 브라우저의 JavaScript 콘솔에서 다음 명령을 실행하십시오.

amplitude.getInstance().options;

콘솔에는 각 옵션과 해당 값이 표시됩니다. 예를 들어 amplitude.com에서 다음과 같은 내용을 볼 수 있습니다.

Amplitude Event 익스플로러 Chrome 확장 프로그램의 API 옵션

Amplitude Event 익스플로러 Chrome 확장 프로그램을 사용하는 경우, 관심 있는 프로젝트를 선택한 후 'API 옵션' 탭에서 초기화 옵션 값에 액세스할 수 있습니다.

Amplitude 객체 인스턴스가 window객체에 저장되어 있지 않은 경우, 이 정보는 콘솔이나 Chrome 확장 프로그램에서 사용할 수 없습니다. 이 문제는 일반적으로 JavaScript SDK 대신 Node.js를 사용할 때 발생합니다.

콘솔의 오류는 다음과 같이 표시됩니다.

스토리지 옵션 설명

이 표에서는 각 스토리지 관련 옵션에 대한 간략한 요약을 제공합니다.

스토리지를 위한 추상화 계층

스토리지 추상화 레이어, 사용 가능한 옵션 및 저장된 메타데이터는 Amplitude의 GitHub에서 확인할 수 있습니다.

• constants.js
• options.js
• cookiestorage.js
• 쿠키.js
• base-cookie.js
• localstorage.js
• metadata-storage.js

SDK는 초기화 시 옵션을 설정합니다. 쿠키 및 메타데이터 저장소의 경우, 이는 Amplitude 클라이언트의 Init 메서드에서 발생합니다.

• amplitude-client.js

this.options.apiKey = apiKey;
this._storageSuffix =
  "_" +
  apiKey +
  (this._instanceName === Constants.DEFAULT_INSTANCE
    ? ""
    : "_" + this._instanceName);
this._storageSuffixV5 = apiKey.slice(0, 6);
this._oldCookieName = this.options.cookieName + this._storageSuffix;
this._unsentKey = this.options.unsentKey + this._storageSuffix;
this._unsentIdentifyKey = this.options.unsentIdentifyKey + this._storageSuffix;
this._cookieName = Constants.COOKIE_PREFIX + "_" + this._storageSuffixV5;
this.cookieStorage.options({
  expirationDays: this.options.cookieExpiration,
  domain: this.options.domain,
  secure: this.options.secureCookie,
  sameSite: this.options.sameSiteCookie,
});
this._metadataStorage = new MetadataStorage({
  storageKey: this._cookieName,
  disableCookies: this.options.disableCookies,
  expirationDays: this.options.cookieExpiration,
  domain: this.options.domain,
  secure: this.options.secureCookie,
  sameSite: this.options.sameSiteCookie,
  storage: this.options.storage,
});
const hasOldCookie = !!this.cookieStorage.get(this._oldCookieName);
const hasNewCookie = !!this._metadataStorage.load();
this._useOldCookie =
  !hasNewCookie && hasOldCookie && !this.options.cookieForceUpgrade;
const hasCookie = hasNewCookie || hasOldCookie;

자주 묻는 질문

CNIL France - 자주 묻는 질문