Android v3 (Lama) - Ringkasan

Panduan ini menjelaskan API yang termasuk dalam SDK versi lama. Pengguna baru harus Memulai SDK Terbaru.

Catatan: Panduan ini menjelaskan implementasi lama Google Tag Manager di aplikasi Android. Pengguna baru harus menggunakan Tag Manager + Firebase untuk mengimplementasikan Google Tag Manager di aplikasi iOS.

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

Pengantar

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

Hal ini berguna untuk mengelola nilai konfigurasi atau flag 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
• 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 TagManager juga memungkinkan implementasi dinamis tag pelacakan dan piksel di aplikasi. Developer dapat mendorong peristiwa penting ke lapisan data dan menentukan tag atau piksel pelacakan mana yang harus diaktifkan. TagManager mendukung tag berikut:

• Google Mobile App Analytics
• Tag Panggilan Fungsi Kustom

Sebelum Anda Mulai

Sebelum menggunakan panduan memulai ini, Anda memerlukan hal berikut:

• Akun Google Tag Manager
• Penampung Tag Manager baru dan makro pengumpulan nilai
• Aplikasi seluler untuk Android yang akan digunakan untuk mengimplementasikan Google Tag Manager
• Google Analytics Services 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 yang umum:

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

1. Menambahkan Google Tag Manager SDK ke Project Anda

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

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

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

<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 di antarmuka web Google Tag Manager, kembali ke langkah ini setelah Anda melakukannya.

Google Tag Manager menggunakan penampung default saat aplikasi Anda dijalankan untuk pertama kalinya. Penampung default akan digunakan hingga aplikasi dapat mengambil penampung baru melalui jaringan.

Untuk mendownload dan menambahkan biner penampung 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 mendownload file biner, pastikan untuk menghapus akhiran versi dari nama file guna memastikan Anda mengikuti konvensi penamaan yang benar.

Meskipun penggunaan file biner direkomendasikan, jika penampung Anda tidak berisi aturan atau tag, Anda dapat memilih untuk menggunakan file JSON. File harus berada di folder /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 penampung default ke /assets/tagmanager/GTM-1234.json.

3. Membuka Penampung

Sebelum mengambil nilai dari penampung, aplikasi Anda harus membuka penampung. Membuka penampung 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 penampung yang disimpan dari penyimpanan lokal. Dengan menangani penetapan mContainer dalam callback containerAvailable, kita memastikan bahwa thread utama tidak diblokir. Jika penampung yang disimpan berusia lebih dari 12 jam, panggilan juga akan menjadwalkan permintaan untuk mengambil penampung baru secara asinkron melalui jaringan.

Implementasi contoh ini menunjukkan cara paling sederhana untuk membuka dan mengambil nilai dari penampung menggunakan class praktis ContainerOpener. Untuk opsi implementasi yang lebih canggih, lihat Konfigurasi Lanjutan.

4. Mendapatkan Nilai Konfigurasi dari Penampung

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

// 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 dengan 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 peristiwa sentuh atau tampilan layar, tersedia untuk makro dan tag Tag Manager dalam penampung.

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

Peristiwa didorong ke DataLayer menggunakan push() dan metode helper 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) untuk diaktifkan bagi setiap tampilan layar dengan membuat aturan ini: sama dengan "openScreen". Untuk meneruskan nama layar ke salah satu tag ini, buat makro lapisan data yang mereferensikan kunci "screenName" di lapisan data. Anda juga dapat membuat tag (seperti piksel konversi Google Ads) untuk diaktifkan hanya untuk tampilan layar tertentu, dengan membuat aturan yang menyatakan sama dengan "openScreen" && sama dengan "ConfirmationScreen".

Catatan: Nilai dan kunci peristiwa DataLayer harus digunakan se-konsisten mungkin, sehingga dalam contoh ini, semua tampilan layar menggunakan "openScreen" sebagai nilai peristiwa, dan "screenName" sebagai kunci nama layar. Hal ini akan memudahkan akses ke DataLayer dan pembuatan tag tambahan di masa mendatang.

6. Melihat Pratinjau &Memublikasikan Penampung

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

Untuk melihat pratinjau penampung, buat URL pratinjau di antarmuka web Google Tag Manager dengan memilih versi penampung yang ingin Anda lihat pratinjaunya, lalu memilih Preview. Simpan URL pratinjau ini karena Anda akan membutuhkannya di langkah-langkah berikutnya.

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

Selanjutnya, tambahkan Aktivitas berikut ke file AndroidManifest.xml aplikasi Anda:

<!-- 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 cocok dengan nama aplikasi yang digunakan untuk membuat URL pratinjau (Gambar 1).

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

Jika Anda siap membuat nilai konfigurasi draf tersedia untuk aplikasi Anda, publikasikan penampung.

Konfigurasi Lanjutan

Google Tag Manager untuk Seluler memiliki sejumlah opsi konfigurasi lanjutan yang memungkinkan Anda memilih nilai berdasarkan kondisi runtime menggunakan aturan, me-refresh penampung secara manual, dan mendapatkan opsi tambahan untuk membuka penampung. Bagian berikut menguraikan beberapa konfigurasi lanjutan yang paling umum.

Opsi Lanjutan untuk Membuka Penampung

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

TagManager.openContainer()

TagManager.openContainer() adalah API tingkat terendah dan paling fleksibel untuk membuka penampung. API ini akan langsung menampilkan penampung default dan juga memuat penampung secara asinkron dari disk atau jaringan jika tidak ada penampung yang disimpan, atau jika penampung yang disimpan tidak baru (> 12 jam).

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() mengeluarkan beberapa callback siklus proses sehingga kode Anda dapat mengetahui kapan permintaan pemuatan dimulai, apakah dan mengapa permintaan tersebut gagal atau berhasil, serta apakah penampung pada akhirnya dimuat dari disk atau jaringan.

Kecuali jika aplikasi Anda dapat menggunakan nilai default, Anda harus menggunakan callback ini untuk mengetahui kapan penampung yang disimpan atau penampung jaringan dimuat. Perhatikan bahwa Anda tidak akan dapat memuat penampung yang disimpan atau penampung jaringan jika ini adalah pertama kalinya aplikasi dijalankan dan tidak ada koneksi jaringan.

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

RefreshType

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

RefreshFailure

Nilai	Deskripsi
Container.Callback.NO_SAVED_CONTAINER	Tidak ada penampung yang disimpan.
Container.Callback.IO_ERROR	Error I/O mencegah refresh penampung.
Container.Callback.NO_NETWORK	Tidak ada koneksi jaringan.
Container.Callback.NETWORK_ERROR	Terjadi error jaringan.
Container.Callback.SERVER_ERROR	Terjadi error di server.
Container.Callback.UNKNOWN_ERROR	Terjadi error yang tidak dapat dikategorikan.

Metode untuk Membuka Penampung Non-Default dan Baru

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

Setiap metode ini menggunakan enumerasi yang meminta penampung non-default atau penampung baru.

OpenType.PREFER_NON_DEFAULT direkomendasikan untuk sebagian besar aplikasi dan mencoba menampilkan penampung non-default pertama yang tersedia dalam periode waktu tunggu tertentu, baik dari disk maupun jaringan, meskipun penampung tersebut berusia lebih dari 12 jam. Jika menampilkan penampung yang disimpan dan sudah tidak berlaku, penampung tersebut juga akan membuat permintaan jaringan asinkron untuk penampung baru. Saat menggunakan OpenType.PREFER_NON_DEFAULT, penampung default akan ditampilkan jika tidak ada penampung lain yang tersedia, atau jika periode waktu tunggu terlampaui.

OpenType.PREFER_FRESH mencoba menampilkan penampung baru dari disk atau jaringan dalam periode waktu tunggu yang diberikan. Penampung ini akan menampilkan penampung yang disimpan jika koneksi jaringan tidak tersedia dan/atau periode waktu tunggu terlampaui.

Sebaiknya jangan gunakan OpenType.PREFER_FRESH di tempat yang waktu permintaan lebih lama dapat memengaruhi pengalaman pengguna secara signifikan, 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 memblokir. ContainerOpener.openContainer(..., Long timeoutInMillis) menampilkan objek ContainerOpener.ContainerFuture, yang metode get menampilkan Container segera setelah dimuat (tetapi akan diblokir hingga saat itu). Metode ContainerOpener.openContainer(..., Notifier notifier) menggunakan satu callback, yang dipanggil saat penampung tersedia, yang dapat digunakan untuk mencegah pemblokiran thread utama. Kedua metode ini memiliki periode waktu tunggu default 2000 milidetik.

Mengevaluasi Makro saat Runtime menggunakan Aturan

Penampung dapat mengevaluasi nilai saat runtime menggunakan aturan. Aturan dapat didasarkan pada kriteria seperti bahasa perangkat, platform, atau nilai makro lainnya. Misalnya, 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 yang 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. Saat penampung ini dipublikasikan, aplikasi Anda akan dapat menampilkan string tampilan yang dilokalkan, bergantung pada bahasa perangkat pengguna saat runtime.

Perhatikan bahwa jika penampung default Anda memerlukan aturan, Anda harus menggunakan file penampung biner sebagai penampung default.

Pelajari lebih lanjut cara mengonfigurasi aturan (Pusat Bantuan).

File Penampung Default Biner

Penampung default yang memerlukan aturan harus menggunakan file penampung biner bukan file JSON sebagai penampung default. Penampung biner menawarkan dukungan untuk menentukan nilai makro saat runtime dengan aturan Google Tag Manager, sedangkan file JSON tidak.

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

Jika file JSON dan file penampung biner ada, SDK akan menggunakan file penampung biner sebagai penampung default.

Menggunakan Makro Panggilan Fungsi

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

Untuk mengonfigurasi makro panggilan fungsi:

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

   /**
    * 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 yang telah didaftarkan sebelumnya dieksekusi setiap kali peristiwa didorong ke lapisan data dan aturan tag dievaluasi ke true.

Untuk mengonfigurasi tag panggilan fungsi:

1. Tentukan tag panggilan fungsi di antarmuka web Google Tag Manager. Argumen dapat dikonfigurasi secara opsional sebagai pasangan kunci-nilai.
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 Refresh Kustom

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

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

Melakukan Debug dengan Logger

Google Tag Manager SDK mencetak error dan peringatan ke log secara default. Mengaktifkan logging yang lebih panjang dapat membantu proses debug dan dapat dilakukan dengan mengimplementasikan 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 menetapkan LogLevel Logger yang ada 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);