Android v4 - Memulai

Catatan: Panduan ini menjelaskan penerapan lama Google Tag Manager di aplikasi Android. Pengguna baru harus menggunakan Tag Manager + Firebase untuk menerapkan Google Tag Manager di aplikasi Android mereka.

Pengantar

Dengan Google Tag Manager, developer dapat mengubah nilai konfigurasi di aplikasi selulernya menggunakan antarmuka Google Tag Manager tanpa harus membuat ulang dan mengirim ulang biner aplikasi ke marketplace aplikasi.

Hal ini berguna untuk mengelola setiap nilai atau flag konfigurasi dalam aplikasi yang mungkin perlu Anda ubah di masa mendatang, termasuk:

• Berbagai setelan UI dan string tampilan
• Ukuran, lokasi, atau jenis iklan yang ditayangkan di aplikasi Anda
• Berbagai setelan Game

Nilai konfigurasi juga dapat dievaluasi saat runtime menggunakan aturan, yang mengaktifkan konfigurasi dinamis seperti:

• Menggunakan ukuran layar untuk menentukan ukuran banner iklan
• Menggunakan bahasa dan lokasi untuk mengonfigurasi elemen UI

Google Tag Manager juga memungkinkan penerapan dinamis tag dan piksel pelacakan dalam aplikasi. Developer dapat mendorong peristiwa penting ke dalam lapisan data dan menentukan nanti tag atau piksel pelacakan mana yang harus diaktifkan.

Sebelum Memulai

Selesaikan langkah-langkah berikut sebelum Anda memulai panduan memulai ini:

• Instal Android SDK
• Download SDK Layanan Google Play
• Buat akun Google Tag Manager
• Mengonfigurasi penampung Google Tag Manager

Setelah menyelesaikan langkah-langkah tersebut, bagian selanjutnya dari panduan ini akan memandu Anda melalui cara mengonfigurasi dan menggunakan Google Tag Manager dalam aplikasi Android.

Memulai

Setelah mengikuti panduan Memulai ini, Anda akan memahami cara:

• Menambahkan Google Tag Manager ke project
• Melakukan inisialisasi Tag Manager di aplikasi Anda
• Mendapatkan nilai konfigurasi dari penampung Tag Manager
• Mendorong nilai dan peristiwa ke dalam dataLayer
• Melihat pratinjau, men-debug, dan memublikasikan penampung

Panduan ini menggunakan cuplikan kode dari aplikasi contoh Cute Animals yang disertakan dengan SDK Layanan Google Play. Sumber lengkap untuk project ini tersedia di: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. Menambahkan Google Tag Manager ke Project Anda

Untuk menambahkan Google Tag Manager ke project Anda:

1. Siapkan SDK Layanan Google Play.
2. Jika Anda menggunakan IDE selain Android Studio, tambahkan izin berikut ke file AndroidManifest.xml:

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

3. Agar InstallReferrerReceiver dapat memanggil penerima Google Analytics untuk menetapkan data kampanye, tambahkan hal berikut ke file 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. Menambahkan File Penampung Default ke Project Anda

Catatan: Jika belum mengonfigurasi penampung di antarmuka web Google Tag Manager, kembali ke langkah ini setelah Anda selesai.

Google Tag Manager menggunakan penampung default saat aplikasi Anda pertama kali dijalankan. Penampung default akan berhenti digunakan begitu aplikasi dapat mengambil penampung baru melalui jaringan.

Untuk mendownload dan menambahkan biner container default ke aplikasi Anda:

1. Login ke antarmuka web Google Tag Manager.
2. Pilih Versi penampung yang ingin Anda download.
3. Klik tombol Download untuk mengambil biner penampung.
4. Tambahkan file biner container yang didownload ke project Anda sebagai resource mentah.
   1. Jika subfolder raw di bawah <project-root>/res/ tidak ada, buat subfolder tersebut.
   2. Ganti nama file biner container jika perlu. Kode ini hanya terdiri dari huruf kecil, angka, dan garis bawah.
   3. Salin file biner container ke folder <project-root>/res/raw.

Meskipun penggunaan file biner direkomendasikan, jika penampung Anda tidak berisi aturan atau tag, Anda dapat memilih untuk menggunakan file JSON sederhana.

3. Menginisialisasi Google Tag Manager

Untuk melakukan inisialisasi Google Tag Manager di aplikasi Anda:

1. Dapatkan singleton TagManager:

   TagManager tagManager = TagManager.getInstance(this);
   

2. Gunakan singleton TagManager untuk membuat permintaan untuk memuat penampung, yang menentukan ID penampung Google Tag Manager serta file penampung default Anda. ID penampung harus berhuruf besar dan sama persis dengan ID penampung di antarmuka web Google Tag Manager. Panggilan ke loadContainerPreferNonDefault() tidak memblokir dan menampilkan PendingResult:

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

3. Gunakan ResultCallback untuk menampilkan ContainerHolder setelah selesai dimuat atau waktu habis:

   // 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);
   

   Catatan: Secara default, penampung memenuhi syarat untuk dimuat ulang melalui jaringan setiap 12 jam. Pelajari cara memuat ulang penampung secara manual.

   Membuat Singleton ContainerHolder

   Anda hanya boleh mempertahankan satu instance ContainerHolder per run aplikasi. Itulah sebabnya contoh di atas menggunakan class utilitas ContainerHolderSingleton untuk mengelola akses ke instance ContainerHolder. Class ContainerHolderSingleton akan terlihat seperti berikut:

   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;
       }
   }
   
   

Melihat Cuplikan Kode dari Contoh Aplikasi

Cuplikan berikut menunjukkan pola lengkap yang diimplementasikan dalam metode onCreate() dari contoh Activity:

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. Mendapatkan Nilai Konfigurasi dari Container

Setelah penampung dimuat, Anda dapat mengambil nilai konfigurasi menggunakan salah satu metode Container.get<type>(). Nilai konfigurasi ditentukan menggunakan variabel kumpulan nilai Google Tag Manager. Misalnya, metode berikut mengambil warna terbaru yang telah kita putuskan untuk digunakan bagi elemen UI dan menampilkannya sebagai bilangan bulat:

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

Kode ini melakukan dua hal untuk mengambil nama warna dari container:

1. Mendapatkan Container dari ContainerHolder menggunakan ContainerHolder.getContainer().
2. Mendapatkan nilai warna menggunakan Container.getString(key), tempat Anda telah menentukan kunci dan nilai di antarmuka web Google Tag Manager.

5. Mendorong Peristiwa dan Nilai ke dataLayer

Google Tag Manager juga menyediakan dataLayer, tempat Anda dapat mengirim informasi tentang aplikasi yang dapat dibaca di bagian lain aplikasi atau digunakan untuk mengaktifkan tag yang telah Anda konfigurasi di antarmuka web Google Tag Manager.

Mendorong Nilai ke dataLayer

dataLayer menyediakan lapisan persistensi yang dapat digunakan untuk menyimpan key-value pair yang mungkin ingin Anda gunakan di bagian lain dalam aplikasi, atau sebagai input untuk tag Google Tag Manager.

Untuk mengirim nilai ke dataLayer, ikuti pola ini:

1. Dapatkan singleton DataLayer:

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

2. Kirim peristiwa menggunakan DataLayer.push():

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

Untuk mendapatkan nilai dari dataLayer, gunakan DataLayer.get(key).

Mendorong Peristiwa ke dataLayer

Mengirim peristiwa ke dataLayer memungkinkan Anda memisahkan kode aplikasi dari tag yang mungkin ingin diaktifkan sebagai respons terhadap peristiwa tersebut.

Misalnya, daripada melakukan hard-coding terhadap panggilan pelacakan tampilan layar Google Analytics ke aplikasi, Anda dapat mengirim peristiwa layar ke dataLayer dan menentukan tag pelacakan melalui antarmuka web Google Tag Manager. Dengan demikian, Anda memiliki fleksibilitas untuk mengubah tag tersebut, atau menambahkan tag lain yang merespons peristiwa layar, tanpa memperbarui kode aplikasi.

Untuk mengirim peristiwa ke dataLayer, ikuti pola ini:

1. Dapatkan singleton DataLayer:

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

2. Kirim peristiwa menggunakan DataLayer.pushEvent():

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

   DataLayer.mapOf() adalah metode utilitas yang dapat Anda gunakan untuk membuat peta key-value pair dengan mudah yang akan memperbarui dataLayer pada saat peristiwa yang sama dikirim.

Melihat Cuplikan Kode dari Contoh Aplikasi

Class utilitas berikut menunjukkan cara mendorong peristiwa, seperti informasi tentang layar yang membuka dan menutup aplikasi, pada 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. Pratinjau, Proses Debug, dan Publikasi

Sebelum memublikasikan versi penampung, Anda dapat melihat pratinjaunya untuk memastikan penampung tersebut berfungsi sebagaimana mestinya. Google Tag Manager memungkinkan Anda melihat pratinjau versi penampung dengan membuat link dan kode QR di antarmuka web dan menggunakannya untuk membuka aplikasi Anda. Anda juga dapat mengaktifkan mode logging panjang untuk men-debug perilaku yang tidak terduga.

Menampilkan pratinjau

Untuk melihat pratinjau versi penampung, ikuti langkah-langkah berikut:

1. Menambahkan Activity pratinjau ini ke file AndroidManifest Anda:

   <!--  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>
   

   Pastikan untuk mengubah baris ini agar menyertakan nama paket aplikasi Anda:

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

2. Membuat link pratinjau di antarmuka web Google Tag Manager
   1. Login ke Google Tag Manager
   2. Pilih penampung Versi yang akan dipratinjau
   3. Klik tombol Pratinjau
   4. Masukkan nama paket aplikasi Anda, lalu klik Buat link memulai pratinjau
3. Gunakan link atau Kode QR yang dibuat untuk meluncurkan aplikasi Anda
4. Anda dapat keluar dari mode pratinjau dengan mengikuti link yang dibuat oleh opsi Buat link akhiri pratinjau di antarmuka web.

Proses debug

Jika Anda perlu memecahkan masalah penerapan penampung, aktifkan logging panjang dengan memanggil 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);

Memublikasikan

Setelah melihat pratinjau penampung dan memastikan penampung tersebut berfungsi sebagaimana mestinya, Anda dapat memublikasikan penampung. Nilai, tag, dan peristiwa konfigurasi penampung Anda akan aktif untuk pengguna saat penampung dimuat ulang lagi. Pelajari lebih lanjut cara memuat ulang penampung.

Konfigurasi Lanjutan

Bagian berikut menjelaskan opsi konfigurasi lanjutan yang ingin Anda gunakan untuk menyesuaikan penerapan Google Tag Manager lebih lanjut.

Memuat Ulang Container

Secara default, penampung Anda memenuhi syarat untuk diperbarui setiap 12 jam. Untuk memuat ulang penampung secara manual, gunakan ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Ini adalah panggilan asinkron yang tidak akan segera ditampilkan. Untuk mengurangi traffic jaringan, refresh() hanya dapat dipanggil sekali setiap 15 menit. Jika tidak, panggilan tidak akan beroperasi.

Catatan: Cuplikan ini menggunakan class utilitas ContainerHolderSingleton yang dijelaskan dalam contoh inisialisasi di atas.

Melihat Cuplikan Kode dari Contoh Aplikasi

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();
}