쿠키 및 동의 관리(레거시 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는 AMP_ 뒤에 프로젝트 API 키의 처음 10자가 붙는 형식의 쿠키를 생성합니다.

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

키 amplitude_cookie_test 뒤에 임의의 base64 문자열 접미사가 붙은 다른 쿠키가 나타날 경우 SDK는 해당 쿠키를 사용하여 사용자가 쿠키를 사용하도록 설정했는지 여부를 테스트하고 테스트가 완료되면 이를 제거합니다. 자세한 내용은 SDK의 base-cookie.js 파일에 있는 세부 정보를 참조하십시오.

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

이 쿠키는 SDK에 대한 다음 메타데이터를 추적합니다.

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

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.cookie을(를) 사용하여 설정된 쿠키의 수명을 1일에서 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로 설정된 경우 사용자가 Amplitude가 이벤트를 업로드하기 전에 빠르게 다른 페이지로 이동하면 이벤트가 손실될 수 있습니다.
• 오프라인 이벤트: SDK의 options.js savedMaxCount 옵션은 오프라인 이벤트 수를 관리합니다(기본값은 1000개). Amplitude가 오프라인 상태에서 1000개 이상의 이벤트를 기록하는 경우 SDK는 스토리지에서 가장 오래된 이벤트를 제거합니다.
• 실패한 이벤트: Amplitude는 재시도를 위해 실패한 이벤트를 여기에 저장합니다.

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

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

자동 캡처된 다른 속성은 쿠키 대신 로컬 스토리지를 사용해도 영향을 받지 않습니다. 자세한 내용은 이 문서를 참조하십시오.

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

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

쿠키를 비활성화하고 사용자가 로컬 스토리지 및 세션 스토리지를 비활성화하면, Amplitude는 기존 ID를 찾을 수 없기 때문에 해당 사용자가 사이트를 방문할 때마다 새로운 device_id을(를) 생성합니다. 사용자가 로그인하거나 다른 식별 정보를 제공하면 Amplitude의 사용자 식별 시스템은 다양한 device_id값을 해당 사용자 ID와 연결합니다. Amplitude가 식별자를 병합할 수 있도록 하려면 사용자는 방문할 때마다 로그인해야 합니다.

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

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

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

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

쿠키 동의 관리

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

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

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

amplitude.getInstance().enableTracking()를 호출하면 Amplitude는 deferInitialization 옵션을 false로 설정하고 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. cookieExpiration의 수명을 수동으로 짧게 설정한 경우, Amplitude 애널리틱스 쿠키가 만료되거나 사용자가 로그인할 때 amplitude.getInstance().enableTracking()을(를) 실행해야 할 수도 있습니다.

2. 사용자가 전체 쿠키를 삭제하면 다음에 앱을 방문할 때 동의 배너를 다시 볼 수 있습니다. Amplitude 애널리틱스 쿠키가 아직 설정되어 있지 않으므로 흐름은 쿠키 동의 관리 섹션을 따릅니다. deferInitialization = true를 사용하는 경우 스토리지 및 추적 옵션의 초기화가 지연됩니다.

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

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

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

amplitude.getInstance().options;

Amplitude는 해당 값과 함께 옵션을 표시합니다. 예를 들어 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.
• cookie.js.
• base-cookie.js.
• localstorage.js.
• metadata-storage.js.

Amplitude는 초기화 시 옵션을 설정합니다. 쿠키 및 메타데이터 저장소의 경우 이는 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 - 자주 묻는 질문