Android용 Google 애널리틱스 SDK: v3로 이전

중요: 이 문서에서는 SDK의 기존 버전을 설명합니다. 신규 사용자는 최신 SDK를 사용해야 합니다.

Google 애널리틱스를 처음 사용하는 개발자는 지금 버전 3을 시작해야 합니다.

이 가이드에서는 Android용 Google 애널리틱스 SDK의 V3로 업그레이드하는 방법을 설명합니다.

한눈에 보기: V3의 새로운 기능

V3의 API는 네이티브 플랫폼과 웹 플랫폼 전반에서 더 일관되도록 리팩터링되었습니다. 모든 V2 사용자는 다음 변경사항을 참고해야 합니다.

• 이제 조회가 단일 send(Map<String, String> parameters) 메서드를 사용하여 전송됩니다.
• 디버그 모드가 Logger로 대체되었습니다.
• EasyTracker에서 이제 Tracker를 서브클래스로 분류하여 인터페이스가 일부 변경되었습니다.
• 신규: 전달된 데이터가 보고서에 표시되지 않도록 dryRun 플래그가 추가되었습니다.

변경사항의 전체 목록은 Android 변경 로그를 참고하세요.

시작하기 전에

v3로 업그레이드를 시작하기 전에 다음이 필요합니다.

• 유니버설 애널리틱스 지원 속성 및 앱 프로필
• Android용 Google 애널리틱스 SDK v3

업그레이드 경로

시작하려면 현재 구현에서 v3으로의 업그레이드 경로를 선택하세요.

• EasyTracker: v1.x에서 v3으로
• EasyTracker: v2.x에서 v3으로
• 맞춤 구현: v1.x에서 v3으로
• 맞춤 구현: v2.x에서 v3으로

EasyTracker: v1.x에서 v3으로

EasyTracker v1.x 사용자는 v3 시작 가이드에 따라 EasyTracker에서 v3을 사용하는 것이 좋습니다.

EasyTracker: v2.x에서 v3으로

v2.x EasyTracker 사용자가 v3으로 업그레이드를 완료하려면 다음 단계를 따라야 합니다.

1. EasyTracker.getInstance() 호출을 업데이트하여 Context:를 제공합니다.

   // v2 (Old)
   // EasyTracker.getInstance().activityStart(this);
   

   // v3:
   EasyTracker.getInstance(this).activityStart(this);
   

2. 이제 EasyTracker가 Tracker를 서브클래스로 분류하여 EasyTracker.getTracker() 호출을 삭제합니다.

   // v2 (Old)
   Tracker v2Tracker = EasyTracker.getInstance().getTracker();
   

   // v3
   Tracker v3Tracker = EasyTracker.getInstance(this);
   

3. 모든 send<hit-type> 편의 메서드를 새로운 send(Map<String, String> parameters) 메서드로 바꿉니다.

   // v2 (Old)
   Tracker v2EasyTracker = EasyTracker.getInstance().getTracker(this);
   v2EasyTracker.sendView("Home Screen");
   

   // v3
   Tracker v3EasyTracker = EasyTracker.getInstance(this);
   
   // Set the screen name on the tracker so that it is used in all hits sent from this screen.
   v3EasyTracker.set(Fields.SCREEN_NAME, "Home Screen");
   
   // Send a screenview.
   v3EasyTracker.send(MapBuilder
     .createAppView()
     .build()
   );
   

   v3에서 데이터를 전송하는 방법 자세히 알아보기



4. ga_debug EasyTracker 매개변수를 ga_logLevel 및 세부정보 값(verbose, info, warning, error) 중 하나로 바꿉니다.

   <!-- res/values/analytics.xml -->
   
   <?xml version="1.0" encoding="utf-8"?>
   <resources>
     <string name="ga_trackingId">UA-XXXX-Y</string>
     <!-- REMOVE: <bool name="ga_debug">true</bool> -->
     <string name="ga_logLevel">verbose</string>
   </resources>
   

   자세한 내용은 EasyTracker 매개변수 참조를 확인하세요.



5. GoogleAnalytics.requestAppOptOut()는 지원 중단되었습니다. 대신 GoogleAnalytics.getAppOptOut()를 사용하세요.

   // v2 (Old)
   GoogleAnalytics.getInstance(this).requestAppOptOut(new AppOptOutCallback() {
      @Override
      public void reportAppOptOut(boolean optOut) {
        if (optOut) {
        ... // Alert the user that they've opted out.
        }
      });
   }
   

   // v3
   boolean optOutPreference = GoogleAnalytics.getInstance(this).getAppOptOut();
   

   주의: v3에서는 앱 수준의 선택 해제 설정이 SDK에서 유지되지 않으며 앱이 실행될 때마다 설정해야 합니다. 애플리케이션 수준 선택 해제 설정 자세히 알아보기
6. (선택사항) 구현을 테스트할 때 ga_dryRun EasyTracker 매개변수를 추가하고 true로 설정하여 테스트 데이터가 프로덕션 보고서에 표시되지 않도록 합니다.

<!-- res/values/analytics.xml -->

<?xml version="1.0" encoding="utf-8"?>

<resources>
  <string name="ga_trackingId">UA-XXXX-Y</string>
  <string name="ga_logLevel">verbose</string>

  <!-- Prevent data from appearing in reports. Useful for testing. -->
  <bool name="ga_dryRun">true</bool>

</resources>

맞춤 구현: v1.x에서 v3으로

EasyTracker를 사용하지 않는 v1.x 사용자는 V3 시작 가이드를 따르고 필요에 따라 고급 구성 개발자 가이드를 참고해야 합니다.

맞춤 구현: v2.x에서 v3으로

EasyTracker를 사용하지 않는 v2.x 사용자는 아래 단계에 따라 v3으로 업그레이드를 완료해야 합니다.

1. 모든 'send<hit-type>' 편의 메서드를 새로운 send(Map<String, String> parameters) 메서드로 바꿉니다.

   // v2 (Old)
   Tracker v2Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
   v2Tracker.sendView("Home Screen");
   

   // v3
   Tracker v3Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
   
   // This screen name value will remain set on the tracker and sent with
   // hits until it is set to a new value or to null.
   v3Tracker.set(Fields.SCREEN_NAME, "Home Screen");
   
   v3Tracker.send(MapBuilder
     .createAppView()
     .build()
   );
   

2. GoogleAnalytics.setDebug() 호출을 삭제하고 GoogleAnalytics.getLogger().setLogLevel()로 바꿉니다.

   // V2 (Old)
   GoogleAnalytics.getInstance(this).setDebug(true);
   

   // V3
   GoogleAnalytics.getInstance(this)
       .getLogger()
       .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
   

   로거에 관해 자세히 알아보기


3. v3 SDK는 앱이 열릴 때 더 이상 새 세션을 자동으로 시작하지 않습니다(EasyTracker를 사용하는 경우 제외). v2 맞춤 구현에서 이 동작을 유지하려면 사용자가 앱을 시작할 때 자체 세션 제어 로직을 구현해야 합니다.

package com.example.app;

import com.google.analytics.tracking.android.GoogleAnalytics;
import com.google.analytics.tracking.android.Tracker;

import android.app.Application;

public class MyApp extends Application {

  private static Tracker mTracker;
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  @Override
  public void onCreate() {
    super.onCreate();
    mTracker = GoogleAnalytics.getInstance(this).getTracker(GA_PROPERTY_ID);

    // CAUTION: Setting session control directly on the tracker persists the
    // value across all subsequent hits, until it is manually set to null.
    // This should never be done in normal operation.
    //
    // mTracker.set(Fields.SESSION_CONTROL, "start");

    // Instead, send a single hit with session control to start the new session.
    mTracker.send(MapBuilder
      .createEvent("UX", "appstart", null, null)
      .set(Fields.SESSION_CONTROL, "start")
      .build()
    );
  }
}

4. (선택사항) 테스트 중에 dryRun 플래그를 설정하여 테스트 데이터가 프로덕션 보고서로 처리되지 않도록 합니다.

// When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

참조

다음 섹션에서는 V3 SDK를 사용하여 데이터를 설정하고 전송하는 방법의 참조 예를 제공합니다.

v3에서 지도를 사용하여 데이터 전송

V3에서는 Google 애널리틱스 필드 및 값의 Map를 인수로 사용하는 단일 send() 메서드를 사용하여 데이터가 전송됩니다. 조회 빌드 프로세스를 단순화하기 위해 MapBuilder 유틸리티 클래스가 제공됩니다.

// Sending a screenview in v3 using MapBuilder.
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");
tracker.set(Fields.SCREEN_NAME, "Home Screen");

tracker.send(MapBuilder
  .createAppView()                           // Creates a Map of hit type 'AppView' (screenview).
  .set(Fields.customDimension(1), "Premium") // Set any additional fields for this hit.
  .build()                                   // Build and return the Map to the send method.
);

MapBuilder 클래스는 이벤트와 같이 지원되는 조회 유형을 빌드하는 데 사용할 수 있습니다.

// Sending an event in v3 using MapBuilder.createEvent()
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

v3에서 데이터 전송에 관해 자세히 알아보기

v3에서 추적기의 데이터 설정

set() 메서드를 사용하여 Tracker에 직접 값을 설정할 수도 있습니다. 직접 설정된 값은 해당 Tracker에서 발생하는 모든 후속 조회에 적용됩니다.

// Values set directly on a tracker apply to all subsequent hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// This screenview hit will include the screen name "Home Screen".
tracker.send(MapBuilder.createAppView().build());

// And so will this event hit.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

Tracker에 설정된 값을 지우려면 속성을 null로 설정하세요.

// Clear the previously-set screen name value.
tracker.set(Fields.SCREEN_NAME, null);

// Now this event hit will not include a screen name value.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

v3의 데이터 설정 자세히 알아보기