자바스크립트 SDK

이 문서는 Amplitude 애널리틱스 JavaScript SDK에 대한 공식 문서입니다.

설치

프로젝트에 Amplitude 애널리틱스 JavaScript SDK를 설치하십시오.

<script type="text/javascript">
  (function (e, t) {
    var n = e.amplitude || { _q: [], _iq: {} };
    var r = t.createElement("script");
    r.type = "text/javascript";
    r.integrity =
      "sha384-5fhzC8Xw3m+x5cBag4AMKRdf900vw3AoaLty2vYfcKIX1iEsYRHZF4RLXIsu2o+F";
    r.crossOrigin = "anonymous";
    r.async = true;
    r.src = "https://cdn.amplitude.com/libs/amplitude-8.21.4-min.gz.js";
    r.onload = function () {
      if (!e.amplitude.runQueuedFunctions) {
        console.log("[Amplitude] Error: could not load SDK");
      }
    };
    var s = t.getElementsByTagName("script")[0];
    s.parentNode.insertBefore(r, s);
    function i(e, t) {
      e.prototype[t] = function () {
        this._q.push([t].concat(Array.prototype.slice.call(arguments, 0)));
        return this;
      };
    }
    var o = function () {
      this._q = [];
      return this;
    };
    var a = [
      "add",
      "append",
      "clearAll",
      "prepend",
      "set",
      "setOnce",
      "unset",
      "preInsert",
      "postInsert",
      "remove",
    ];
    for (var c = 0; c < a.length; c++) {
      i(o, a[c]);
    }
    n.Identify = o;
    var l = function () {
      this._q = [];
      return this;
    };
    var u = [
      "setProductId",
      "setQuantity",
      "setPrice",
      "setRevenueType",
      "setEventProperties",
    ];
    for (var p = 0; p < u.length; p++) {
      i(l, u[p]);
    }
    n.Revenue = l;
    var d = [
      "init",
      "logEvent",
      "logRevenue",
      "setUserId",
      "setUserProperties",
      "setOptOut",
      "setVersionName",
      "setDomain",
      "setDeviceId",
      "enableTracking",
      "setGlobalUserProperties",
      "identify",
      "clearUserProperties",
      "setGroup",
      "logRevenueV2",
      "regenerateDeviceId",
      "groupIdentify",
      "onInit",
      "onNewSessionStart",
      "logEventWithTimestamp",
      "logEventWithGroups",
      "setSessionId",
      "resetSessionId",
      "getDeviceId",
      "getUserId",
      "setMinTimeBetweenSessionsMillis",
      "setEventUploadThreshold",
      "setUseDynamicConfig",
      "setServerZone",
      "setServerUrl",
      "sendEvents",
      "setLibrary",
      "setTransport",
    ];
    function v(t) {
      function e(e) {
        t[e] = function () {
          t._q.push([e].concat(Array.prototype.slice.call(arguments, 0)));
        };
      }
      for (var n = 0; n < d.length; n++) {
        e(d[n]);
      }
    }
    v(n);
    n.getInstance = function (e) {
      e = (!e || e.length === 0 ? "$default_instance" : e).toLowerCase();
      if (!Object.prototype.hasOwnProperty.call(n._iq, e)) {
        n._iq[e] = { _q: [] };
        v(n._iq[e]);
      }
      return n._iq[e];
    };
    e.amplitude = n;
  })(window, document);
  amplitude.getInstance().init(AMPLITUDE_API_KEY);
</script>

SDK를 설치한 후 프로젝트로 amplitude가져옵니다.

import amplitude from "amplitude-js";

// initialize the client
var instance1 = amplitude.getInstance().init(AMPLITUDE_API_KEY);

// send an event
const event = "œButton Clicked";
amplitude.getInstance().logEvent(event);

핵심 기능

다음 함수는 Amplitude 애널리틱스 JavaScript SDK의 핵심을 구성합니다.

초기화

계측을 수행하려면 먼저 Amplitude 프로젝트의 API 키를 사용하여 SDK를 초기화해야 합니다.

초기화는 기본 인스턴스를 생성하지만 문자열 이름과 함께 사용하여 더 많은 인스턴스를 생성할 수 getInstance있습니다.

var instance1 = amplitude.getInstance().init("AMPLITUDE_API_KEY"); // initializes default instance of Amplitude client
var instance2 = amplitude
  .getInstance("instance-name")
  .init("AMPLITUDE_API_KEY"); // initializes named instance of Amplitude client

옵션이 포함된 초기화

init메소드에 사용자 지정 옵션을 전달합니다. GitHub의 옵션 목록을 참조하십시오.

var options = {};
var instance = amplitude
  .getInstance("instance")
  .init(AMPLITUDE_API_KEY, null, options); // initializes with the given options

구성

일괄 처리 동작 구성

고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. SDK는 메소드가 메모리에 기록하는 모든 이벤트를 logEvent대기열에 보관합니다. SDK는 백그라운드에서 이벤트를 일괄적으로 플러시합니다.eventUploadThreshold 및 eventUploadPeriodMillis을 사용하여 일괄 처리 동작을 사용자 정의할 수 있습니다. 기본적으로 serverUrl은 https://api.amplitude.com입니다. 이 SDK는 배치 모드, 즉 배치 API 엔드포인트를 지원하지 않습니다.

amplitude.getInstance().init(apiKey, null, {
  // Events queued in memory will flush when number of events exceed upload threshold
  // Default value is 30
  eventUploadThreshold: 50,
  // Events queue will flush every certain milliseconds based on setting
  // Default value is 30000 milliseconds
  eventUploadPeriodMillis: 100000,
});

EU 데이터 상주

버전 8.9.0부터는 클라이언트를 초기화한 후 Amplitude의 EU 서버로 데이터를 전송하도록 서버 영역을 구성할 수 있습니다.

서버 영역 구성은 동적 구성도 지원합니다.

이전 버전의 경우 클라이언트를 초기화한 후 apiEndpoint 속성을 구성하십시오.

버전 8.9.0 이상 이전 버전

// No need to call setServerUrl for sending data to Amplitude's EU servers
amplitude.getInstance().init(euApiKey, null, {
  serverZone: "EU",
  serverZoneBasedApi: true,
});

amplitude.getInstance().init(euApiKey, null, {
  apiEndpoint: "https://api.eu.amplitude.com",
});

설정 userID

클라이언트를 초기화할 때 또는 초기화 후 setUserId메소드를 사용하여 설정하십시오userID.

var userId = "12345";
amplitude.getInstance().init(AMPLITUDE_API_KEY, userId); // initializes client with the given userId

이벤트 전송

기본 이벤트

이벤트는 사용자가 앱과 상호작용함을 나타냅니다. 예를 들어 ‘버튼 클릭’은 추적하려는 동작일 수 있습니다.

const event = "Button Clicked";
amplitude.getInstance().logEvent(event);

이벤트 속성

이벤트에는 이벤트에 대한 컨텍스트를 제공하는 속성이 있을 수 있습니다. 예를 들어 "마우스 오버 시간"은 "버튼 클릭됨" 이벤트와 관련된 속성입니다.

var event = "Button Clicked";
var eventProperties = {
  "hover time": "100ms",
};
amplitude.getInstance().logEvent(event, eventProperties);

이벤트 속성의 배열

이벤트 속성 값은 배열일 수 있습니다. 배열의 개별 속성의 전체 하위 집합을 기준으로 배열 이벤트 속성을 쿼리할 수 있습니다.

var event = "Button Clicked";
var eventProperties1 = {
  selectedColors: ["red", "blue"],
};
amplitude.getInstance().logEvent(event, eventProperties1);
var eventProperties2 = {
  selectedColors: ["red", "green"],
};
amplitude.getInstance().logEvent(event, eventProperties2);

사용자 속성

사용자 속성은 사용자가 앱 첫 사용 후 어떤 작업을 수행했을 때 사용자를 이해하는 데 도움이 됩니다. 예를 들어 사용자의 장치 세부 정보, 기본 설정, 언어에 대해 알 수 있습니다.

사용자 속성 설정

Amplitude Identify 오브젝트는 사용자 속성을 설정하는 방법을 제어합니다. 먼저 Identify 객체 인스턴스를 생성한 다음 인스턴스에서 Identify 메서드를 호출한 다음 클라이언트가 Identify 객체를 사용하여 호출을 수행합니다.

new amplitude.Identify(); // does nothing, must call one of the following methods and pass to client
var identify = new amplitude.Identify();
amplitude.getInstance().identify(identify); // makes identify call to amplitude with the properties of the identify object

set

사용자 속성의 값을 설정합니다. 또한 여러 set호출을 함께 연결할 수도 있습니다.

var identify1 = new amplitude.Identify().set("key1", "value1");
var identify2 = new amplitude.Identify()
  .set("key2", "value2")
  .set("key3", "value3");
amplitude.getInstance().identify(identify1);
amplitude.getInstance().identify(identify2);

setOnce

setOnce 는 사용자 속성의 값을 한 번만 설정합니다. Amplitude는 setOnce를 사용하는 후속 호출을 무시합니다.

var identify = new amplitude.Identify().setOnce("key1", "value1");
amplitude.getInstance().identify(identify);

add

add를 사용하여 사용자 속성을 숫자만큼 증가시킵니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 이 속성은 0로 초기화됩니다.

var identify = new amplitude.Identify().add("value1", 10);
amplitude.getInstance().identify(identify);

여러 사용자 속성 설정

setUserProperties을 단축어로 사용하여 여러 사용자 속성을 한 번에 설정할 수 있습니다. 예를 들어, 다음 코드를 사용하여 사용자의 도시를 설정합니다.

var userProperties = {
  city: "San Francisco",
};
amplitude.getInstance().setUserProperties(userProperties);

사용자 속성의 배열

사용자 속성은 배열일 수 있습니다. 배열을 직접 설정하거나 append을 사용하여 생성합니다.

var values = ["value1", "value2"];
var identify = new amplitude.Identify().set("key1", values);
amplitude.getInstance().identify(identify);

prepend 그리고 append

• append 사용자 속성 배열에 값을 추가합니다.
• prepend 는 사용자 속성 배열 앞에 값을 추가합니다.

사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 추가하기 전에 이를 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있고 해당 값이 목록이 아닌 경우 SDK는 해당 값을 목록으로 변환하고 새 값을 추가합니다.

사용자 그룹

Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 수행하는 것을 지원합니다. 그룹 구성원 중 적어도 한 명이 특정 이벤트를 수행한 경우 해당 그룹도 수행 회수가에 포함됩니다.

예를 들어 'orgId'를 사용하여 사용자가 속한 조직을 기준으로 사용자를 그룹화하려는 경우가 있습니다. Joe는 'orgId' '10'에 있고 Sue는 'orgId' '15'에 있습니다. Sue와 Joe는 둘 다 특정 이벤트를 수행합니다. 이벤트 세분화 차트에서 해당 조직을 쿼리할 수 있습니다.

그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예시에서 'orgId'는 groupType이고 '10'과 '15'는 groupName에 대한 값입니다. groupType의 또 다른 예로는 'tennis' 및 'baseball'과 같은 groupName 값을 가진 'sport'가 있을 수 있습니다.

또한 그룹을 설정하면 groupType:groupName를 사용자 속성으로 설정하고 해당 사용자의 groupType에 대해 설정된 전체 기존 groupName값과 해당 사용자 속성 값을 덮어씁니다. groupType은 groupName문자열이며 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 배열일 수 있습니다.

amplitude.getInstance().setGroup("orgId", ["10", "16"]);

logEventWithGroups을 사용하여 이벤트 수준 그룹을 설정할 수도 있습니다. 이벤트 수준 그룹의 경우 그룹 지정은 SDK가 기록하는 특정 이벤트에만 적용되며 setGroup를 사용하여 명시적으로 설정하지 않는 한 사용자에게 지속되지 않습니다.

var eventProperties = {
  key: "value",
};
amplitude
  .getInstance()
  .logEventWithGroups("initialize_game", eventProperties, { sport: "soccer" });

그룹 식별

Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 다음 사항을 염두에 두십시오.

• 업데이트는 향후 이벤트에만 영향을 미치며 과거 이벤트를 업데이트하지는 않습니다.
• 최대 5개의 고유 그룹 유형과 총 10개의 그룹을 추적할 수 있습니다.

groupIdentify이 메서드는 그룹 유형 문자열 매개변수와 그룹 이름 객체 매개변수, 그리고 SDK가 그룹에 적용하는 Identify 객체를 허용합니다.

var groupType = "plan";
var groupName = "enterprise";
var identify = new amplitude.Identify().set("key1", "value1");
amplitude.getInstance().groupIdentify(groupType, groupName, identify);

선택적 콜백 함수를 groupIdentify의 네 번째 인수로 제공할 수 있습니다.

매출 추적

사용자의 수익을 추적하는 가장 좋은 방법은 제공된 Revenue 인터페이스와 함께 사용하는 것입니다. logRevenueV2()수익 인스턴스는 각 수익 거래를 저장하며, Amplitude의 이벤트 세분화 및 LTV (Lifetime Value) 차트에서 사용하는 몇 가지 특별한 수익 속성을 정의할 수 있습니다(예: revenueType 및 productIdentifier). 또한 eventProperties필드를 통해 이벤트 속성을 수익 이벤트에 추가할 수 있습니다. 이러한 Revenue 인스턴스 객체를 logRevenueV2에 전달하여 Amplitude에 수익 이벤트로 전송합니다. 그러면 Amplitude는 플랫폼의 매출과 관련된 데이터를 자동으로 표시합니다. 이러한 방식으로 앱 내 구매와 앱 외부 구매를 모두 추적할 수 있습니다.

사용자의 수익을 추적하려면 사용자가 수익을 창출할 때마다 전화하십시오. logRevenueV2()다음은 예입니다.

var revenue = new amplitude.Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3);
amplitude.getInstance().logRevenueV2(revenue);

호출은 다음과 같은 수익 이벤트 유형을 생성합니다logRevenueV2.

• [Amplitude] Revenue: SDK는 사용자가 검증을 활성화했는지 여부에 관계없이 모든 수익 이벤트에 대해 이 이벤트를 기록합니다.

원시 데이터에서 이러한 클라이언트측 수익 이벤트에 지정된 기본 이름을 변경할 수는 없지만 표시 이름을 변경할 수는 있습니다. 수익 추적에 대한 자세한 내용은 수익 추적을 참조하십시오.

사용자를 추적에서 해제합니다

지정된 사용자에 대한 로깅을 해제하려면 다음과 같이 호출하십시오setOptOut.

amplitude.getInstance().setOptOut(true);

setOptOut가 활성화되어 있는 동안에는 SDK가 이벤트를 서버에 저장하거나 전송하지 않습니다. 옵트아웃 설정은 페이지가 로드될 때에도 유지됩니다. 로깅을 다시 활성화하려면 다음을 호출하십시오.

amplitude.getInstance().setOptOut(false);

특정 필드 추적 비활성화

기본적으로 JavaScript SDK는 일부 속성을 자동으로 추적합니다. SDK를 초기화할 때 trackingOptions라는 객체를 전달하여 이 동작을 재정의할 수 있습니다. 해당 옵션을 false로 설정합니다.

사용자 지정 사용자 ID 설정

앱에 사용자를 추적할 로그인 시스템이 있는 경우 언제든지 다음 주소로 setUserId전화할 수 있습니다.

amplitude.getInstance().setUserId("USER_ID");

또한 사용자 ID를 init 호출에 인수로 추가할 수도 있습니다.

amplitude.getInstance().init(AMPLITUDE_API_KEY, "USER_ID");

각 고유 사용자 ID는 Amplitude에서 고유한 사용자를 나타내므로 변경될 수 있는 사용자 ID를 사용자에게 할당하지 마십시오. 자세한 내용은 다음을 참조하십시오. 헬프 센터에서 Amplitude의 고유 사용자를 추적하세요.

로그아웃된 사용자 및 익명 사용자

Amplitude는 사용자 데이터를 병합하므로, Amplitude는 알려진 userId 또는 deviceId에 관련된 모든 이벤트를 기존 사용자와 연결합니다. 사용자가 로그아웃하면 Amplitude는 해당 사용자의 로그아웃 이벤트를 해당 사용자의 기록에 병합할 수 있습니다. 이 동작을 변경하고 해당 이벤트를 익명 사용자에게 기록할 수 있습니다.

익명 사용자에게 이벤트를 기록하려면 다음을 수행하십시오.

1. userId를 null로 설정합니다.
2. 새 deviceId를 생성합니다.

현재 사용자 또는 기기에서 발생한 이벤트는 Amplitude에서 새 사용자로 표시됩니다. 참고: 이 작업을 수행하면 두 사용자가 동일한 장치를 사용했는지 알 수 없습니다.

amplitude.getInstance().setUserId(null); // not string 'null'
amplitude.getInstance().regenerateDeviceId();

세션 추적

서로 30분 첫 사용 후 트리거된 이벤트는 현재 세션에 수행 회수가 포함됩니다. 첫 번째 이벤트의 시간은 세션의 시작 시간을 표시하고 마지막으로 트리거된 이벤트는 세션의 종료 시간을 표시합니다. SDK 구성 옵션 필드 sessionTimeout를 통해 세션 시간 초과 기간을 변경할 수 있습니다.

세션 ID 가져오기

JavaScript SDK에서 헬퍼 메소드를 사용하여 getSessionId현재 값을 얻을 수 있습니다sessionId:

const sessionId = amplitude.getInstance().getSessionId();

HTTP 헤더 구성

사용자 지정 HTTP 요청 헤더가 필요한 도메인 프록시를 사용하는 경우 초기화 options.headers다음 기간동안 로 해당 헤더를 구성하십시오.

amplitude.getInstance().init(AMPLITUDE_API_KEY, null, {
  headers: {
    "x-session-id": appToken,
    "Content-Type": "application/json;charset=utf-8",
  },
});

여러 프로젝트에 이벤트 기록

이벤트를 여러 Amplitude 프로젝트에 기록하려면 각 Amplitude 프로젝트에 대해 별도의 인스턴스를 가져야 합니다. 각 인스턴스는 독립적인 apiKeys, userIds, deviceIds및 설정을 허용합니다.

각 Amplitude 프로젝트와 인스턴스에 이름을 할당해야 하며, 함수를 호출하기 위해 해당 인스턴스를 가져올 때 해당 이름을 일관되게 사용해야 합니다.

인스턴스 이름은 NULL이 아니고 비어있지 않은 문자열이어야 합니다. 이름은 대소문자를 구분하지 않으며, 각 인스턴스의 이름을 호출하여 가져올 수 있습니다.

각 새 인스턴스는 고유한 apiKey, userId, deviceId 및 설정을 갖습니다.

다음은 두 개의 별도 프로젝트에 이벤트를 설정하고 기록하는 방법의 예입니다.

// existing project, existing settings, and existing API key
amplitude.getInstance().init("12345", null, { batchEvents: true });
// new project, new API key
amplitude
  .getInstance("new_project")
  .init("67890", null, { includeReferrer: true });
// need to reconfigure new project
amplitude.getInstance("new_project").setUserId("joe@gmail.com");
amplitude.getInstance("new_project").setUserProperties({ gender: "male" });
amplitude.getInstance("new_project").logEvent("Clicked");
var identify = new amplitude.Identify().add("karma", 1);
amplitude.getInstance().identify(identify);
amplitude.getInstance().logEvent("Viewed Home Page");

웹 어트리뷰션

Amplitude의 JavaScript SDK는 기본적으로 웹 어트리뷰션 데이터를 수집하지 않지만 설정은 빠릅니다. 어트리뷰션 구성 옵션을 활성화하면 SDK가 이 정보를 자동으로 수집할 수 있습니다.

Amplitude는 SDK 구성 옵션을 통해 다음을 자동으로 추적할 수 있도록 지원합니다.

• 사용자의 브라우저 쿠키 또는 URL 매개변수에서 includeUtm.를 사용하여 얻은 5가지 표준 UTM 매개변수입니다.
• includeReferrer에서 참조하는 URL 및 도메인입니다.
• URL 매개 변수에서 includeGclid까지 구글 클릭 식별자입니다.
• 페이스북 URL 매개 변수에서 includeFbclid까지 식별자를 클릭합니다.

UTM 매개변수 추적

UTM 매개 변수는 Urchin 트래픽 모니터링 매개 변수의 약자로, 다양한 광고 캠페인과 추천 사이트의 효과를 분석하는 데 도움을 줍니다. UTM 매개변수는 대소문자를 구분하므로, 대소문자 표기가 다를 경우 Amplitude는 이를 서로 다른 값으로 취급합니다.

다음과 같은 다섯 가지 표준 UTM 매개변수가 있습니다.

• utm_source: 트래픽을 전송한 웹사이트를 식별합니다(예: Google, Facebook).
• utm_medium: 사용된 링크 유형을 식별합니다(예: 배너, 버튼, 이메일).
• utm_campaign: 사용된 특정 캠페인을 식별합니다(예: "summer_sale").
• utm_term: 사용된 유료 검색 용어를 식별합니다(예: 제품+분석).
• utm_content: 이 값은 사용자를 사이트로 이끌었던 원인을 식별하며 일반적으로 A/B 테스트에 사용됩니다(예: "배너 링크", "텍스트 링크").

다음은 예제 URL입니다.

https://www.amplitude.com/?utm_source=newsletter&utm_campaign=product_analytics_playbook&utm_medium=email&utm_term=product%20analytics&utm_content=banner-link

SDK를 통해 활성화

Amplitude에서 includeUtm옵션을 true로 설정하면 JavaScript SDK가 자동으로 참조 URL에서 UTM 매개변수를 가져오고 이를 모든 관련 이벤트의 사용자 속성으로 포함시킵니다.

• includeGclid: Gclid(Google 클릭 식별자)는 Google이 사용하는 전 세계적으로 고유한 추적 매개변수입니다. 사용 중일 때 Google은 런타임 시 URL에 고유한 매개 변수(예: "?gclid=734fsdf3")를 추가합니다. 이 값을 true로 설정하면 SDK가 initial_gclid및 gclid를 사용자 속성으로 캡처합니다.
• includeFbclid: Fbclid(Facebook Click Identifier)는 Facebook이 사용하는 전 세계적으로 고유한 추적 매개변수입니다. 사용 중일 때 Facebook은 런타임 시 URL에 고유한 매개 변수(예: "?fbclid=392foih3")를 추가합니다. 이 값을 true로 설정하면 SDK는 initial_fblid및 fbclid를 사용자 속성으로 캡처합니다.
• includeUtm: true인 경우, URL 또는 브라우저 쿠키에서 표준 UTM 매개변수를 찾아 사용자 속성으로 설정합니다. 이 옵션은 utm_source, utm_medium, utm_campaign, utm_term 및 utm_content, 그리고 initial_utm_source, initial_utm_medium, initial_utm_campaign, initial_utm_term 및 initial_utm_content를 사용자의 사용자 속성으로 설정합니다. 기본적으로 SDK는 세션당 한 번씩 UTM 파라미터를 캡처하며, 캡처는 사용자가 귀하의 사이트와 Amplitude SDK를 처음 로드할 때 발생합니다. saveParamsReferrerOncePerSession 구성 옵션을 통해 세션당 1회 제한을 비활성화할 수 있습니다. SDK가 새 세션을 시작해야 함을 감지할 때, SDK는 해당 시점에 사용 가능한 UTM 매개변수를 가져옵니다. SDK는 이러한 UTM 매개변수를 사용자 속성으로 설정하며, 이는 앞으로 진행되는 모든 사용자 이벤트에 대해 지속됩니다. 그러나 SDK는 setOnce작업을 통해 각 사용자에 대해 초기 UTM 매개변수를 한 번씩 캡처합니다.

레퍼럴 추적

사용자가 귀하의 웹사이트에 어떻게 접근하는지 추적하려면 추천자(추천 사이트)를 추적하십시오.

Amplitude는 다음 필드를 자동으로 추적할 수 있도록 지원합니다.

• referrer: 사용자가 마지막으로 방문한 페이지입니다(예: <https://amplitude.com/behavioral-analytics-platform?ref=nav>).
• referring_domain: 사용자가 마지막으로 사용했던 도메인(예: amplitude.com).

SDK를 통해 활성화

includeReferrer옵션을 true로 설정한 후에는 Amplitude가 각 세션의 referrer및 referring_domain를 캡처하여 관련 이벤트의 사용자 속성으로 설정합니다.

• includeReferrer: 이때 true는 각 세션의 referrer및 referring_domain를 사용자 속성으로 캡처하고 각 사용자에 대해 initial_referrer및 initial_referring_domain 사용자 속성을 한 번씩 캡처합니다. 참조자는 전체 URL이고, referring_domain는 사용자가 유입된 도메인 이름입니다.

Amplitude는 setOnce작업을 통해 각 사용자에 대해 한 번씩 초기 참조 정보를 캡처합니다.

퍼스트 터치 어트리뷰션

Amplitude는 각 사용자의 초기 UTM 매개변수와 리퍼러 정보를 캡처할 수 있습니다. Amplitude는 사용자의 널이 아닌 UTM 매개변수를 처음 감지할 때 최초 접촉 기여 값을 설정합니다. Amplitude는 이러한 사용자 속성을 한 번만 설정합니다.

• initial_utm_source
• initial_utm_medium
• initial_utm_campaign
• initial_utm_term
• initial_utm_content
• initial_referrer
• initial_referring_domain
• initial_gclid
• initial_fbclid

JavaScript SDK 구성 옵션 includeReferrer, includeUtm, includeFbclid, 및 includeGclid을 true로 설정하여 이러한 매개변수를 캡처합니다.

마지막 접촉 기여

Amplitude는 다음 사용자 속성을 설정하여 각 세션에서 사용자가 어디에서 왔는지 캡처합니다.

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• referrer
• referring_domain
• gclid
• fbclid

이를 사용하려면 JavaScript SDK 구성 옵션 includeReferrer, includeUtm, includeFbclid 및 includeGclid을 true로 설정하십시오. 기본적으로 SDK는 세션 시작 시에만 값을 저장하므로, 사용자가 동일한 세션 첫 사용 후 다른 UTM 매개변수 세트를 사용하여 다시 사이트에 방문하도록 유도하는 흐름을 트리거하면 SDK는 두 번째 세트를 저장하지 않습니다.

멀티 터치 기여 분석

JavaScript SDK 구성에서 saveParamsReferrerOncePerSession을 설정하면 SDK는 항상 사용자로부터 새 값을 캡처합니다. false이렇게 하면 세션 내내 이러한 사용자 속성이 변경될 경우 업데이트됩니다.

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• referrer
• referring_domain
• gclid
• fbclid

일부 고객은 또한 이러한 사용자 속성을 배열로 계측하여 SDK가 단일 사용자에 대해 동일한 세션 첫 사용 후 감지한 모든 기여 매개변수를 추적합니다.

Amplitude를 통해 캡처된 속성 값을 기록

이 기능은 고급옵션 사용 사례입니다.

JavaScript SDK 구성에서 logAttributionCapturedEvent를 true로 설정하면 SDK는 사용자로부터 새로운 속성 값을 캡처할 때마다 Amplitude 이벤트를 기록합니다.

이벤트 이름: [Amplitude] Attribution Captured

이벤트 속성:

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• referrer
• referring_domain
• gclid
• fbclid

구글 태그 관리자

Amplitude의 JavaScript SDK는 Google 태그 관리자와의 연동을 지원합니다. 설정 지침은 GitHub의 데모 앱을 참조하세요.

문제 해결 및 디버깅

디버깅 방법

브라우저에서 디버깅하면 코드 구현과 관련된 문제점과 사용 중인 SDK 첫 사용 후 잠재적 문제를 식별하는 데 도움이 됩니다. 다음은 디버깅을 위해 브라우저에 내장된 개발자 도구(DevTools)를 사용하는 방법에 대한 기본 가이드입니다.

콘솔

검사 > 콘솔에서 JavaScript 오류를 찾을 수 있습니다. 여기에는 문제를 일으킨 코드 줄과 파일에 대한 세부 정보가 있을 수 있습니다. 또한 콘솔을 사용하면 JavaScript 코드를 실시간으로 실행할 수 있습니다.

• 다음 지침에 따라 디버그 모드를 활성화하십시오. 기본 로거를 사용하면 SDK는 사용자가 전체 SDK 공용 메서드를 호출할 때마다 추가 함수 컨텍스트 정보를 개발자 콘솔에 출력하며, 이는 디버깅에 도움이 될 수 있습니다.
• Amplitude는 SDK 지연 초기화를 지원합니다. SDK는 초기화 호출 후 초기화 전에 추적된 이벤트를 디스패치합니다. 이벤트를 전송할 수는 없지만 브라우저 콘솔에 입력한 후 성공적으로 이벤트를 전송할 수 있다면 amplitude.init(API_KEY, 'USER_ID')호출이 코드베이스에서 트리거되지 않았거나, 초기화 다음 기간 동안 올바른 Amplitude 인스턴스를 사용하지 않았을 수 있습니다.amplitude.init 구현 방법을 확인하십시오.

Instrumentation 익스플로러/Chrome Extension

Amplitude Instrumentation 익스플로러는 Google Chrome 웹 스토어에서 사용할 수 있는 확장 프로그램입니다. 이 확장 기능은 사용자가 트리거하는 각 Amplitude 이벤트를 캡처하여 확장 기능 팝업에 표시합니다. SDK가 이벤트를 성공적으로 전송했는지 확인하고, 이벤트 페이로드의 컨텍스트를 확인하십시오.

일반적인 문제

다음은 브라우저 SDK와 관련된 일반적인 문제입니다.

AD 차단 프로그램

Ad Blocker 이벤트가 삭제될 수 있습니다. 다음 오류는 Ad Blocker가 추적에 영향을 미친다는 것을 나타냅니다. 스크립트 태그를 통해 로드할 경우 SDK 스크립트가 로드되는 동안 콘솔/네트워크 탭에 오류가 나타날 수 있습니다. npm 패키지를 사용하여 로드할 때 SDK가 서버로 이벤트를 전송하려고 할 때 네트워크 탭에 오류가 나타날 수 있습니다. 오류는 브라우저에 따라 다를 수 있습니다.

• 크롬(우분투, 맥OS) 콘솔: error net::ERR_BLOCKED_BY_CLIENT 네트워크: 상태(차단됨:기타)
• Firefox (Ubuntu) 콘솔: 오류 텍스트에 전체 차단 관련 정보가 포함되어 있지 않습니다. 네트워크: 전송된 열에는 uBlock Origin에 의해 차단된 플러그인 이름이 포함됩니다
• 사파리 (맥 OS) 콘솔: 오류에 텍스트가 포함되어 있습니다. 콘텐츠 차단기로 인해 프레임 ... 이 ...에서 리소스를 로드할 수 없습니다. 네트워크: 차단된 요청이 나열되지 않은 것 같습니다. 그것들을 보여줄 수 있을지 확실하지 않습니다.

Amplitude는 이러한 상황을 피하기 위해 프록시 서버를 사용할 것을 권장합니다.

쿠키 관련

SDK가 쿠키에 저장하는 정보에 대해서는 쿠키 관리 섹션을 참조하십시오. 쿠키를 비활성화하거나 개인 브라우저/창/탭을 사용하는 것과 같은 클라이언트의 행동은 쿠키에 불러오기된 이러한 값의 지속성에 영향을 미칩니다. 이러한 값이 지속되지 않거나 1씩 증가하지 않는 경우 이것이 원인일 수 있습니다.

CORS

Cross-Origin Resource Sharing (CORS)는 브라우저가 웹 페이지가 다른 도메인으로부터 리소스를 요청할 수 있는 방법을 제한하기 위해 사용하는 보안 조치입니다. CORS를 사용하는 경우 setServerURL이 문제가 발생할 수 있습니다.

Access to fetch at 'xxx' from origin 'xxx' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

Cross-origin resource sharing (CORS)는 악의적인 사이트가 다른 사이트의 데이터를 권한 없이 읽는 것을 방지합니다. 이 오류 메시지는 귀하가 접속하려는 서버가 귀하의 오리진에서 요청된 리소스에 접근할 수 없음을 나타냅니다. 이 문제의 원인은 서버의 응답에 Access-Control-Allow-Origin헤더가 없기 때문입니다.

• 서버에 대한 제어 권한이 있는 경우 서버의 CORS 정책을 업데이트할 수 있습니다. 서버의 응답에 Access-Control-Allow-Origin 헤더를 추가하십시오. 이 변경 사항은 여러분의 오리진이 요청을 할 수 있게 해줍니다. Access-Control-Allow-Origin의 값은 모든 출처를 허용하거나 웹 페이지의 특정 URL을 허용할 *수 있습니다.
• 서버에 대한 제어 권한이 없는 경우 필요한 CORS 헤더를 추가하는 프록시 서버를 설정할 수 있습니다. 웹 페이지는 프록시에 요청을 전송하며, 프록시는 실제 서버에 요청을 전송합니다. 프록시는 응답을 웹 페이지로 다시 전송하기 전에 응답에 Access-Control-Allow-Origin헤더를 추가합니다.

API 프록시를 설정했는데 선택한 플랫폼에서 그와 관련된 구성 문제가 발생할 경우, 이는 더 이상 SDK 문제가 아니라 애플리케이션과 서비스 공급자 대상 구간 연동 문제입니다.

이벤트가 발생했지만 네트워크 요청이 없음

로거를 '디버그' 수준으로 설정하고 개발자 콘솔에 호출 추적이 표시되면 SDK가 이 track() 메서드를 호출한 것입니다. Amplitude, Amplitude Instrumentation 익스플로러 Chrome 확장 프로그램 또는 브라우저의 네트워크 요청 탭에서 해당 이벤트를 볼 수 없다면 SDK가 해당 이벤트를 Amplitude로 전송하지 않은 것입니다. SDK는 성공적인 호출 후 이벤트를 발생시켜 SDK의 내부 대기열에 넣지만, track()때로는 이러한 대기열에 저장된 이벤트가 성공적으로 전송되지 않을 수도 있습니다. 이는 브라우저가 진행 중인 HTTP 요청을 취소할 때 발생할 수 있습니다. 예를 들어 브라우저를 닫거나 페이지를 떠나는 경우입니다.

이 문제를 해결하는 방법은 두 가지가 있습니다.

1. 표준 네트워크 요청을 사용하는 경우 초기화 다음 기간동안 전송을 beacon로 설정하거나 beacon페이지 종료 시 전송을 sendBeacon으로 설정하십시오. 는 백그라운드에서 이벤트를 전송하고 4xx또는 5xx과 같은 서버 응답을 반환하지 않으므로 이 경우 작동하지 않습니다. 따라서 실패 시 재시도하지 않습니다. sendBeacon는 백그라운드에서 예약된 요청만 전송합니다. 자세한 내용은 sendBeacon 섹션을 참조하십시오.
2. track()을 동기화하려면 호출 전에 키워드 await를 추가하십시오.

고급옵션 항목

동적 구성

버전 8.9.0부터는 동적 구성을 사용하도록 앱을 구성할 수 있습니다. 이 기능은 앱 사용자의 위치를 기반으로 최적의 서버 URL을 자동으로 찾습니다.

사용하려면 true로 설정하십시오useDynamicConfig.

• 자체 프록시 서버를 보유하고 있고 apiEndPoint API를 사용하는 경우 동적 구성을 해제하십시오.
• 중국 본토에 사용자가 있는 경우, Amplitude는 동적 구성을 사용하는 것을 권장합니다.
• 기본적으로 이 기능은 Amplitude의 미국 서버의 서버 URL을 반환합니다. Amplitude의 EU 서버로 데이터를 전송해야 하는 경우, setServerZone을 사용하여 이를 EU 지역으로 설정하세요.

amplitude.getInstance().init(euApiKey, null, {
  useDynamicConfig: true,
});

COPPA 제어

Amplitude의 다른 SDK의 COPPA 제어는 IDFA, IDFV, 도시, 위치 데이터(location_lat 및 location_lng), 및 IP 주소에 대한 추적을 비활성화합니다. JavaScript SDK는 location_lat, location_lng , IDFA 또는 IDFV를 추적하지 않으므로 COPPA 제어용 인터페이스가 없습니다. 대신, trackingOptions및 city에 대해 ip_address를 사용하여 추적을 비활성화할 수 있습니다.

var trackingOptions = {
  city: false,
  ip_address: false,
};

장치 ID 가져오기

다음 코드를 사용하여 사용자의 현재 장치 ID를 가져옵니다.

var deviceId = amplitude.getInstance().getDeviceId(); // existing device ID

구성 옵션 설정

객체를 init에 세 번째 인수로 전달하여 Amplitude를 구성합니다.

amplitude.getInstance().init(AMPLITUDE_API_KEY, null, {
  // optional configuration options
  saveEvents: true,
  includeUtm: true,
  includeReferrer: true,
});

쿠키 관리

SDK에 의해 생성된 쿠키

초기화 시 SDK는 접두사 amp_ 로 시작하여 API 키의 처음 여섯자리로 끝나는 쿠키를 생성합니다. 예를 들어, amplitude.getInstance().init("a2dbce0e18dfe5f8e74493843ff5c053")는 키가 인 쿠키를 생성합니다amp_a2dbce.

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

• 무작위로 생성된 장치 ID
• 현재 세션 ID
• 사용자 ID가 설정된 경우 현재 사용자 ID
• 마지막 이벤트 시간
• 이벤트를 올바른 순서로 배치하고 작업을 식별하기 위한 시퀀스 ID

쿠키 비활성화

disableCookies 옵션을 사용하여 SDK에서 생성한 쿠키를 비활성화하십시오. 쿠키를 비활성화하면 JavaScript SDK는 기본적으로 localStorage를 사용하여 데이터를 저장합니다. LocalStorage는 유용한 대안이지만 도메인 전체에서 쿠키를 추적할 수는 없습니다. 브라우저는 하위 도메인별로 localStorage액세스를 제한하기 때문에, 제품의 하위 도메인에서 익명 사용자를 추적할 수 없습니다(예: www.amplitude.com와 analytics.amplitude.com).

SameSite

JavaScript SDK는 기본적으로 쿠키에 대한 SameSite 옵션을 None로 설정합니다. 이 설정은 sameSiteCookie옵션을 통해 재정의할 수 있습니다. 사이트로 양식을 보내는 타사 사이트가 있는 경우가 아니라면 Amplitude는 POST를 사용할 것을 권장합니다Lax.

HTTP전용 쿠키

HTTPOnly 옵션은 SDK가 생성하는 쿠키에 대해 기술적으로 가능하지 않습니다. SDK는 클라이언트 측에서 쿠키를 설정하고 이를 클라이언트 측 데이터 저장소로 사용합니다. SDK 쿠키는 HTTPOnly 플래그를 설정할 수 없습니다.

레거시 쿠키 업그레이드

SDK가 생성한 기존 쿠키는 새롭고 더 작은 쿠키보다 큽니다. 오래된 쿠키가 있는 사용자의 경우, cookieForceUpgrade 옵션이 true로 설정되어 있으면 SDK는 기존 쿠키를 제거하고 새 쿠키 형식을 사용하기 시작합니다. 여러 제품에서 SDK를 사용하고 해당 제품에서 익명 사용자를 추적하는 경우, 해당 모든 제품에 이 옵션을 설정해야 합니다.

RequireJS

RequireJS를 사용하여 JavaScript 파일을 로드하는 경우 로딩 스니펫을 사용하는 대신 이를 사용하여 Amplitude JavaScript SDK 스크립트를 직접 로드할 수 있습니다. 이 접근법을 택하면 스니펫의 주요 장점 중 하나를 잃게 됩니다. 이 장점은 Amplitude가 완전히 다운로드될 때까지 기다리지 않고 앱을 시작하고 Amplitude SDK를 사용할 수 있게 해줍니다.

<script src="scripts/require.js"></script>
<!-- loading RequireJS -->
<script>
  require([
    "https://cdn.amplitude.com/libs/amplitude-6.2.0-min.umd.gz.js",
  ], function (amplitude) {
    amplitude.getInstance().init(AMPLITUDE_API_KEY); // replace AMPLITUDE_API_KEY with your Amplitude API key.
    window.amplitude = amplitude; // You can bind the amplitude object to window if you want to use it directly.
    amplitude.getInstance().logEvent("Clicked Link A");
  });
</script>

또한 다음과 같이 RequireJS 구성에서 경로를 정의할 수도 있습니다.

<script src="scripts/require.js"></script>
<!-- loading RequireJS -->
<script>
  requirejs.config({
    paths: {
      amplitude: "https://cdn.amplitude.com/libs/amplitude-6.2.0-min.umd.gz.js",
    },
  });
  require(["amplitude"], function (amplitude) {
    amplitude.getInstance().init(AMPLITUDE_API_KEY); // replace AMPLITUDE_API_KEY with your Amplitude API key.
    window.amplitude = amplitude; // You can bind the amplitude object to window if you want to use it directly.
    amplitude.getInstance().logEvent("Clicked Link A");
  });
</script>
<script>
  require(["amplitude"], function (amplitude) {
    amplitude.getInstance().logEvent("Page loaded");
  });
</script>

도메인 간 추적(JavaScript)

두 개의 다른 도메인에서 익명의 행동을 추적할 수 있습니다. Amplitude는 기기 ID를 기준으로 익명 사용자를 식별하며, 이 ID는 도메인 대상 구간 전달해야 합니다. 예를 들면 다음과 같습니다.

• 사이트 1: www.example.com
• 사이트 2: www.example.org

사이트 1에서 시작한 다음 사이트 2로 이동하는 사용자는 사이트 1에서 생성된 디바이스 ID를 매개변수로 사이트 2로 전달해야 합니다. 그런 다음 사이트 2는 디바이스 ID를 사용하여 SDK를 초기화해야 합니다. SDK는 deviceIdFromUrlParam가 활성화된 경우 URL 매개 변수를 자동으로 구문 분석할 수 있습니다.

1. 사이트 1에서 amplitude.getInstance().options.deviceId에서 디바이스 ID를 가져옵니다.
2. 사용자가 탐색할 때 URL 매개 변수를 통해 장치 ID를 사이트 2에 전달하십시오(예: www.example.com?amp_device_id=device_id_from_site_1).
3. 사이트 2에서 amplitude.init(AMPLITUDE_API_KEY, null, {deviceIdFromUrlParam: true})를 사용하여 Amplitude SDK를 초기화합니다.

UTM 매개 변수, 참조자 및 gclid 추적(JavaScript)

Amplitude는 자동 추적을 지원합니다.

• 초기화 다음 기간동안 구성 옵션includeUtm이 true로 설정된 경우 사용자의 쿠키 또는 URL 매개변수에서 가져온 표준 UTM 매개변수입니다.
• 초기화 다음 기간동안 구성 옵션includeReferrer이 true로 설정된 경우 참조하는 URL입니다.
• gclid (Google Click ID)는 초기화 다음 기간동안 구성 옵션 includeGclid가 true로 설정된 경우 URL 매개 변수에서 가져옵니다.

추적을 활성화하면 SDK는 세션당 한 번씩 값을 사용자 속성(예: referrer 또는 utm_source)으로 설정합니다. 이를 마지막 접촉 속성이라고 합니다. 또한 SDK는 setOnce 작업을 사용하여 initial_referrer 및 initial_utm_source 와 같은 초기값을 저장합니다. SDK가 이러한 값을 설정한 후에는 절대로 변경되지 않습니다. 이를 첫 번째 터치 속성이라고 합니다.

saveParamsReferrerOncePerSession

기본적으로 SDK는 세션 시작 시에만 값을 저장합니다. 예를 들어 사용자가 초기 UTM 매개변수 세트를 사용하여 귀하의 사이트에 접속하고, 이로 인해 사용자가 동일한 Amplitude 세션 첫 사용 후 다른 UTM 매개변수 세트를 사용하여 다시 사이트에 접속하게 되는 경우, SDK는 두 번째 세트를 저장하지 않습니다. 구성 옵션을 saveParamsReferrerOncePerSession 로 false 설정하여 해당 제한을 제거할 수 있으므로 SDK가 항상 사용자로부터 새 값을 캡처할 수 있습니다.

unsetParamsReferrerOnNewSession

기본적으로 SDK는 새 세션을 시작할 때 기존 UTM 매개변수 및 참조자 값을 그대로 사용합니다. 예를 들면 다음과 같습니다. 사용자의 세션이 만료되면 SDK는 사용자의 Referrer 및 UTM 매개변수를 기존 값에 매핑합니다. SDK가 새 세션을 인스턴스화할 때 이러한 값을 null로 재설정하려면 unsetParamsReferrerOnNewSession를 true로 설정하십시오.

logEvent, identify및 redirect에 대한 콜백

콜백 함수를 logEvent 및 identify에 전달할 수 있으며, SDK는 서버로부터 응답을 받은 후 이를 호출합니다. 이 기능은 타이밍 때문에 브라우저가 웹 페이지에서 벗어나기 전에 SDK가 이벤트를 캡처하지 못할 수 있는 경우 유용합니다. logEvent 메소드의 콜백에 탐색을 포함하면 탐색이 발생하기 전에 SDK가 이벤트를 캡처할 수 있습니다. 다음은 logEvent 예제입니다.

amplitude.getInstance().logEvent("EVENT_TYPE", null, callback_function);

다음은 identify 예입니다.

var identify = new amplitude.Identify().set("key", "value");
amplitude.getInstance().identify(identify, callback_function);

SDK는 서버에서 콜백 함수로 상태 및 응답 본문을 전달합니다. 이 기능은 유용할 수 있습니다. 다음은 응답 후 브라우저를 다른 사이트로 리디렉션하는 콜백 함수의 예입니다.

var callback_function = function (status, response) {
  if (status === 200 && response === "success") {
    // do something here
  }
  window.location.replace("URL_OF_OTHER_SITE");
};

이 정보를 사용하여 귀하의 웹사이트에 대한 아웃바운드 링크를 추적할 수도 있습니다. 예를 들어, 다음과 같은 링크가 있을 수 있습니다.

<a href="javascript:trackClickLinkA();">Link A</a>

그런 다음 사용자가 링크를 클릭할 때 실행되는 함수를 다음과 같이 정의합니다.

var trackClickLinkA = function () {
  amplitude.getInstance().logEvent("Clicked Link A", null, function () {
    window.location = "LINK_A_URL";
  });
};

optOut가 true인 경우 SDK는 이벤트를 기록하지 않지만 콜백을 호출합니다.batchEvents 가 true 일 때, eventUploadThreshold 을 호출할 때 배치 요구 사항인 logEvent 및 eventUploadPeriodMillis 가 충족되지 않으면 SDK는 요청을 보내지 않지만 여전히 콜백을 호출합니다. 이러한 경우 SDK는 입력 상태가 0이고 '요청이 전송되지 않았음'이라는 응답으로 콜백을 호출합니다.

오류 콜백

이벤트에 대한 네트워크 요청이 실패할 경우 SDK가 호출하는 logEvent 및 identify에 두 번째 콜백을 전달할 수 있습니다. 이 기능은 사용자가 광고 차단기를 사용하고 있는지 또는 이벤트 형식의 문제로 인해 Amplitude 서버에서 오류가 발생했는지 여부를 감지하는 데 유용합니다. 다음과 같이 오류 콜백을 성공 콜백과 함께 사용할 수 있습니다.

var successCallback = function () {
  console.log("the event was logged successfully");
};
var errorCallback = function () {
  console.log("there was an error logging the event");
};
amplitude.getInstance().logEvent("event", null, successCallback, errorCallback);

init 콜백

또한 SDK가 비동기 로드를 완료한 후 호출하는 콜백 함수를 init에 전달할 수도 있습니다. SDK는 인스턴스를 콜백의 인수로 전달합니다.

amplitude
  .getInstance()
  .init(AMPLITUDE_API_KEY, "USER_ID", null, function (instance) {
    console.log(instance.options.deviceId); // access Amplitude's deviceId after initialization
  });

sendBeacon 사용

SDK 버전 8.5.0 이상에서는 SDK가 브라우저의 내장 navigator.sendBeacon API를 사용하여 이벤트를 전송할 수 있습니다. 표준 네트워크 요청과 달리 sendBeacon은 사용자가 브라우저를 닫거나 페이지를 떠날 때에도 백그라운드에서 이벤트를 전송합니다.

sendBeacon을 사용하여 이벤트를 전송하려면 다음 두 가지 방법 중 하나로 transport SDK 옵션을 'beacon'으로 설정하십시오.

// set transport to 'beacon' when initializing an event
amplitude
  .getInstance()
  .init(AMPLITUDE_API_KEY, "USER_ID", { transport: "beacon" });
// set transport to 'beacon' after initialization
amplitude.getInstance().setTransport("beacon");
// this event will be sent using navigator.sendBeacon
amplitude.getInstance().logEvent("send event with beacon");
// set transport back to the default 'http' value
amplitude.getInstance().setTransport("http");
// this event will be sent using the standard xhr mechanism
amplitude.getInstance().logEvent("send event with http");

페이지를 종료할 때만 sendBeacon 사용

JavaScript SDK는 사용자가 페이지를 종료할 때만 실행되는 콜백 기능을 제공합니다. 이 기능은 콜백에서 전송된 전체 로그에 대해 자동으로 전송을 'beacon'으로 전환합니다. 이 콜백은 onExitPage이라고 불리며, 초기화 시 다음과 같이 이를 SDK에 전달합니다.

var exitCallback = function {
 amplitude.getInstance().logEvent('Logging a final event as user exits via sendBeacon');
};
amplitude.getInstance().init(AMPLITUDE_API_KEY, 'USER_ID', { onExitPage: exitCallback });

장치 ID 생애주기 분석

SDK는 다음 순서로 장치 ID를 초기화하며, 장치 ID를 발견한 첫 번째 유효한 값으로 설정합니다.

1. 초기화 시 구성에 있는 장치 ID입니다.
2. URL 매개 변수의 "amp_device_id" 값(true인 configuration.deviceIdFromUrlParam경우)입니다. 자세한 내용은 교차 도메인 추적을 참조하십시오.
3. 쿠키 저장소의 장치 ID입니다. 자세한 내용은 쿠키 관리를 참조하십시오.
4. 무작위로 생성된 22자리 base64 ID입니다. 이 ID는 동일한 128비트 범위를 갖는 36자 UUID보다 더 간결합니다.

장치 ID가 변경되는 시기

장치 ID는 다음과 같은 여러 가지 시나리오에서 변경됩니다.

Amplitude 애널리틱스 SDK는 실험 SDK와 ID 저장소를 공유합니다.

setDeviceId또한 ID 저장소를 업데이트하여 새로운 사용자 정보를 실험 SDK에 전파하고 장치 ID가 변경될 경우 가져오기를 트리거합니다.

• 명시적으로 setDeviceId()호출합니다.
• 기본적으로 SDK는 기기 ID를 쿠키에 저장하므로 사용자가 쿠키를 지우거나 다른 기기를 사용하거나 개인정보 보호 모드를 사용하면 기기 ID가 변경됩니다.
• 초기화 시 SDK는 deviceIdFromUrlParam가 활성화된 경우 URL 매개변수에서 장치 ID를 가져옵니다amp_device_id.

사용자 지정 장치 ID

setDeviceId()를 사용하여 새 장치 ID를 할당할 수 있습니다. 사용자 지정 장치 ID를 설정할 때는 값이 충분히 고유한지 확인하십시오. Amplitude는 UUID 사용을 권장합니다.

기본적으로 장치 ID는 임의로 생성된 base64 ID입니다. 사용자 지정 장치 ID를 구성 옵션으로 설정하거나 setDeviceId을 호출하여 정의할 수 있습니다.

amplitude.getInstance().setDeviceId("DEVICE_ID");

장치 ID 가져오기

Amplitude가 Amplitude.getInstance().getDeviceId()와 함께 사용하는 장치 ID를 검색하거나, 사용자 지정 인스턴스 이름을 정의한 경우 Amplitude.getInstance('YOUR-INSTANCE-NAME').getDeviceId()에 검색할 수 있습니다. 이 메서드는 SDK가 아직 deviceId를 생성하지 않은 경우 반환될 수 있습니다null.

const deviceId = amplitude.getInstance().getDeviceId();

현재 장치 ID를 다른 인스턴스와 공유

때로는 Amplitude JavaScript SDK 인스턴스가 두 개 이상 설정되어 있으며 인스턴스 간에 장치 ID를 공유하려는 경우가 있습니다.

• 방법 1: 구성에서 장치 ID를 사용하여 다른 인스턴스를 초기화하십시오.

// Initialize an instance with default configuration
// Device Id of this instance is created by default
var instanceDev = amplitude.getInstance("amplitude-dev");
instanceDev.init("API-KEY-1");
// Initialize another instance with a different API key
// And pass the deviceId from the previous instance to the configuration
var instanceProd = amplitude.getInstance("amplitude-prod");
instanceProd.init("API-KEY-2", undefined, {
  deviceId: instanceDev.getDeviceId(),
});

• 방법 2: 동일한 상태로 유지되어야 할 때마다 초기화 후 장치 ID를 설정하십시오.

var instanceDev = amplitude.getInstance("amplitude-dev");
instanceDev.init("API-KEY-1");
var instanceProd = amplitude.getInstance("amplitude-prod");
instanceProd.init("API-KEY-2");
// Before the line blow, the device Ids of the two instances are different
instanceProd.setDeviceId(instanceDev.getDeviceId());

• 방법 3: URL 매개변수 amp_device_id에 장치 ID를 전달합니다. 자세한 내용은 교차 도메인 추적을 참조하십시오.

콘텐츠 보안 정책(CSP)

보안상의 이유로 웹 앱에 엄격한 콘텐츠 보안 정책(CSP)이 구성되어 있는 경우, Amplitude 도메인을 허용하도록 정책을 조정하십시오.

• "스니펫"을 사용할 때는 https://*.amplitude.com에 script-src추가하십시오.
• https://*.amplitude.com을 connect-src에 추가하십시오.