Android v3 (Lama) - Ringkasan

Panduan ini menjelaskan API yang termasuk dalam versi SDK yang lama. Pengguna baru seharusnya Mulai Menggunakan SDK Terbaru.

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 iOS mereka.

Panduan developer ini menjelaskan cara menerapkan Google Tag Manager di aplikasi seluler.

Pengantar

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

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

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

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

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

Google TagManager juga mengaktifkan penerapan tag pelacakan secara dinamis dan piksel dalam aplikasi. Developer dapat mendorong peristiwa penting ke dalam data dan memutuskan tag atau piksel pelacakan mana yang harus diaktifkan. TagManager saat ini mendukung tag berikut:

• Google Analisis Aplikasi Seluler
• Tag Panggilan Fungsi Khusus

Sebelum Anda Mulai

Sebelum menggunakan panduan memulai ini, Anda akan memerlukan hal berikut:

• Akun Google Tag Manager
• Tag Manager baru makro penampung dan pengumpulan nilai
• Aplikasi seluler untuk Android tempat menerapkan Google Tag Manager
• Layanan Google Analytics SDK, yang berisi library Tag Manager.

Jika Anda baru menggunakan Google Tag Manager, sebaiknya Pelajari lebih lanjut penampung, makro, dan aturan (Pusat Bantuan) sebelum melanjutkan panduan ini.

Memulai

Bagian ini akan memandu developer melalui alur kerja Tag Manager standar:

1. Menambahkan Google Tag Manager SDK ke project
2. Menetapkan Nilai Penampung Default
3. Membuka Container
4. Mendapatkan Nilai Konfigurasi dari Penampung
5. Mengirim Peristiwa ke DataLayer
6. Pratinjau & Memublikasikan Penampung

1. Menambahkan SDK Google Tag Manager ke Project Anda

Sebelum menggunakan SDK Google Tag Manager, Anda harus mengekstrak paket SDK dan menambahkan library ke jalur build project Anda dan menambahkan izin ke file AndroidManifest.xml Anda.

Pertama, tambahkan library Google Tag Manager ke folder /libs pada proyek Anda.

Selanjutnya, perbarui file AndroidManifest.xml Anda untuk menggunakan izin:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

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 digunakan hingga aplikasi dapat mengambil penampung baru melalui jaringan.

Untuk mendownload dan menambahkan biner container default ke aplikasi Anda, ikuti langkah-langkah berikut:

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 ke jalur berikut: <project-root>/assets/tagmanager/

Nama file default harus berupa ID penampung (misalnya, GTM-1234). Setelah Anda mengunduh file biner, pastikan untuk menghapus akhiran versi dari nama file untuk memastikan Anda mengikuti konvensi penamaan yang benar.

Meskipun sebaiknya gunakan file biner, jika penampung Anda tidak berisi aturan atau tag, Anda dapat memilih untuk menggunakan JSON file tersebut. File harus berada di /assets/tagmanager baru project Android Anda dan harus mengikuti konvensi penamaan ini: <Container_ID>.json. Misalnya, jika ID penampung Anda adalah GTM-1234, Anda harus menambahkan nilai container default ke /assets/tagmanager/GTM-1234.json.

3. Membuka Container

Sebelum mengambil nilai dari container, aplikasi Anda harus dibuka container-nya. Membuka container akan memuatnya dari disk (jika tersedia), atau akan memintanya dari jaringan (jika diperlukan).

Cara termudah untuk membuka penampung di Android adalah dengan menggunakan ContainerOpener.openContainer(..., Notifier notifier), seperti dalam contoh berikut:

import com.google.tagmanager.Container;
import com.google.tagmanager.ContainerOpener;
import com.google.tagmanager.ContainerOpener.OpenType;
import com.google.tagmanager.TagManager;

import android.app.Activity;
import android.os.Bundle;

public class RacingGame {

  // Add your public container ID.
  private static final String CONTAINER_ID = "GTM-YYYY";

  volatile private Container mContainer;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    TagManager mTagManager = TagManager.getInstance(this);

    // The container is returned to containerFuture when available.
    ContainerOpener.openContainer(
        mTagManager,                            // TagManager instance.
        CONTAINER_ID,                           // Tag Manager Container ID.
        OpenType.PREFER_NON_DEFAULT,            // Prefer not to get the default container, but stale is OK.
        null,                                   // Time to wait for saved container to load (ms). Default is 2000ms.
        new ContainerOpener.Notifier() {        // Called when container loads.
          @Override
          public void containerAvailable(Container container) {
            // Handle assignment in callback to avoid blocking main thread.
            mContainer = container;
          }
        }
    );
    // Rest of your onCreate code.
  }
}

Dalam contoh ini, ContainerOpener.openContainer(..., Notifier notifier) digunakan untuk meminta container tersimpan dari penyimpanan lokal. Dengan menangani penugasan mContainer dalam callback containerAvailable, kita memastikan bahwa thread utama tidak diblokir. Jika penampung tersimpan lebih dari 12 jam, juga akan menjadwalkan permintaan untuk mengambil penampung baru secara asinkron melalui jaringan.

Contoh implementasi ini mewakili cara paling sederhana untuk membuka dan mengambil nilai dari penampung menggunakan class praktis ContainerOpener. Untuk opsi penerapan lanjutan lainnya, lihat Konfigurasi Lanjutan.

4. Mendapatkan Nilai Konfigurasi dari Penampung

Setelah penampung terbuka, nilai konfigurasi dapat diambil menggunakan get<type>Value() metode:

// Retrieving a configuration value from a Tag Manager Container.

// Get the configuration value by key.
String title = mContainer.getStringValue("title_string");

Permintaan yang dibuat dengan kunci yang tidak ada akan menampilkan nilai default yang sesuai ke jenis yang diminta:

// Empty keys will return a default value depending on the type requested.

// Key does not exist. An empty string is returned.
string subtitle = container.getStringValue("Non-existent-key");
subtitle.equals(""); // Evaluates to true.

5. Mendorong Nilai ke DataLayer

DataLayer adalah peta yang memungkinkan informasi runtime tentang aplikasi Anda, seperti sentuhan peristiwa atau tampilan layar, agar tersedia untuk makro dan tag Tag Manager di container.

Misalnya, dengan mendorong informasi tentang tampilan layar ke dalam peta DataLayer, Anda dapat menyiapkan tag di antarmuka web Tag Manager untuk mengaktifkan piksel konversi dan melacak panggilan sebagai respons terhadap tampilan layar tersebut tanpa perlu kode ke dalam aplikasi Anda.

Peristiwa dikirim ke DataLayer menggunakan push() dan Metode bantuan DataLayer.mapOf():

//
// MainActivity.java
// Pushing an openScreen event with a screen name into the data layer.
//

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

import android.app.Activity;
import android.os.Bundle;

public MainActivity extends Activity {

  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

  }

  // This screen becomes visible when Activity.onStart() is called.
  public void onStart() {
    super.onStart();

    // The container should have already been opened, otherwise events pushed to
    // the DataLayer will not fire tags in that container.
    DataLayer dataLayer = TagManager.getInstance(this).getDataLayer();
    dataLayer.push(DataLayer.mapOf("event",
                                   "openScreen",      // The event type. This value should be used consistently for similar event types.
                                   "screenName",      // Writes a key "screenName" to the dataLayer map.
                                   "Home Screen")     // Writes a value "Home Screen" for the "screenName" key.
    );
  }
  // Rest of the Activity implementation
}

Di antarmuka web, Anda kini dapat membuat tag (seperti tag Google Analytics) diaktifkan untuk setiap tampilan layar dengan membuat aturan ini: sama dengan "openScreen". Untuk meneruskan nama layar ke salah satu tag ini, buat makro lapisan data yang merujuk ke "screenName" di lapisan data. Anda juga dapat membuat tag (seperti piksel konversi Google Ads) agar hanya diaktifkan untuk tampilan layar tertentu, dengan membuat aturan di mana sama dengan "openScreen" && sama dengan "ConfirmationScreen".

Catatan: Kunci dan nilai peristiwa Lapisan Data harus digunakan sekonsisten mungkin, sehingga dalam contoh ini, semua tampilan layar menggunakan "openScreen" sebagai nilai peristiwa, dan "screenName" sebagai kunci nama layar. Hal ini membuat pengaksesan DataLayer dan pembuatan tag tambahan di masa mendatang semudah mungkin.

6. Melihat pratinjau & Memublikasikan Penampung

Nilai makro akan selalu sesuai dengan versi yang dipublikasikan saat ini. Sebelum memublikasikan penampung versi terbaru, Anda dapat melihat pratinjau penampung draf Anda.

Untuk melihat pratinjau penampung, buat URL pratinjau di Google Antarmuka web Tag Manager dengan memilih versi penampung yang ingin Anda lihat pratinjaunya, lalu pilih Preview. Tunggu sebentar URL pratinjau ini karena Anda akan memerlukannya di langkah berikutnya.

Gambar 1: Mendapatkan URL pratinjau dari Antarmuka web Tag Manager.

Berikutnya, tambahkan Aktivitas berikut ke aktivitas File AndroidManifest.xml:

<!-- Google Tag Manager Preview Activity -->
<activity
  android:name="com.google.tagmanager.PreviewActivity"
  android:label="@string/app_name"
  android:noHistory="true" >  <!-- Optional, removes the PreviewActivity from activity stack. -->
  <intent-filter>
    <data android:scheme="tagmanager.c.application_package_name" />
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE"/>
  </intent-filter>
</activity>
  

Catatan: application_package_name harus sama dengan nama aplikasi yang digunakan untuk membuat URL pratinjau (Gambar 1).

Buka link di emulator atau perangkat fisik untuk lihat pratinjau penampung draf di aplikasi Anda.

Jika Anda sudah siap untuk menyediakan draf nilai konfigurasi bagi aplikasi, memublikasikan penampung.

Konfigurasi Lanjutan

Google Tag Manager untuk Seluler memiliki sejumlah konfigurasi lanjutan opsi yang memungkinkan Anda memilih nilai berdasarkan kondisi runtime menggunakan aturan, memuat ulang penampung secara manual, dan mendapatkan opsi tambahan untuk membuka container. Bagian berikut menguraikan beberapa {i>template <i}yang paling umum konfigurasi standar.

Opsi Lanjutan untuk Membuka Container

SDK Google Tag Manager menyediakan beberapa metode untuk membuka container yang dapat memberi Anda kontrol lebih besar atas proses pemuatan:

TagManager.openContainer()

TagManager.openContainer() adalah API level terendah dan paling fleksibel untuk membuka container. Metode ini segera ditampilkan dengan kontainer default dan memuat kontainer secara asinkron dari {i>disk <i}atau jaringan ada, atau jika penampung tersimpan tidak baru (> 12 jam lamanya).

mContainer = tagManager.openContainer(CONTAINER_ID, new Container.Callback() {

  // Called when a refresh is about to begin for the given refresh type.
  @Override
  public void containerRefreshBegin(Container container, RefreshType refreshType) {
    // Notify UI that the Container refresh is beginning.
   }

  // Called when a successful refresh occurred for the given refresh type.
  @Override
  public void containerRefreshSuccess(Container container, RefreshType refreshType]) {
    // Notify UI that Container is ready.
  }

  // Called when a refresh failed for the given refresh type.
  @Override
  public void containerRefreshFailure(Container container,
                                      RefreshType refreshType,
                                      RefreshFailure refreshFailure) {
    // Notify UI that the Container refresh has failed.
  }

Selama proses pemuatan, TagManager.openContainer() masalah beberapa callback siklus proses sehingga kode Anda bisa mengetahui kapan dimulainya permintaan pemuatan, apakah dan mengapa permintaan itu gagal atau berhasil, dan apakah kontainer pada akhirnya dimuat dari {i>disk<i} atau jaringan.

Kecuali aplikasi Anda dapat menggunakan nilai {i>default<i}, Anda perlu menggunakan callback ini untuk mengetahui kapan penampung telah dimuat. Perhatikan bahwa Anda tidak akan dapat memuat file yang disimpan atau kontainer jaringan jika ini adalah pertama kalinya aplikasi berjalan dan tidak ada koneksi jaringan.

TagManager.openContainer() meneruskan enum berikut sebagai argumen ke callback ini:

RefreshType

Nilai	Deskripsi
Container.Callback.SAVED	Permintaan pembaruan sedang memuat penampung yang disimpan secara lokal.
Container.Callback.NETWORK	Permintaan pembaruan sedang memuat penampung melalui jaringan.

RefreshFailure

Nilai	Deskripsi
Container.Callback.NO_SAVED_CONTAINER	Tidak ada penampung tersimpan yang tersedia.
Container.Callback.IO_ERROR	Error I/O mencegah pemuatan ulang penampung.
Container.Callback.NO_NETWORK	Tidak ada koneksi jaringan yang tersedia.
Container.Callback.NETWORK_ERROR	Terjadi error pada jaringan.
Container.Callback.SERVER_ERROR	Terjadi error pada server.
Container.Callback.UNKNOWN_ERROR	Telah terjadi kesalahan yang tidak dapat dikategorikan.

Metode untuk Membuka Container Non-Default dan Baru

ContainerOpener menggabungkan TagManager.openContainer() serta menyediakan dua metode praktis untuk membuka container: ContainerOpener.openContainer(..., Notifier notifier) dan ContainerOpener.openContainer(..., Long timeoutInMillis).

Setiap metode ini mengambil enumerasi yang meminta {i>non-default<i} atau penampung baru.

OpenType.PREFER_NON_DEFAULT direkomendasikan untuk sebagian besar aplikasi dan berupaya mengembalikan penampung non-default pertama yang tersedia dalam periode waktu tunggu, baik dari disk atau jaringan, meskipun kontainer itu lebih besar dari 12 jam lalu. Jika mengembalikan penampung tersimpan yang usang, hal itu juga akan membuat permintaan jaringan asinkron untuk jaringan yang baru. Saat menggunakan OpenType.PREFER_NON_DEFAULT, default akan dikembalikan jika tidak ada penampung lain yang tersedia, atau jika periode waktu tunggu habis terlampaui.

OpenType.PREFER_FRESH mencoba menampilkan penampung baru dari {i>disk<i} atau jaringan dalam periode waktu tunggu yang ditentukan. Metode ini menampilkan penampung tersimpan jika koneksi tidak tersedia dan/atau periode waktu tunggu terlampaui.

Tidak direkomendasikan menggunakan OpenType.PREFER_FRESH di tempat-tempat di mana waktu permintaan yang lebih lama dapat sangat memengaruhi pengalaman pengguna, seperti dengan flag UI atau string tampilan. Anda juga dapat menggunakan Container.refresh() kapan saja untuk memaksa permintaan penampung jaringan.

Kedua metode praktis ini tidak bersifat memblokir. ContainerOpener.openContainer(..., Long timeoutInMillis) menampilkan Objek ContainerOpener.ContainerFuture, yang metode get-nya menampilkan Container segera setelah dimuat (tetapi itu akan diblokir sampai saat itu). Metode ContainerOpener.openContainer(..., Notifier notifier) mengambil satu callback, dipanggil saat kontainer tersedia, yang dapat digunakan untuk mencegah pemblokiran thread utama. Kedua metode memiliki periode waktu tunggu default 2000 milidetik.

Mengevaluasi Makro pada Runtime menggunakan Aturan

Penampung dapat mengevaluasi nilai saat runtime menggunakan aturan. Aturan mungkin didasarkan berdasarkan kriteria seperti bahasa perangkat, platform, atau nilai makro lainnya. Sebagai contoh, aturan dapat digunakan untuk memilih string tampilan yang dilokalkan berdasarkan bahasa perangkat saat runtime. Hal ini dapat dikonfigurasi menggunakan aturan berikut:

Gambar 1:Menambahkan aturan untuk mengaktifkan makro pengumpulan nilai hanya untuk perangkat dikonfigurasi untuk menggunakan bahasa Spanyol.

Kemudian, Anda dapat membuat makro pengumpulan nilai untuk setiap bahasa, dan menambahkan aturan ini ke setiap makro, dengan menyisipkan kode bahasa yang sesuai. Ketika penampung ini dipublikasikan, aplikasi Anda akan dapat menampilkan tampilan yang dilokalkan {i>string<i}, tergantung pada bahasa perangkat pengguna pada saat {i>runtime<i}.

Perlu diketahui bahwa jika penampung default memerlukan aturan, Anda harus menggunakan file container biner sebagai default Anda container.

Pelajari lebih lanjut cara mengonfigurasi aturan (Pusat Bantuan).

File Container Default Biner

Penampung default yang memerlukan aturan harus menggunakan file container biner alih-alih JSON sebagai container default. Container biner menawarkan dukungan untuk menentukan nilai makro saat waktu proses dengan aturan Google Tag Manager, sedangkan JSON tidak dilakukan oleh file.

File penampung biner dapat didownload dari web Google Tag Manager antarmuka pengguna dan harus ditambahkan ke metode /assets/tagmanager/ folder dan ikuti pola ini: /assets/tagmanager/GTM-XXXX, dengan nama file mewakili ID penampung.

Jika file JSON Seperti file kontainer biner, SDK akan menggunakan kontainer biner sebagai container default.

Menggunakan Makro Panggilan Fungsi

Makro Panggilan Fungsi adalah makro yang ditetapkan ke nilai hasil fungsi tertentu dalam aplikasi Anda. Makro Panggilan Fungsi dapat digunakan untuk menggabungkan nilai runtime dengan aturan Google Tag Manager, seperti menentukan pada runtime harga mana yang akan ditampilkan kepada pengguna berdasarkan bahasa dan mata uang perangkat.

Untuk mengonfigurasi makro panggilan fungsi:

1. Tentukan makro panggilan fungsi di antarmuka web Google Tag Manager. Argumen dapat dikonfigurasi sebagai pasangan nilai kunci secara opsional.
2. Daftarkan FunctionCallMacroHandler di aplikasi Anda menggunakan Container.registerFunctionCallMacroHandler() dan nama fungsi yang Anda konfigurasi di antarmuka web Google Tag Manager, dengan menggantikan Metode getValue():

   /**
    * Registers a function call macro handler.
    *
    * @param functionName The function name field, as defined in the Google Tag
    *     Manager web interface.
    */
   mContainer.registerFunctionCallMacroHandler(functionName, new FunctionCallMacroHandler() {
   
     /**
      * This code will execute when any custom macro's rule(s) evaluate to true.
      * The code should check the functionName and process accordingly.
      *
      * @param functionName Corresponds to the function name field defined
      *     in the Google Tag Manager web interface.
      * @param parameters An optional map of parameters
      *     as defined in the Google Tag Manager web interface.
      */
     @Override
     public Object getValue(String functionName, Map<String, Object> parameters)) {
   
       if (functionName.equals("myConfiguredFunctionName")) {
         // Process and return the calculated value of this macro accordingly.
         return macro_value
       }
       return null;
     }
   });
   

Menggunakan Tag Panggilan Fungsi

Tag Panggilan Fungsi memungkinkan fungsi pradaftar untuk dijalankan kapan saja peristiwa didorong ke lapisan data dan aturan tag mengevaluasi ke true.

Untuk mengonfigurasi tag panggilan fungsi:

1. Tentukan tag panggilan fungsi di antarmuka web Google Tag Manager. Argumen dapat dikonfigurasi sebagai pasangan nilai kunci secara opsional.
2. Daftarkan pengendali tag panggilan fungsi di aplikasi Anda menggunakan Container.registerFunctionCallTagHandler():

   /**
    * Register a function call tag handler.
    *
    * @param functionName The function name, which corresponds to the function name field
    *     Google Tag Manager web interface.
    */
   mContainer.registerFunctionCallTagHandler(functionName, new FunctionCallTagHandler() {
   
     /**
      * This method will be called when any custom tag's rule(s) evaluates to true.
      * The code should check the functionName and process accordingly.
      *
      * @param functionName The functionName passed to the functionCallTagHandler.
      * @param parameters An optional map of parameters as defined in the Google
      *     Tag Manager web interface.
      */
     @Override
     public void execute(String functionName, Map<String, Object> parameters) {
       if (functionName.equals("myConfiguredFunctionName")) {
         // Process accordingly.
       }
     }
   });
   

Menetapkan Periode Pembaruan Khusus

SDK Google Tag Manager akan mencoba mengambil penampung baru jika usia penampung saat ini melebihi 12 jam. Untuk menyetel periode pembaruan penampung khusus, gunakan Timer , seperti dalam contoh berikut:

timer.scheduleTask(new TimerTask() {
  @Override
  public void run() {
    mContainer.refresh();
  }
}, delay, <new_period_in milliseconds>);

Proses debug dengan Pencatat

SDK Google Tag Manager mencetak error dan peringatan ke log secara default. Mengaktifkan logging panjang dapat membantu proses debug dan dapat dilakukan dengan menerapkan Logger Anda sendiri dengan TagManager.setLogger, seperti dalam contoh ini:

TagManager tagManager = TagManager.getInstance(this);
tagManager.setLogger(new Logger() {

  final String TAG = "myGtmLogger";

  // Log output with verbosity level of DEBUG.
  @Override
  public void d(String arg0) {
    Log.d(TAG, arg0);
  }

  // Log exceptions when provided.
  @Override
  public void d(String arg0, Throwable arg1) {
    Log.d(TAG, arg0);
    arg1.printStackTrace();
  }

  // Rest of the unimplemented Logger methods.

});

Atau, Anda dapat mengatur LogLevel yang ada dengan menggunakan TagManager.getLogger().setLogLevel(LogLevel) , seperti dalam contoh ini:

// Change the LogLevel to INFO to enable logging at INFO and higher levels.
TagManager tagManager = TagManager.getInstance(this);
tagManager.getLogger().setLogLevel(LogLevel.INFO);