Android v4 - Memulai

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

Pengantar

Google Tag Manager memungkinkan developer mengubah nilai konfigurasi di aplikasi seluler mereka menggunakan antarmuka Google Tag Manager tanpa harus membuat ulang dan mengirim ulang biner aplikasi ke marketplace aplikasi.

Hal ini berguna untuk mengelola nilai konfigurasi atau flag apa pun di aplikasi yang mungkin Anda perlukan yang akan diubah di masa depan, termasuk:

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

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

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

Google TagManager juga memungkinkan penerapan dinamis tag dan piksel pelacakan di menggunakan berbagai aplikasi obrolan. Developer dapat mendorong peristiwa penting ke lapisan data dan kemudian memutuskan peristiwa yang akan tag atau piksel pelacakan harus diaktifkan.

Sebelum Anda Mulai

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 Anda menyelesaikan langkah-langkah ini, bagian selanjutnya dari panduan ini akan memandu Anda tentang cara mengonfigurasi dan menggunakan Google Tag Manager dalam aplikasi Android Anda.

Memulai

Setelah mengikuti panduan Memulai ini, Anda akan memahami cara:

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

Panduan ini menggunakan cuplikan kode dari Cute Animals aplikasi contoh 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. Untuk mengaktifkan InstallReferrerReceiver untuk memanggil penerima Google Analytics Untuk menetapkan data kampanye, tambahkan hal berikut ke bagian 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 Anda belum mengonfigurasi penampung Anda di antarmuka web Google Tag Manager, kembali ke langkah ini setelah Anda melakukannya.

Google Tag Manager menggunakan penampung default saat pertama kali aplikasi Anda dijalankan. Default akan berhenti digunakan segera setelah aplikasi dapat mengambil container 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 ada di bawah <project-root>/res/ tidak ada, buat saja.
   2. Ganti nama file biner penampung jika perlu. Hanya terdiri dari huruf kecil, angka, dan garis bawah.
   3. Salin file biner container ke folder <project-root>/res/raw.

Meskipun sebaiknya gunakan file biner, jika penampung Anda tidak berisi aturan atau tag, Anda dapat memilih untuk menggunakan file JSON sederhana sebagai gantinya.

3. Melakukan inisialisasi 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 guna memuat container, yang menentukan ID penampung Google Tag Manager serta penampung default Anda . ID penampung harus huruf besar dan sama persis dengan ID penampung di Tag Google Antarmuka web pengelola. Panggilan ke loadContainerPreferNonDefault() tidak bersifat memblokir dan mengembalikan PendingResult:

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

3. Gunakan ResultCallback untuk menampilkan ContainerHolder setelah pemuatan selesai 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 pengoperasian aplikasi. Itulah sebabnya contoh di atas menggunakan class utilitas ContainerHolderSingleton untuk mengelola akses ke instance ContainerHolder. Berikut adalah hal yang Class ContainerHolderSingleton terlihat seperti ini:

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

Lihat Cuplikan Kode dari Aplikasi Contoh

Cuplikan berikut menunjukkan pola lengkap yang diterapkan 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 Penampung

Setelah kontainer 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 dalam 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), jika Anda memiliki 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 memasukkan informasi aplikasi Anda yang dapat dibaca di bagian lain aplikasi atau digunakan untuk mengaktifkan tag yang telah Anda konfigurasikan di antarmuka web Google Tag Manager.

Mendorong Nilai ke dataLayer

dataLayer menyediakan lapisan persistensi yang dapat Anda gunakan untuk menyimpan pasangan nilai kunci yang mungkin ingin Anda gunakan di bagian lain 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. Mengirim 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 Anda aktifkan sebagai respons terhadap peristiwa tersebut.

Misalnya, sebagai ganti melakukan {i>hard-coding<i} tampilan layar Google Analytics panggilan ke aplikasi Anda, Anda dapat mengirim peristiwa layar ke dataLayer dan menentukan tag pelacakan melalui Antarmuka web Google Tag Manager. Hal ini memberi Anda fleksibilitas untuk mengubah tag tersebut, atau menambahkan tag tambahan yang merespons peristiwa layar, tanpa memperbarui kode aplikasi Anda.

Untuk mengirim peristiwa ke dataLayer, ikuti pola ini:

1. Dapatkan Singleton DataLayer:

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

2. Mengirim peristiwa menggunakan DataLayer.pushEvent():

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

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

Lihat Cuplikan Kode dari Aplikasi Contoh

Class utilitas berikut menunjukkan cara mendorong peristiwa, seperti informasi tentang layar membuka dan menutup di aplikasi Anda, 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 melakukan pratinjau untuk memastikan penampung berfungsi sebagaimana mestinya. Google Tag Manager memberi Anda kemampuan untuk melihat pratinjau versi penampung dengan membuat link dan kode QR di antarmuka web dan menggunakannya untuk membuka aplikasi. Anda juga dapat mengaktifkan mode logging panjang untuk men-debug perilaku yang tidak terduga.

Menampilkan pratinjau

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

1. Menambahkan pratinjau ini Activity 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 memodifikasi baris ini untuk 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 Versi penampung untuk melihat pratinjaunya
   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 Buat link akhiri pratinjau di antarmuka web.

Proses Debug

Jika Anda perlu memecahkan masalah penerapan container, 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);

Publikasi

Setelah melihat pratinjau penampung dan memastikan bahwa penampung berfungsi sebagaimana mestinya, Anda dapat publikasikan penampung. Nama nilai konfigurasi penampung, tag, dan peristiwa akan tersedia untuk pengguna saat container diperbarui. Pelajari lebih lanjut cara memuat ulang penampung.

Konfigurasi Lanjutan

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

Memuat Ulang Penampung

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

ContainerHolderSingleton.getContainerHolder().refresh();

Ini adalah panggilan asinkron yang tidak akan segera ditampilkan. Untuk mengurangi traffic jaringan, refresh() mungkin hanya dipanggil sekali setiap 15 menit, jika tidak maka sistem tidak akan dioperasikan.

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

Lihat Cuplikan Kode dari Aplikasi Contoh

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