Android v4 - 시작하기

참고: 이 가이드에서는 Android 애플리케이션에서 Google 태그 관리자의 기존 구현을 설명합니다. 신규 사용자는 태그 관리자 + Firebase를 사용하여 Android 애플리케이션에서 Google 태그 관리자를 구현해야 합니다.

소개

Google 태그 관리자를 사용하면 개발자가 애플리케이션 바이너리를 다시 빌드하고 앱 마켓에 다시 제출할 필요 없이 Google 태그 관리자 인터페이스를 사용하여 모바일 애플리케이션의 구성 값을 변경할 수 있습니다.

이 기능은 다음과 같이 애플리케이션에서 향후 변경이 필요할 수 있는 모든 구성 값이나 플래그를 관리하는 데 유용합니다.

• 다양한 UI 설정 및 표시 문자열
• 애플리케이션에 게재되는 광고의 크기, 위치 또는 유형
• 다양한 게임 설정

구성 값은 런타임 시 규칙을 사용하여 평가할 수도 있으며 다음과 같은 동적 구성을 사용 설정합니다.

• 화면 크기를 사용하여 광고 배너 크기 결정
• 언어 및 위치를 사용하여 UI 요소 구성

또한 Google TagManager를 사용하면 애플리케이션에서 추적 태그 및 픽셀을 동적으로 구현할 수 있습니다. 개발자는 중요한 이벤트를 데이터 영역으로 푸시하고, 실행할 추적 태그 또는 픽셀을 나중에 결정할 수 있습니다.

시작하기 전에

이 시작 가이드를 시작하기 전에 다음 단계를 완료하세요.

• Android SDK를 설치합니다.
• Google Play 서비스 SDK 다운로드
• Google 태그 관리자 계정을 만듭니다.
• Google 태그 관리자 컨테이너 구성하기

이 단계를 완료한 후 이 가이드의 나머지 부분에서는 Android 애플리케이션에서 Google 태그 관리자를 구성하고 사용하는 방법을 안내합니다.

시작하기

시작 가이드를 마치면 다음 작업을 수행하는 방법을 이해하게 됩니다.

• 프로젝트에 Google 태그 관리자 추가
• 애플리케이션에서 태그 관리자 초기화하기
• 태그 관리자 컨테이너에서 구성 값 가져오기
• 값 및 이벤트를 dataLayer에 푸시
• 컨테이너 미리보기, 디버그, 게시

이 가이드에서는 Google Play 서비스 SDK에 포함된 Cute Animals 샘플 애플리케이션의 코드 스니펫을 사용합니다. 이 프로젝트의 전체 소스는 <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals에서 확인할 수 있습니다.

1. 프로젝트에 Google 태그 관리자 추가하기

프로젝트에 Google 태그 관리자를 추가하는 방법은 다음과 같습니다.

1. Google Play 서비스 SDK를 설정합니다.
2. Android 스튜디오 이외의 IDE를 사용하는 경우 다음 권한을 AndroidManifest.xml 파일에 추가합니다.

   <!-- For TagManager SDK -->
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   

3. InstallReferrerReceiver에서 Google 애널리틱스 수신기를 호출하여 캠페인 데이터를 설정하도록 하려면 AndroidManifest.xml 파일에 다음을 추가합니다.

   <!-- Used for install referrer tracking-->
   <service android:name="com.google.android.gms.tagmanager.InstallReferrerService" />
   <receiver
     android:name="com.google.android.gms.tagmanager.InstallReferrerReceiver"
     android:exported="true">
     <intent-filter>
       <action android:name="com.android.vending.INSTALL_REFERRER" />
     </intent-filter>
   </receiver>
   

2. 프로젝트에 기본 컨테이너 파일 추가

참고: 아직 Google 태그 관리자 웹 인터페이스에서 컨테이너를 구성하지 않은 경우 구성을 완료한 후 이 단계로 돌아오세요.

Google 태그 관리자는 애플리케이션을 처음 실행할 때 기본 컨테이너를 사용합니다. 기본 컨테이너는 앱이 네트워크를 통해 새 컨테이너를 가져올 수 있게 되면 즉시 사용되지 않습니다.

기본 컨테이너 바이너리를 다운로드하여 애플리케이션에 추가하려면 다음 안내를 따르세요.

1. Google 태그 관리자 웹 인터페이스에 로그인합니다.
2. 다운로드할 컨테이너의 버전을 선택합니다.
3. 다운로드 버튼을 클릭하여 컨테이너 바이너리를 검색합니다.
4. 다운로드한 컨테이너 바이너리 파일을 프로젝트에 원시 리소스로 추가합니다.
   1. <project-root>/res/ 아래에 raw 하위 폴더가 없으면 새로 만듭니다.
   2. 필요한 경우 컨테이너 바이너리 파일의 이름을 바꿉니다. 소문자, 숫자, 밑줄로만 구성됩니다.
   3. 컨테이너 바이너리 파일을 <project-root>/res/raw 폴더에 복사합니다.

바이너리 파일을 사용하는 것이 좋지만 컨테이너에 규칙이나 태그가 포함되어 있지 않으면 간단한 JSON 파일을 대신 사용할 수도 있습니다.

3. Google 태그 관리자 초기화

애플리케이션에서 Google 태그 관리자를 초기화하는 방법은 다음과 같습니다.

1. TagManager 싱글톤을 가져옵니다.

   TagManager tagManager = TagManager.getInstance(this);
   

2. TagManager 싱글톤을 사용하여 컨테이너 로드 요청을 실행하고 Google 태그 관리자 컨테이너 ID와 기본 컨테이너 파일을 지정합니다. 컨테이너 ID는 대문자여야 하며 Google 태그 관리자 웹 인터페이스의 컨테이너 ID와 정확하게 일치해야 합니다. loadContainerPreferNonDefault() 호출은 비블로킹이며 PendingResult를 반환합니다.

   PendingResult<ContainerHolder> pending =
           tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
           R.raw.defaultcontainer_binary);
   

3. 로드가 완료되거나 타임아웃되면 ResultCallback를 사용하여 ContainerHolder를 반환합니다.

   // The onResult method will be called as soon as one of the following happens:
   //     1. a saved container is loaded
   //     2. if there is no saved container, a network container is loaded
   //     3. the 2-second timeout occurs
   pending.setResultCallback(new ResultCallback<ContainerHolder>() {
       @Override
       public void onResult(ContainerHolder containerHolder) {
           ContainerHolderSingleton.setContainerHolder(containerHolder);
           Container container = containerHolder.getContainer();
           if (!containerHolder.getStatus().isSuccess()) {
               Log.e("CuteAnimals", "failure loading container");
               displayErrorToUser(R.string.load_error);
               return;
           }
           ContainerLoadedCallback.registerCallbacksForContainer(container);
           containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
           startMainActivity();
       }
   }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
   

   참고: 기본적으로 컨테이너는 네트워크를 통해 12시간마다 새로고침될 수 있습니다. 컨테이너를 수동으로 새로고침하는 방법 알아보기

   ContainerHolder 싱글톤 만들기

   애플리케이션을 실행할 때마다 ContainerHolder 인스턴스를 하나만 유지해야 합니다. 따라서 위의 예에서는 ContainerHolderSingleton 유틸리티 클래스를 사용하여 ContainerHolder 인스턴스에 대한 액세스를 관리합니다. ContainerHolderSingleton 클래스는 다음과 같이 표시됩니다.

   package com.google.android.tagmanager.examples.cuteanimals;
   
   import com.google.android.gms.tagmanager.ContainerHolder;
   
   /**
    * Singleton to hold the GTM Container (since it should be only created once
    * per run of the app).
    */
   public class ContainerHolderSingleton {
       private static ContainerHolder containerHolder;
   
       /**
        * Utility class; don't instantiate.
        */
       private ContainerHolderSingleton() {
       }
   
       public static ContainerHolder getContainerHolder() {
           return containerHolder;
       }
   
       public static void setContainerHolder(ContainerHolder c) {
           containerHolder = c;
       }
   }
   
   

샘플 애플리케이션의 코드 스니펫 보기

다음 스니펫은 샘플 Activity의 onCreate() 메서드에 구현된 전체 패턴을 보여줍니다.

package com.google.android.tagmanager.examples.cuteanimals;

import java.util.concurrent.TimeUnit;
import java.util.Map;

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.content.Intent;
import android.os.Bundle;
import android.util.Log;

import com.google.android.gms.common.api.PendingResult;
import com.google.android.gms.common.api.ResultCallback;
import com.google.android.gms.tagmanager.Container;
import com.google.android.gms.tagmanager.Container.FunctionCallMacroCallback;
import com.google.android.gms.tagmanager.Container.FunctionCallTagCallback;
import com.google.android.gms.tagmanager.ContainerHolder;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Displays simple splash screen while GTM container is loading. Once the container is loaded,
 * launches the {@link MainActivity}.
 */
public class SplashScreenActivity extends Activity {
    private static final long TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS = 2000;
    private static final String CONTAINER_ID = "GTM-XXXX";

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_splashscreen);

        TagManager tagManager = TagManager.getInstance(this);

        // Modify the log level of the logger to print out not only
        // warning and error messages, but also verbose, debug, info messages.
        tagManager.setVerboseLoggingEnabled(true);

        PendingResult<ContainerHolder> pending =
                tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
                R.raw.defaultcontainer_binary);

        // The onResult method will be called as soon as one of the following happens:
        //     1. a saved container is loaded
        //     2. if there is no saved container, a network container is loaded
        //     3. the 2-second timeout occurs
        pending.setResultCallback(new ResultCallback<ContainerHolder>() {
            @Override
            public void onResult(ContainerHolder containerHolder) {
                ContainerHolderSingleton.setContainerHolder(containerHolder);
                Container container = containerHolder.getContainer();
                if (!containerHolder.getStatus().isSuccess()) {
                    Log.e("CuteAnimals", "failure loading container");
                    displayErrorToUser(R.string.load_error);
                    return;
                }
                ContainerLoadedCallback.registerCallbacksForContainer(container);
                containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
                startMainActivity();
            }
        }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
  // Rest of the Activity definition.
}

4. 컨테이너에서 구성 값 가져오기

컨테이너가 로드되면 Container.get<type>() 메서드 중 하나를 사용하여 구성 값을 검색할 수 있습니다. 구성 값은 Google 태그 관리자의 값 컬렉션 변수를 사용하여 정의됩니다. 예를 들어 다음 메서드는 UI 요소에 사용하기로 결정한 최신 색상을 가져와 정수로 반환합니다.

/**
 * Returns an integer representing a color.
 */
private int getColor(String key) {
    return colorFromColorName(containerHolder.getContainer().getString(key));
}

이 코드는 두 가지 작업을 통해 컨테이너에서 색상 이름을 가져옵니다.

1. ContainerHolder.getContainer()를 사용하여 ContainerHolder에서 Container를 가져옵니다.
2. Google 태그 관리자 웹 인터페이스에서 키와 값을 정의한 경우, Container.getString(key)를 사용하여 색상 값을 가져옵니다.

5. dataLayer에 이벤트 및 값 푸시하기

Google 태그 관리자는 또한 dataLayer를 제공합니다. 이 정보를 통해 애플리케이션의 다른 부분에서 읽을 수 있거나 Google 태그 관리자 웹 인터페이스에서 구성한 태그를 실행하는 데 사용할 수 있는 애플리케이션 정보를 푸시할 수 있습니다.

dataLayer에 값 푸시하기

dataLayer는 애플리케이션의 다른 부분에서 사용하거나 Google 태그 관리자 태그에 대한 입력으로 사용하려는 키-값 쌍을 저장하는 데 사용할 수 있는 지속성 레이어를 제공합니다.

값을 dataLayer에 푸시하려면 다음 패턴을 따르세요.

1. DataLayer 싱글톤을 가져옵니다.

   DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
   

2. DataLayer.push()를 사용하여 이벤트 푸시:

   // Put the image_name into the data layer for future use.
   TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);
   

dataLayer에서 값을 가져오려면 DataLayer.get(key)를 사용합니다.

dataLayer에 이벤트 푸시

이벤트를 dataLayer에 푸시하면 해당 이벤트에 대한 응답으로 실행하려는 태그와 애플리케이션 코드를 분리할 수 있습니다.

예를 들어 Google 애널리틱스 화면 조회수 추적 호출을 애플리케이션에 하드 코딩하는 대신 dataLayer에 화면 이벤트를 푸시하고 Google 태그 관리자 웹 인터페이스를 통해 추적 태그를 정의할 수 있습니다. 이렇게 하면 애플리케이션 코드를 업데이트하지 않고도 유연하게 태그를 수정하거나 화면 이벤트에 응답하는 태그를 추가할 수 있습니다.

이벤트를 dataLayer에 푸시하려면 다음 패턴을 따르세요.

1. DataLayer 싱글톤을 가져옵니다.

   DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
   

2. DataLayer.pushEvent()를 사용하여 이벤트 푸시:

   dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
   

   DataLayer.mapOf()는 이벤트가 푸시되는 동시에 dataLayer를 업데이트하는 키-값 쌍의 맵을 쉽게 생성하는 데 사용할 수 있는 유틸리티 메서드입니다.

샘플 애플리케이션의 코드 스니펫 보기

다음 유틸리티 클래스는 앱에서 화면 열기 및 닫기에 관한 정보와 같은 이벤트를 dataLayer에 푸시하는 방법을 보여줍니다.

package com.google.android.tagmanager.examples.cuteanimals;

import android.content.Context;

import com.google.android.gms.tagmanager.DataLayer;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Utility class.
 */
public class Utils {
    private Utils() {
        // private constructor.
    }

    /**
     * Push an "openScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushOpenScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
    }

    /**
     * Push a "closeScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushCloseScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("closeScreen", DataLayer.mapOf("screenName", screenName));
    }
}

6. 미리보기, 디버깅 및 게시

컨테이너 버전을 게시하기 전에 미리 보고 의도한 대로 작동하는지 확인하는 것이 좋습니다. Google 태그 관리자를 사용하면 웹 인터페이스에서 링크와 QR 코드를 생성하고 이를 사용해 애플리케이션을 열어 컨테이너의 버전을 미리 볼 수 있습니다. 상세 로깅 모드를 사용 설정하여 예상치 못한 동작을 디버그할 수도 있습니다.

미리보기 중

컨테이너 버전을 미리 보려면 다음 단계를 따르세요.

1. 이 미리보기 Activity을 AndroidManifest 파일에 추가합니다.

   <!--  Add preview activity. -->
   <activity
       android:name="com.google.android.gms.tagmanager.PreviewActivity"
       android:label="@string/app_name"
       android:noHistory="true">  <!-- optional, removes the previewActivity from the activity stack. -->
       <intent-filter>
         <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
         <action android:name="android.intent.action.VIEW" />
         <category android:name="android.intent.category.DEFAULT" />
         <category android:name="android.intent.category.BROWSABLE"/>
       </intent-filter>
   </activity>
   

   애플리케이션의 패키지 이름을 포함하도록 이 줄을 수정해야 합니다.

   <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
   

2. Google 태그 관리자 웹 인터페이스에서 미리보기 링크를 생성합니다.
   1. Google 태그 관리자에 로그인합니다.
   2. 미리 볼 컨테이너 버전을 선택합니다.
   3. 미리보기 버튼을 클릭합니다
   4. 애플리케이션의 패키지 이름을 입력하고 미리보기 시작하기 링크 생성을 클릭합니다.
3. 생성된 링크 또는 QR 코드를 사용하여 애플리케이션을 실행하세요.
4. 웹 인터페이스의 미리보기 종료하기 링크 생성 옵션에서 생성된 링크를 따라 미리보기 모드를 종료할 수 있습니다.

디버깅

컨테이너 구현 문제를 해결해야 한다면 TagManager.setVerboseLoggingEnabled(true)를 호출하여 상세 로깅을 사용 설정하세요.

// Modify the log level of the logger to print out not only
// warning and error messages, but also verbose, debug, info messages.
tagManager.setVerboseLoggingEnabled(true);

게시

컨테이너를 미리 보고 의도한 대로 작동하는지 확인한 후 컨테이너를 게시할 수 있습니다. 컨테이너 구성 값, 태그, 이벤트는 다음에 컨테이너를 새로고침할 때 사용자에게 표시됩니다. 컨테이너 새로고침에 대해 자세히 알아보기

고급 구성

다음 섹션에서는 Google 태그 관리자 구현을 추가로 맞춤설정하는 데 사용할 고급 구성 옵션을 설명합니다.

컨테이너 새로고침

기본적으로 컨테이너는 12시간마다 새로고침될 수 있습니다. 컨테이너를 수동으로 새로고침하려면 ContainerHolder.refresh()를 사용하세요.

ContainerHolderSingleton.getContainerHolder().refresh();

즉시 반환되지 않는 비동기 호출입니다. 네트워크 트래픽을 줄이기 위해 refresh()는 15분마다 한 번만 호출될 수 있으며, 그렇지 않으면 노옵스(no-ops)가 됩니다.

참고: 이 스니펫은 위의 초기화 예에서 설명한 ContainerHolderSingleton 유틸리티 클래스를 사용합니다.

샘플 애플리케이션의 코드 스니펫 보기

public void refreshButtonClicked(@SuppressWarnings("unused") View view) {
    Log.i(TAG, "refreshButtonClicked");
    ContainerHolderSingleton.getContainerHolder().refresh();

    // Push the "refresh" event to trigger firing an analytics tag.
    TagManager.getInstance(this).getDataLayer().push("event", "refresh");
    // Push the "custom tag" event to trigger firing a custom function call tag.
    TagManager.getInstance(this).getDataLayer().push("event", "custom_tag");
    updateCategories();
}