Android용 Google 애널리틱스 SDK 버전 1 (기존)

Android용 모바일 앱용 Google 애널리틱스 SDK를 사용하면 Android 기반 애플리케이션에서 Google 애널리틱스를 쉽게 구현할 수 있습니다. 이 문서에서는 SDK를 앱과 통합하는 방법을 설명합니다.

SDK 개요

이 SDK는 기존 웹사이트로 사용자를 추적하고 기존 웹페이지의 위젯과 상호작용하는 것을 추적하도록 설계된 추적 모델을 사용합니다. 따라서 아래에서 사용되는 용어는 기존 웹사이트 추적 모델을 반영하며 모바일 애플리케이션을 추적하는 데 사용됩니다. 이 SDK의 작동 방식을 이해하려면 애널리틱스 추적을 잘 알고 있어야 합니다.

모바일 추적 SDK를 이용하면 다음과 같은 애널리틱스 상호작용 유형으로 전화 애플리케이션을 추적할 수 있습니다.

페이지 조회 추적

페이지 조회는 기존 웹사이트의 트래픽 양을 측정하는 표준 수단입니다. 모바일 앱에는 HTML 페이지가 포함되어 있지 않으므로 페이지 조회 요청을 트리거할 시기와 빈도를 결정해야 합니다. 또한 페이지 조회 요청은 디렉터리 구조를 보고하도록 설계되었으므로 애널리틱스의 콘텐츠 보고서에서 페이지 경로 이름 지정을 활용하려면 요청을 설명하는 이름을 제공해야 합니다. 선택한 이름은 애널리틱스 보고서에 실제로는 HTML 페이지가 아니더라도 페이지 경로로 채워지지만, 호출을 위한 추가 그룹을 제공하도록 경로를 구조화하면 더욱 편리합니다.

이벤트 추적

애널리틱스에서 이벤트는 페이지 조회 요청과는 다른 방법으로 웹페이지 요소에 대한 사용자 상호작용을 추적하도록 설계되었습니다. Google 애널리틱스의 이벤트 추적 기능을 사용하면 추가 호출을 할 수 있으며, 이 호출은 애널리틱스 보고서 인터페이스의 이벤트 추적 섹션에 보고됩니다. 이벤트는 카테고리를 사용하여 그룹화되며, 보고 시 유연성을 제공하는 이벤트별 라벨을 사용할 수도 있습니다. 예를 들어 멀티미디어 앱의 경우 동영상 카테고리에 재생/중지/일시중지 작업이 있고 각 동영상 이름에 라벨을 할당할 수 있습니다. 그러면 Google 애널리틱스 보고서에서 동영상 카테고리로 태그가 추가된 모든 이벤트의 이벤트를 집계합니다. 이벤트 추적에 대한 자세한 내용은 이벤트 추적 가이드를 참조하세요.

전자상거래 추적

전자상거래 추적 기능을 사용하여 장바구니 거래와 인앱 구매를 추적합니다. 거래를 추적하려면 Transaction 클래스를 사용하여 전체 구매 정보를 나타내고 Item 클래스를 사용하여 장바구니의 각 제품을 나타냅니다. 수집된 데이터는 Google 애널리틱스 인터페이스의 전자상거래 보고 섹션에서 볼 수 있습니다. 전자상거래 추적에 대한 자세한 내용은 전자상거래 추적 가이드를 참고하세요.

맞춤 변수

맞춤 변수는 Google 애널리틱스 추적을 세분화하기 위해 추적 코드에 삽입할 수 있는 이름-값 쌍 태그입니다. 맞춤 변수를 사용하는 방법에 대한 자세한 내용은 맞춤 변수 가이드를 참고하세요.

시작하기

요구사항

Google 애널리틱스의 추적 기능을 Android 앱과 통합하려면 다음이 필요합니다.

• Android 개발자 SDK (Windows, Mac OS X, Linux에서 사용 가능)
• 모바일 앱용 Google 애널리틱스 Android SDK

설정

• 프로젝트의 /libs 디렉터리에 libGoogleAnalytics.jar를 추가합니다.
• 프로젝트의 AndroidManifest.xml 매니페스트 파일에 다음 권한을 추가합니다.
  • <uses-permission android:name="android.permission.INTERNET" />
  • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

성공적으로 설정되었을 경우 프로젝트가 어떻게 나타나는지 보여주는 예제 애플리케이션이 SDK에 포함되어 있습니다. 이 템플릿을 애널리틱스 통합 앱의 템플릿으로 사용하세요.

SDK 사용

SDK를 사용하기 전에 먼저 www.google.com/analytics에서 무료 계정을 만들고, 허위이지만 설명이 포함된 웹사이트 URL (예: http://mymobileapp.mywebsite.com)을 사용하여 해당 계정에 새 웹 속성을 만들어야 합니다. 속성을 만든 후에는 새로 만든 속성에 대해 생성된 웹 속성 ID를 기록하거나 사본을 보관해야 합니다.

애플리케이션 자체 또는 서비스 약관을 통해 앱 내의 사용자 활동을 익명으로 추적하고 보고할 권리가 있음을 사용자에게 명시해야 합니다. Google 애널리틱스 SDK를 사용하면 계정에 가입할 때 동의해야 하는 Google 애널리틱스 SDK 서비스 약관이 추가로 적용됩니다.

샘플 및 권장사항

code.google.com의 analytics-api-samples 프로젝트에서 샘플 코드와 권장사항을 확인할 수 있습니다.

EasyTracker 라이브러리

EasyTracker 라이브러리를 사용할 수 있습니다. 또한 개발 작업을 거의 수행할 필요 없이 애플리케이션 및 활동 수준 추적을 제공합니다. analytics-api-samples 프로젝트의 다운로드 섹션에서 이를 확인할 수 있습니다.

트래커 시작

GoogleAnalyticsTracker.getInstance()를 호출하여 추적기 싱글톤을 가져옵니다. 그런 다음 startNewSession 메서드를 호출하여 추적 중인 웹 속성 ID와 활동을 전달합니다. 애플리케이션에 활동이 하나만 있는 경우 활동의 onCreate 메서드에서 이 메서드를 직접 호출할 수 있습니다. 예를 들면 다음과 같습니다.

package com.google.android.apps.analytics.sample;

import com.google.android.apps.analytics.GoogleAnalyticsTracker;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class TestActivity extends Activity {

  GoogleAnalyticsTracker tracker;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    tracker = GoogleAnalyticsTracker.getInstance();

    // Start the tracker in manual dispatch mode...
    tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this);

    // ...alternatively, the tracker can be started with a dispatch interval (in seconds).
    //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this);

    setContentView(R.layout.main);
    Button createEventButton = (Button)findViewById(R.id.NewEventButton);
    createEventButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        tracker.trackEvent(
            "Clicks",  // Category
            "Button",  // Action
            "clicked", // Label
            77);       // Value
      }
    });

    Button createPageButton = (Button)findViewById(R.id.NewPageButton);
    createPageButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and
        // scope of session-level.
        tracker.setCustomVar(1, "Navigation Type", "Button click", 2);
        // Track a page view. This is probably the best way to track which parts of your application
        // are being used.
        // E.g.
        // tracker.trackPageView("/help"); to track someone looking at the help screen.
        // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game.
        // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen.
        tracker.trackPageView("/testApplicationHomeScreen");
      }
    });

    Button quitButton = (Button)findViewById(R.id.QuitButton);
    quitButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        finish();
      }
    });

    Button dispatchButton = (Button)findViewById(R.id.DispatchButton);
    dispatchButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Manually start a dispatch, not needed if the tracker was started with a dispatch
        // interval.
        tracker.dispatch();
      }
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    // Stop the tracker when it is no longer needed.
    tracker.stopSession();
  }
}

애플리케이션에 여러 활동이 있는 경우 analytics-api-samples 프로젝트의 다운로드 섹션에 제공된 EasyTracker 라이브러리를 사용할 수 있습니다.

페이지 조회 및 이벤트 추적

페이지 조회 및 이벤트를 추적하는 것은 간단합니다. 페이지 조회를 트리거할 때마다 추적기 객체의 trackPageView를 호출하기만 하면 됩니다. trackEvent를 호출하여 이벤트를 녹화합니다. 페이지 조회 및 이벤트에 대한 자세한 내용은 위의 SDK 개요를 참고하세요.

맞춤 변수 사용

맞춤 변수를 추가하는 방법도 간단합니다. 모바일 SDK에서 제공하는 setCustomVar 메서드를 사용하면 됩니다. 각 맞춤 변수가 매핑되는 색인을 미리 계획하여 이전의 기존 변수를 덮어쓰지 않도록 하는 것이 좋습니다. 맞춤 변수에 대한 자세한 내용은 맞춤 변수 가이드를 참고하세요. setCustomVar 메서드는 자체적으로 데이터를 직접 전송하지 않습니다. 대신 다음에 추적된 페이지 조회 또는 이벤트와 함께 데이터가 전송됩니다. 페이지 조회 또는 이벤트를 추적하기 전에 setCustomVar를 호출해야 합니다. 맞춤 변수의 기본 범위는 페이지 범위입니다.

전자상거래 추적 이용하기

애플리케이션에서 전자상거래 추적을 사용 설정하는 방법은 4가지입니다.

• addTransaction
• addItem
• trackTransactions
• clearTransactions

addTransaction 및 addItem를 호출하면 거래 또는 항목이 내부 전자상거래 버퍼에 추가되며 이 버퍼에 더 많은 항목과 거래를 추가할 수 있습니다. trackTransactions를 호출할 때만 거래와 항목이 디스패처로 전송되고 Google 애널리틱스로 전송되도록 큐에 추가됩니다.

버퍼를 삭제하려면 clearTransactions 메서드를 호출하면 됩니다. 참고: 이전에 운영자에게 전송된 거래나 Google 애널리틱스에서 이미 수집한 거래는 회수되지 않습니다.

다음 샘플 코드로 시작해 보세요. 구매가 확인되거나 거부될 때 onPurchaseCompleted 메서드가 호출된다고 가정합니다.

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   *
   * @param purchase A PurchaseObject containing all of the transaction information needed to
   *     send the ecommerce hit to Google Analytics.
   */
  public void onPurchaseCompleted(PurchaseObject purchase) {
    tracker.addTransaction(new Transaction.Builder(
        purchase.getTransactionId(),
        purchase.getTotal())
        .setStoreName(purchase.getStoreName())
        .setTotalTax(purchase.getTotalTax())
        .setShippingCost(purchase.getShippingCost())
        .build());
    for (PurchaseLineItem lineItem : purchase.getLineItems()) {
        tracker.addItem(new Item.Builder(
            purchase.getTransactionId(),
            lineItem.getItemSKU(),
            lineItem.getItemCost(),
            lineItem.getQuantity())
            .setItemName(lineItem.getItemName())
            .setItemCategory(lineItem.getItemCategory())
            .build());
    }
    if (purchase.isConfirmed()) {
      tracker.trackTransactions();
    } else {
      // The purchase was denied or failed in some way.  We need to clear out
      // any data we've already put in the Ecommerce buffer.
      tracker.clearTransactions();
    }
  }

전자상거래에 대한 자세한 내용은 전자상거래 추적 가이드를 참고하세요.

IP 익명 처리

사용자 IP 정보를 익명처리하려면 setAnonymizeIp 메서드를 사용합니다. 이렇게 하면 Google 애널리틱스에 저장 전에 IP 주소의 마지막 옥텟을 삭제하여 SDK에서 전송한 정보를 익명처리하도록 지시하게 됩니다.

언제든지 setAnonymizeIp번으로 전화를 걸 수 있습니다.

샘플링 레이트 설정

setSampleRate 메서드를 사용하여 샘플링 레이트를 설정할 수 있습니다. 애플리케이션에서 많은 애널리틱스 트래픽이 생성되는 경우 샘플링 레이트를 설정하면 샘플링된 데이터를 사용하여 보고서가 생성되지 않을 수 있습니다. 샘플링은 순 사용자를 대상으로 일관되게 이루어지므로 샘플링 레이트를 사용 설정하면 추세 및 보고에 무결성이 유지됩니다. setSampleRate 메서드는 하나의 int 매개변수를 허용합니다. 이 매개변수에 유효한 값은 0에서 100 사이의 정수입니다.

비율이 0이면 조회 생성이 중지되고 비율이 100이면 모든 데이터가 Google 애널리틱스로 전송됩니다. 추적 메서드를 호출하기 전에 setSampleRate를 호출하는 것이 가장 좋습니다.

샘플링에 대한 자세한 내용은 샘플링 개념 가이드를 참조하세요.

조회수 일괄 처리

연결 및 배터리 오버헤드를 절약하려면 추적 요청을 일괄 처리하는 것이 좋습니다. 일괄 요청을 할 때마다 추적 객체에서 dispatch를 호출할 수 있으며 이 작업은 수동으로 또는 특정 시간 간격으로 실행할 수 있습니다.

알려진 문제

다른 스레드에서 GoogleAnalyticsTracker 메서드를 호출하면 명확하지 않은 오류가 발생할 수 있습니다. 모든 호출은 동일한 스레드에서 실행해야 합니다.

캠페인 추적

SDK는 두 가지 유형의 캠페인 추적을 지원합니다.

- Google Play 캠페인 추적 – Google Play를 통해 설치 추천을 추적할 수 있습니다.
- 일반 캠페인 추적 – 사용자를 앱으로 연결하는 모든 캠페인을 추적할 수 있습니다.

Google Play 캠페인 추적

Android 1.6 OS 출시에서는 Google Play 다운로드 링크에서 referrer URL 매개변수 사용을 지원합니다. Android용 Google 애널리틱스 SDK는 이 매개변수를 사용하여 애플리케이션을 위해 Google 애널리틱스에서 캠페인 정보를 자동으로 채웁니다. 이렇게 하면 애플리케이션 설치 소스를 기록하고 향후 페이지뷰 및 이벤트와 연결할 수 있으며, 이를 통해 앱에 대한 특정 광고의 효과를 측정하는 데 유용할 수 있습니다.

추천 추적이 작동하려면 프로젝트의 AndroidManifest.xml 매니페스트 파일에 다음 코드 스니펫을 추가해야 합니다.

<!-- Used for install referrer tracking -->
<receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

Google Play를 통해 Google 애널리틱스 캠페인 추적을 설정하려면 아래의 URL 작성 도구를 사용하여 추천 링크를 생성하세요. 링크를 사용하여 사용자를 애플리케이션으로 안내하세요. 애널리틱스 SDK가 추천 정보를 자동으로 파싱 및 기록하고 애널리틱스 보고서에 채웁니다.

추천 링크를 생성하려면 Google Play 캠페인 URL 작성 도구를 사용하세요. 패키지 이름, 캠페인 소스, 캠페인 매체, 캠페인 이름은 필수 항목입니다. 각 매개변수에 관한 자세한 설명은 아래 표를 참고하세요.

일반 캠페인 추적

Android용 Google 애널리틱스 SDK 버전 1.3에서는 Google Play 이외의 소스에 대한 캠페인을 추적할 수 있습니다. 예를 들어 광고의 링크에서 애플리케이션이 실행되었는지 알아보려면 애플리케이션 실행을 유도한 인텐트에서 캠페인 추천 정보를 확인한 다음 이 캠페인 정보를 Google 애널리틱스에 저장하면 됩니다.

캠페인 추천 정보를 설정하려면 다음과 같이 setReferrer 메서드를 사용합니다.

  tracker.setReferrer(referrer);

이 기능을 사용하는 데는 두 가지 제한사항이 있습니다. 먼저 setReferrer를 호출하기 전에 startNewSession를 호출해야 합니다. 이렇게 해야 하는 이유는 Google 애널리틱스에서 사용하는 SQLite 데이터베이스가 startNewSession를 호출하기 전에 설정되지 않았고 setReferrer에 해당 데이터베이스가 필요하기 때문입니다. startNewSession를 호출하지 않았다면 IllegalStateException이 발생합니다.

두 번째 제한사항은 setReferrer에 전달된 추천 문자열이 특정 형식을 따라야 한다는 점입니다. URL 매개변수 집합의 형식을 취해야 하며 gclid 매개변수를 하나 이상 포함하거나 utm_campaign, utm_medium, utm_source의 각각 하나씩 포함해야 합니다. 후자의 경우 utm_term 및 utm_content 매개변수도 포함할 수 있습니다.

gclid 매개변수는 Google 애널리틱스와 Google Ads를 자동으로 연결하는 자동 태그 추가 기능의 일부입니다. 자동 태그 추가를 사용한 캠페인 추천의 예시는 다음과 같습니다.

referrer = “gclid=gclidValue”;

수동 캠페인 추천 문자열은 다음과 같이 표시됩니다.

referrer = “utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;

잘못된 형식의 리퍼러 문자열을 setReferrer에 전달하면 리퍼러 정보는 변경되지 않으며 false의 반환 값이 반환됩니다. 반환 값이 true이면 리퍼러가 업데이트되었으며, 앞으로 모든 조회에 추가될 예정임을 나타냅니다.

또한 setReferrer를 호출하고 true를 반환하면 새 세션이 시작됩니다.

추천 링크 매개변수

매개변수	필수	설명	예시
utm_campaign	예	캠페인 이름. 특정 제품 프로모션 또는 전략적 캠페인을 식별하기 위한 키워드 분석에 사용됩니다.	utm_campaign=spring_sale
utm_source	예	검색엔진, 뉴스레터 또는 기타 소스를 식별하는 데 사용되는 캠페인 소스	utm_source=google
utm_medium	예	캠페인 매체: 이메일 또는 클릭당비용 (CPC)과 같은 매체를 식별하는 데 사용됨	utm_medium=cpc
utm_term	아니요	광고 키워드를 제공하기 위해 유료 검색과 함께 사용되는 캠페인 검색어	utm_term=running+shoes
utm_content	아니요	캠페인 콘텐츠: 동일한 URL을 가리키는 광고 또는 링크를 구분하기 위해 A/B 테스트 및 콘텐츠 타겟팅 광고에 사용됨	utm_content=logolink utm_content=textlink