Flutter SDK 4.0 마이그레이션 가이드

Amplitude Flutter SDK 4.0은 기본 이벤트 트래킹, 간소화된 인터페이스를 특징으로 하며 최신 Amplitude iOS, Android Kotlin 및 Browser Typescript SDK를 래핑합니다.

용어

amplitude_flutter:v3: Flutter SDK 3.0입니다.
amplitude_flutter:v4: Flutter SDK 4.0입니다.

종속성

pubspec.yaml을 열고 종속성을 업데이트합니다.

diff

dependencies:
-  amplitude_flutter: ^3
+  amplitude_flutter: ^4

flutter pub get를 터미널에서 실행하여 종속성을 업데이트합니다.

Podfile 열기 및 업데이트:

diff

- platform :ios, '10.0'
+ platform :ios, '13.0'

Flutter 프로젝트의 ios 디렉토리 아래에서 pod install을 실행하여 CocoaPods 의존성을 업데이트합니다.

Flutter Web의 경우, web/index.html에 위치한 "Amplitude-JavaScript" 스니펫을 다음 "브라우저 SDK 2" 스니펫으로 바꿉니다.

html

<script type="text/javascript">
  !(function () {
    "use strict";
    !(function (e, t) {
      var r = e.amplitude || { _q: [], _iq: {} };
      if (r.invoked)
        e.console &&
          console.error &&
          console.error("Amplitude snippet has been loaded.");
      else {
        var n = function (e, t) {
            e.prototype[t] = function () {
              return (
                this._q.push({
                  name: t,
                  args: Array.prototype.slice.call(arguments, 0),
                }),
                this
              );
            };
          },
          s = function (e, t, r) {
            return function (n) {
              e._q.push({
                name: t,
                args: Array.prototype.slice.call(r, 0),
                resolve: n,
              });
            };
          },
          o = function (e, t, r) {
            e._q.push({ name: t, args: Array.prototype.slice.call(r, 0) });
          },
          i = function (e, t, r) {
            e[t] = function () {
              if (r)
                return {
                  promise: new Promise(
                    s(e, t, Array.prototype.slice.call(arguments)),
                  ),
                };
              o(e, t, Array.prototype.slice.call(arguments));
            };
          },
          a = function (e) {
            for (var t = 0; t < g.length; t++) i(e, g[t], !1);
            for (var r = 0; r < m.length; r++) i(e, m[r], !0);
          };
        r.invoked = !0;
        var c = t.createElement("script");
        ((c.type = "text/javascript"),
          (c.integrity =
            "sha384-R0H1kXlk6r2aEQMtwVcPolpk0NAuIqM/8NlxAv24Gr3/PBJPl+9elu0bc3o/FDjR"),
          (c.crossOrigin = "anonymous"),
          (c.async = !0),
          (c.src =
            "https://cdn.amplitude.com/libs/analytics-browser-2.11.10-min.js.gz"),
          (c.onload = function () {
            e.amplitude.runQueuedFunctions ||
              console.log("[Amplitude] Error: could not load SDK");
          }));
        var l = t.getElementsByTagName("script")[0];
        l.parentNode.insertBefore(c, l);
        for (
          var u = function () {
              return ((this._q = []), this);
            },
            p = [
              "add",
              "append",
              "clearAll",
              "prepend",
              "set",
              "setOnce",
              "unset",
              "preInsert",
              "postInsert",
              "remove",
              "getUserProperties",
            ],
            d = 0;
          d < p.length;
          d++
        )
          n(u, p[d]);
        r.Identify = u;
        for (
          var f = function () {
              return ((this._q = []), this);
            },
            v = [
              "getEventProperties",
              "setProductId",
              "setQuantity",
              "setPrice",
              "setRevenue",
              "setRevenueType",
              "setEventProperties",
            ],
            y = 0;
          y < v.length;
          y++
        )
          n(f, v[y]);
        r.Revenue = f;
        var g = [
            "getDeviceId",
            "setDeviceId",
            "getSessionId",
            "setSessionId",
            "getUserId",
            "setUserId",
            "setOptOut",
            "setTransport",
            "reset",
            "extendSession",
          ],
          m = [
            "init",
            "add",
            "remove",
            "track",
            "logEvent",
            "identify",
            "groupIdentify",
            "setGroup",
            "revenue",
            "flush",
          ];
        (a(r),
          (r.createInstance = function (e) {
            return ((r._iq[e] = { _q: [] }), a(r._iq[e]), r._iq[e]);
          }),
          (e.amplitude = r));
      }
    })(window, document);
  })();
</script>

계측

Flutter SDK 4.0은 이벤트를 계측하기 위한 API를 제공합니다. Flutter SDK 4.0으로 마이그레이션하려면 몇 가지 호출을 업데이트해야 합니다. 다음 섹션에서는 변경된 호출에 대해 자세히 설명합니다.

초기화

Flutter SDK 4.0은 다른 레거시 호출과 함께 instance()을 제거합니다. Flutter SDK 4.0은 Configuration 객체를 사용하여 구성을 설정합니다. 자세한 내용은 Configuration을 참조하십시오.

dart

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/identify.dart';
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
// Create the instance and initialize SDK
final Amplitude amplitude = Amplitude.getInstance(instanceName: "project");
amplitude.setServerUrl("https://your.endpoint.com")
amplitude.setServerZone("US")
amplitude.trackingSessionEvents(true)
amplitude.init(widget.apiKey);
final Amplitude amplitude = Amplitude(Configuration(
    apiKey: "YOUR-API-KEY",
    serverUrl: "https://your.endpoint.com",
    serverZone: ServerZone.eu,
    autocapture: AutocaptureOptions(
       sessions: true
    )
  ));
await amplitude.isBuilt;

구성

Flutter SDK 4.0에는 다음과 같은 구성 변경 사항이 포함되어 있습니다.

구성은 런타임 간에 더욱 일관성이 있습니다.
Flutter SDK 4.0은 더 이상 특정 구성을 지원하지 않습니다.
Flutter SDK 4.0은 설정을 위해 SDK 버전 3.0의 세터 대신 인스턴스 변수를 사용합니다.
설정은 Amplitude에 전달한 후에는 변경할 수 없게 됩니다.
defaultTracking 및 DefaultTrackingOptions은(는) 더 이상 사용되지 않습니다. 대신 autocapture를 AutocaptureOptions과 함께 사용하십시오. Flutter SDK 4 참조에서 자동 캡처를 참조하십시오.

Flutter SDK 3.0	Flutter SDK 4.0
`enableCoppaControl()` 또는 `disableCoppaControl()`	`config.enableCoppaControl`
`setMinTimeBetweenSessionsMillis()`	`config.minTimeBetweenSessionsMillis`
`setEventUploadThreshol(d)`	`config.flushQueueSize`
`setEventUploadPeriodMillis()`	`config.flushIntervalMillis`
`setServerZone()`	`config.serverZone`
`setServerUrl()`	`config.serverUrl`
`setUseDynamicConfig()`	지원되지 않음
`setOptOut()`	`config.optOut`
`setOffline()`	지원되지 않음
`trackingSessionEvents()`	`autocapture: AutocaptureOptions(sessions: true)`
`useAppSetIdForDeviceId()`	`config.useAppSetIdForDeviceId`

이벤트 추적

Flutter SDK 4.0은 통합 track API를 사용하여 다음 logEvent API 변형을 대체합니다.

withEventProperties.
withApiProperties.
withUserProperties.
withGroup.
withGroupProperties.

logEvent()

logEvent() API는 track()에 매핑됩니다.

dart

amplitude.logEvent('BUTTON_CLICKED');
amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED'));

이벤트 속성을 가진 logEvent()

dart

amplitude.logEvent('BUTTON_CLICKED', {"Hover Time": "100ms"});
amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED', eventProperties: {"Hover Time": "100ms"}));

outOfSession을 사용한 logEvent()

logEvent()는 선택적인 불리언 인수 outOfSession를 받습니다. 새 track() API는 outOfSession를 지원하지 않습니다. 이벤트를 세션 외부로 추적하려면 event.sessionId = -1을 설정합니다.

dart

amplitude.logEvent("BUTTON_CLICKED", outOfSession: true);
amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED', sessionId: -1));

uploadEvents()

uploadEvents() API는 flush()에 매핑됩니다.

dart

amplitude.uploadEvents();
amplitude.flush();

사용자 속성 설정

사용자 속성을 설정하기 위한 API는 Flutter SDK 4.0에서 instance()를 제거한다는 점을 제외하고 동일합니다. 다음 코드 조각은 사용자 속성 API를 마이그레이션하는 방법을 보여줍니다.

setUserId()

startNewSession는 setUserId()를 더 이상 수신하지 않으며 현재 기본 최소 길이는 5입니다. 이 기본값을 무시하려면 초기화 과정에서 minIdLength 설정 옵선을 지정하십시오.

최소 식별자

유지 관리 SDK는 deviceId 및 userId에 대해 길이 제한을 적용하지 않는 오래된 SDK 엔드포인트(api2.amplitude.com)를 사용합니다. 최신 SDK는 Amplitude의 HTTP V2 API(api2.amplitude.com/2/httpapi)를 사용하며 기본적으로 최소 5자의 식별자를 요구합니다. 최신 SDK로 마이그레이션할 때 5자 미만의 식별자를 허용했다면 config.minIdLength를 더 작은 값으로 설정하십시오.

setDeviceId()

setDeviceId()는 이제 기본 최소 길이가 5입니다. 이 기본값을 변경하려면 초기화 과정에서minIdLength 구성 옵션을 설정하십시오.

최소 식별자

regenerateDeviceId()

Flutter SDK 4.0은 regenerateDeviceId()를 지원하지 않습니다.

clearUserProperties()

Flutter SDK 4.0은 clearUserProperties API를 제거합니다. 사용자 속성을 제거하려면 통합 identify API를 사용하십시오.

dart

amplitude.clearUserProperties();
final Identify identify = Identify()
  ..clearAll();
amplitude.identify(identify);

setUserProperties()

Flutter SDK 4.0은 setUserProperties API를 제거합니다. 사용자 속성을 추가하려면 통합 identify API를 사용하십시오.

dart

- Map<String, dynamic> userProps = {
-   'gender': 'female',
-   'age': '20'
- };
- amplitude.setUserProperties(userProperties);
+ final Identify identify = Identify()
+                          ..set('gender','female')
+                          ..set('age',20);
+ amplitude.identify(identify);

identify()

이제 instance()를 호출하지 않고도 amplitude에서 identify 호출을 수행할 수 있습니다.

dart

final Identify identify = Identify()
                          ..set('gender','female')
                          ..set('age',20);
Amplitude.getInstance().identify(identify);
amplitude.identify(identify);

그룹 속성 설정

`setGroup()`

이제 instance()를 호출하지 않고도 amplitude에서 identify 호출을 수행할 수 있습니다.

dart

// set group with a single group name
Amplitude.getInstance().setGroup("orgId", "15");
amplitude.setGroup("orgId", "15");
// set group with multiple group names
Amplitude.getInstance().setGroup("sport", ["tennis", "soccer"]);
amplitude.setGroup("sport", ["tennis", "soccer"]);

groupIdentify()

이제 instance()를 호출하지 않고도 amplitude에서 identify 호출을 수행할 수 있습니다.

dart

final Identify identify = Identify()
                          ..set("gender", "female")
                          ..set("age", 20);
Amplitude.getInstance().groupIdentify("groupType", "groupValue", identify);
amplitude.groupIdentify("groupType", "groupValue", identify);

매출 추적

revenue() API는 logRevenue() 및 logRevenueAmount()를 대체합니다.

dart

String productId = "product001";
int quantity = 2;
double price = 20;
double amount = 35;
amplitude.logRevenue(productId, quantity, price);
amplitude.logRevenueAmount(amount);
final Revenue revenue = Revenue()
  ..price = 3.99
  ..quantity = 3
  ..productId = "com.company.productId";
amplitude.revenue(revenue);

이 내용이 도움이 되었나요?