Android v4 (Lama) - Memulai

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 atau flag konfigurasi apa pun di aplikasi Anda yang mungkin perlu diubah 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, sehingga memungkinkan 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 pelacakan dan piksel di aplikasi. Developer dapat mengirim peristiwa penting ke lapisan data, lalu menentukan tag pelacak atau piksel mana yang harus diaktifkan.

Sebelum Anda Mulai

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

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

Memulai

Setelah mengikuti panduan Memulai ini, Anda akan memahami cara:

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. Menyiapkan 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 agar memanggil penerima Google Analytics untuk menetapkan data kampanye, tambahkan kode 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

Google Tag Manager menggunakan penampung default pada pengoperasian pertama aplikasi Anda. Penampung default akan berhenti digunakan segera setelah aplikasi dapat mengambil penampung baru melalui jaringan.

Untuk mendownload dan menambahkan biner penampung 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 container.
  4. Tambahkan file biner penampung yang didownload ke project Anda sebagai resource mentah.
    1. Jika subfolder raw di bagian <project-root>/res/ tidak ada, buat subfolder tersebut.
    2. Ganti nama file biner container jika perlu. Nama ini 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.

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 pemuatan penampung, dengan menentukan ID penampung Google Tag Manager serta file penampung default Anda. ID penampung harus menggunakan huruf besar dan sama persis dengan ID penampung di antarmuka web Google Tag Manager. Panggilan ke loadContainerPreferNonDefault() bersifat non-pemblokiran 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 tunggu 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);

    Membuat Singleton ContainerHolder

    Anda hanya boleh mengelola satu instance ContainerHolder per operasi aplikasi. Itulah sebabnya contoh di atas menggunakan class utilitas ContainerHolderSingleton untuk mengelola akses ke instance ContainerHolder. Berikut adalah tampilan class ContainerHolderSingleton tersebut:

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

4. Mendapatkan Nilai Konfigurasi dari Penampung

Setelah penampung dimuat, Anda dapat mengambil nilai konfigurasi menggunakan salah satu metode Container.get<type>(). Nilai konfigurasi ditentukan menggunakan variabel pengumpulan 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 penampung:

  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, yang dapat Anda gunakan untuk mengirim informasi tentang aplikasi Anda yang dapat dibaca di bagian lain aplikasi atau digunakan untuk mengaktifkan tag yang telah Anda konfigurasi di antarmuka web Google Tag Manager.

Memasukkan Nilai ke dataLayer

dataLayer menyediakan lapisan persistensi yang dapat Anda gunakan untuk menyimpan key-value pair yang mungkin ingin Anda gunakan di bagian lain aplikasi, atau sebagai input ke 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).

Mengirim Peristiwa ke dataLayer

Dengan mengirim peristiwa ke dataLayer, Anda dapat memisahkan kode aplikasi dari tag yang mungkin ingin diaktifkan sebagai respons terhadap peristiwa tersebut.

Misalnya, daripada melakukan hard code pada panggilan pelacakan tampilan layar Google Analytics ke dalam aplikasi, 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.

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 yang sama dengan pengiriman peristiwa.

6. Melihat Pratinjau, Men-debug, dan Memublikasikan

Sebelum memublikasikan versi penampung, Anda dapat melihat pratinjaunya untuk memastikan penampung 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. Tambahkan 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. Buat link pratinjau di antarmuka web Google Tag Manager
    1. Login ke Google Tag Manager
    2. Pilih Versi penampung 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);

Publikasi

Setelah melihat pratinjau penampung dan memverifikasi bahwa penampung tersebut berfungsi sebagaimana mestinya, Anda dapat memublikasikan penampung. Nilai konfigurasi, tag, dan peristiwa penampung Anda akan aktif untuk pengguna saat penampung mereka dimuat ulang pada waktu berikutnya. 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 container secara manual, gunakan ContainerHolder.refresh():

ContainerHolderSingleton.getContainerHolder().refresh();

Ini adalah panggilan asinkron yang tidak akan langsung ditampilkan. Untuk mengurangi traffic jaringan, refresh() hanya boleh dipanggil sekali setiap 15 menit, jika tidak, operasi tidak akan dilakukan.