Android v4 - เริ่มต้นใช้งาน

หมายเหตุ: คู่มือนี้จะอธิบายการใช้งานแท็ก Google แบบเก่า เครื่องมือจัดการในแอปพลิเคชัน Android ผู้ใช้ใหม่ควรใช้ Tag Manager + Firebase เพื่อใช้งาน Google Tag Manager ในแอปพลิเคชัน Android

บทนำ

Google Tag Manager ช่วยให้นักพัฒนาซอฟต์แวร์เปลี่ยนการกำหนดค่าในแอปพลิเคชันบนอุปกรณ์เคลื่อนที่ได้ ใช้อินเทอร์เฟซ Google Tag Manager ได้โดยไม่ต้องสร้างและส่งไฟล์ไบนารีของแอปพลิเคชันอีกครั้ง ในตลาดแอป

ซึ่งจะมีประโยชน์ในการจัดการค่าของการกำหนดค่าหรือแฟล็กในแอปพลิเคชันที่คุณอาจต้องใช้ เปลี่ยนแปลงได้ในอนาคต ซึ่งรวมถึง

• การตั้งค่า UI ต่างๆ และสตริงที่แสดง
• ขนาด สถานที่ตั้ง หรือประเภทของโฆษณาที่แสดงในแอปพลิเคชันของคุณ
• การตั้งค่าเกมต่างๆ

หรืออาจประเมินค่าการกําหนดค่าขณะรันไทม์โดยใช้กฎ เพื่อเปิดใช้แบบไดนามิก การกำหนดค่า เช่น

• การใช้ขนาดหน้าจอเพื่อกำหนดขนาดของแบนเนอร์โฆษณา
• การใช้ภาษาและตำแหน่งเพื่อกำหนดค่าองค์ประกอบ UI

Google TagManager ยังเปิดใช้งานการติดตั้งใช้งานแท็กและพิกเซลการติดตามแบบไดนามิกใน แอปพลิเคชัน นักพัฒนาซอฟต์แวร์สามารถพุชเหตุการณ์สำคัญเข้าไปในชั้นข้อมูลและตัดสินใจในภายหลังว่าเหตุการณ์ใด แท็กหรือพิกเซลการติดตามควรเริ่มทำงาน

ก่อนที่คุณจะเริ่ม

ทำตามขั้นตอนต่อไปนี้ก่อนเริ่มคู่มือเริ่มต้นใช้งาน

• ติดตั้ง Android SDK
• ดาวน์โหลด SDK บริการ Google Play
• สร้างบัญชี Google Tag Manager
• กำหนดค่าคอนเทนเนอร์ Google Tag Manager

เมื่อคุณทำตามขั้นตอนเหล่านี้เสร็จแล้ว ส่วนที่เหลือของคู่มือนี้จะอธิบายวิธีการ กำหนดค่าและใช้ Google Tag Manager ภายในแอปพลิเคชัน Android

เริ่มต้นใช้งาน

หลังจากทำตามคู่มือเริ่มต้นใช้งานนี้ คุณจะเข้าใจวิธีการ

• เพิ่ม Google Tag Manager ลงในโปรเจ็กต์
• เริ่มต้น Tag Manager ในแอปพลิเคชัน
• รับการกําหนดค่าจากคอนเทนเนอร์ Tag Manager
• พุชค่าและเหตุการณ์ลงใน dataLayer
• แสดงตัวอย่าง แก้ไขข้อบกพร่อง และนำคอนเทนเนอร์ไปใช้จริง

คู่มือนี้ใช้ข้อมูลโค้ดจาก Cute Animals แอปพลิเคชันตัวอย่างที่รวมอยู่ใน SDK บริการ Google Play แหล่งที่มาที่สมบูรณ์ของโปรเจ็กต์นี้มีอยู่ใน: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals

1. การเพิ่ม Google Tag Manager ลงในโปรเจ็กต์

วิธีเพิ่ม Google Tag Manager ในโปรเจ็กต์

1. ตั้งค่า SDK บริการ Google Play
2. หากคุณใช้ IDE อื่นที่ไม่ใช่ Android Studio ให้เพิ่มสิทธิ์ต่อไปนี้ลงใน AndroidManifest.xml ไฟล์:

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

3. เมื่อต้องการเปิดใช้งาน InstallReferrerReceiver เพื่อเรียกใช้ตัวรับของ Google Analytics ในการตั้งค่าข้อมูลแคมเปญ ให้เพิ่มข้อมูลต่อไปนี้ลงใน 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. การเพิ่มไฟล์คอนเทนเนอร์เริ่มต้นลงในโครงการ

หมายเหตุ: หากยังไม่ได้ กำหนดค่าคอนเทนเนอร์ในอินเทอร์เฟซเว็บของ Google Tag Manager แล้ว ให้กลับมาที่ขั้นตอนนี้เมื่อทำเสร็จแล้ว

Google Tag Manager ใช้คอนเทนเนอร์เริ่มต้นในการเรียกใช้แอปพลิเคชันครั้งแรก ค่าเริ่มต้น คอนเทนเนอร์จะหยุดทำงานทันทีที่แอปสามารถดึงข้อมูลคอนเทนเนอร์ใหม่ผ่าน เครือข่าย

วิธีดาวน์โหลดและเพิ่มไบนารีของคอนเทนเนอร์เริ่มต้นลงในแอปพลิเคชัน

1. ลงชื่อเข้าใช้อินเทอร์เฟซเว็บของ Google Tag Manager
2. เลือกเวอร์ชันของคอนเทนเนอร์ที่คุณต้องการดาวน์โหลด
3. คลิกปุ่มดาวน์โหลดเพื่อดึงข้อมูลไบนารีของคอนเทนเนอร์
4. เพิ่มไฟล์ไบนารีของคอนเทนเนอร์ที่ดาวน์โหลดไว้ลงในโปรเจ็กต์เป็นทรัพยากรดิบ
   1. หากโฟลเดอร์ย่อย raw อยู่ภายใต้ <project-root>/res/ ไม่มีอยู่ โปรดสร้าง
   2. เปลี่ยนชื่อไฟล์ไบนารีของคอนเทนเนอร์หากจำเป็น ซึ่งประกอบด้วย ตัวอักษรพิมพ์เล็ก ตัวเลข และขีดล่าง
   3. คัดลอกไฟล์ไบนารีของคอนเทนเนอร์ไปยังโฟลเดอร์ <project-root>/res/raw

แม้ว่าแนะนำให้ใช้ไฟล์ไบนารี แต่หากคอนเทนเนอร์ไม่มีกฎหรือแท็ก คุณอาจเลือกใช้ไฟล์ JSON แบบง่ายแทนก็ได้

3. กำลังเริ่มต้น Google Tag Manager

วิธีเริ่มต้น Google Tag Manager ในแอปพลิเคชัน

1. ใช้ซิงเกิลตันของ TagManager ดังนี้

   TagManager tagManager = TagManager.getInstance(this);

2. ใช้ซิงเกิลตัน TagManager เพื่อส่งคำขอโหลดคอนเทนเนอร์ โดยระบุ รหัสคอนเทนเนอร์ Google Tag Manager รวมถึงคอนเทนเนอร์เริ่มต้น รหัสคอนเทนเนอร์ควรเป็นตัวพิมพ์ใหญ่และตรงกับรหัสคอนเทนเนอร์ในแท็ก Google ทุกประการ อินเทอร์เฟซเว็บของเครื่องมือจัดการ การโทรไปยัง loadContainerPreferNonDefault() ไม่ถูกบล็อก และแสดงผล PendingResult:

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

3. ใช้ ResultCallback เพื่อส่งคืน ContainerHolder หลังจากที่โหลดเสร็จแล้วหรือหมดเวลา

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

   หมายเหตุ: โดยค่าเริ่มต้น คอนเทนเนอร์จะมีสิทธิ์รีเฟรช บนเครือข่ายทุก 12 ชั่วโมง ดูวิธีรีเฟรชคอนเทนเนอร์ด้วยตนเอง

   การสร้าง Singleton สำหรับคอนเทนเนอร์

   คุณควรเก็บ ContainerHolder เพียง 1 อินสแตนซ์ต่อการเรียกใช้ แอปพลิเคชัน นั่นคือสาเหตุที่ตัวอย่างด้านบนใช้คลาสยูทิลิตี ContainerHolderSingleton เพื่อจัดการการเข้าถึงอินสแตนซ์ ContainerHolder นี่คือสิ่งที่ ชั้นเรียน ContainerHolderSingleton มีลักษณะดังนี้

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

ดูข้อมูลโค้ดจากแอปพลิเคชันตัวอย่าง

ข้อมูลโค้ดต่อไปนี้ แสดงรูปแบบแบบเต็มที่ใช้ในเมธอด onCreate() ของตัวอย่าง 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. การรับค่าของการกำหนดค่าจากคอนเทนเนอร์

เมื่อคอนเทนเนอร์โหลดแล้ว คุณสามารถดึงค่าของการกำหนดค่าโดยใช้ Container.get<type>() วิธี การกำหนดค่าจะกำหนดโดยใช้ ตัวแปรการรวบรวมค่าของ Google Tag Manager ตัวอย่างเช่น วิธีการต่อไปนี้ จะดึงสีล่าสุดที่เราตัดสินใจว่าจะใช้ในองค์ประกอบ UI ใดและแสดงเป็น จำนวนเต็ม:

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

โค้ดนี้ทำหน้าที่ 2 อย่างเพื่อดึงชื่อสีจากคอนเทนเนอร์

1. รับ Container จาก ContainerHolder โดยใช้ ContainerHolder.getContainer()
2. รับค่าสีโดยใช้ Container.getString(key) ซึ่งมี กำหนดคีย์และค่าในอินเทอร์เฟซเว็บ Google เครื่องจัดการแท็กแล้ว

5. การพุชเหตุการณ์และค่าไปยัง dataLayer

นอกจากนี้ Google Tag Manager ยังมี dataLayer ไว้อีกด้วย ซึ่งคุณสามารถพุชข้อมูลได้ เกี่ยวกับแอปพลิเคชันที่สามารถอ่านในส่วนอื่นๆ ของแอปพลิเคชันหรือใช้เพื่อเริ่มการทำงานของแท็ก ที่คุณได้กำหนดค่าในอินเทอร์เฟซเว็บของ Google Tag Manager

การพุชค่าไปยังชั้นข้อมูล

dataLayer จะช่วยเพิ่มความต่อเนื่องให้คุณได้ลองใช้ ในการจัดเก็บคู่คีย์-ค่าที่คุณอาจต้องการใช้ในส่วนอื่นๆ ของแอปพลิเคชัน หรือ เป็นอินพุตสำหรับแท็ก Google Tag Manager

หากต้องการพุชค่าไปยัง dataLayer ให้ใช้รูปแบบนี้

1. รับ DataLayer ซิงเกิล:

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

2. พุชเหตุการณ์โดยใช้ DataLayer.push()

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

หากต้องการค่าจาก dataLayer ให้ใช้ DataLayer.get(key)

การพุชเหตุการณ์ไปยัง dataLayer

การพุชเหตุการณ์ไปยัง dataLayer จะช่วยให้คุณสามารถแยกโค้ดแอปพลิเคชันจาก แท็กที่คุณอาจต้องการให้เริ่มทํางานเพื่อตอบสนองต่อเหตุการณ์เหล่านั้น

ตัวอย่างเช่น แทนที่จะฮาร์ดโค้ดการติดตามจำนวนการดูหน้าจอของ Google Analytics ลงในแอปพลิเคชันของคุณ คุณสามารถพุชเหตุการณ์บนหน้าจอไปยัง dataLayer และกำหนดแท็กติดตามผ่าน เว็บอินเทอร์เฟซของ Google Tag Manager ซึ่งให้คุณแก้ไขแท็กหรือเพิ่มแท็ก แท็กเพิ่มเติมที่ตอบสนองต่อเหตุการณ์บนหน้าจอโดยไม่ต้องอัปเดตโค้ดของแอปพลิเคชัน

หากต้องการพุชเหตุการณ์ไปยัง dataLayer ให้ใช้รูปแบบนี้

1. รับ DataLayer ซิงเกิล:

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

2. พุชเหตุการณ์โดยใช้ DataLayer.pushEvent()

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

   DataLayer.mapOf() เป็นวิธียูทิลิตีที่คุณสามารถใช้สร้างแผนที่ของ คู่คีย์-ค่าที่จะอัปเดต dataLayer พร้อมกับการพุชเหตุการณ์

ดูข้อมูลโค้ดจากแอปพลิเคชันตัวอย่าง

คลาสยูทิลิตีต่อไปนี้แสดงวิธีพุชเหตุการณ์ เช่น ข้อมูลเกี่ยวกับหน้าจอ การเปิดและปิดในแอปของคุณบน 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. การดูตัวอย่าง การแก้ไขข้อบกพร่อง และการเผยแพร่

ก่อนที่จะเผยแพร่เวอร์ชันของคอนเทนเนอร์ คุณควรดูตัวอย่างเพื่อให้คอนเทนเนอร์ทำงานได้ ตามที่ต้องการ Google Tag Manager ช่วยให้คุณดูตัวอย่างคอนเทนเนอร์เวอร์ชันต่างๆ ได้ โดยการสร้างลิงก์และโค้ด QR ในเว็บอินเทอร์เฟซและใช้ลิงก์เพื่อเปิดแอปพลิเคชันของคุณ คุณยังสามารถเปิดใช้โหมดการบันทึกที่มีข้อมูลขนาดใหญ่เพื่อแก้ไขข้อบกพร่องของการทำงานที่ไม่คาดคิดได้อีกด้วย

กำลังแสดงตัวอย่าง

หากต้องการดูตัวอย่างเวอร์ชันคอนเทนเนอร์ ให้ทำตามขั้นตอนต่อไปนี้

1. กำลังเพิ่มหน้าตัวอย่าง Activity นี้ลงในไฟล์ AndroidManifest ของคุณ:

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

   ตรวจสอบให้แน่ใจว่าได้แก้ไขบรรทัดนี้ให้รวมชื่อแพ็กเกจของแอปพลิเคชันของคุณ:

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

2. สร้างลิงก์แสดงตัวอย่างในอินเทอร์เฟซเว็บของ Google เครื่องจัดการแท็ก
   1. ลงชื่อเข้าใช้ Google Tag Manager
   2. เลือกเวอร์ชันคอนเทนเนอร์เพื่อดูตัวอย่าง
   3. คลิกปุ่มตัวอย่าง
   4. ป้อนชื่อแพ็กเกจของแอปพลิเคชันแล้วคลิกสร้างลิงก์เริ่มการแสดงตัวอย่าง
3. ใช้ลิงก์ที่สร้างขึ้นหรือคิวอาร์โค้ดเพื่อเปิดใช้แอปพลิเคชัน
4. คุณออกจากโหมดแสดงตัวอย่างได้โดยไปที่ลิงก์สร้างลิงก์สิ้นสุดการแสดงตัวอย่าง ในอินเทอร์เฟซเว็บ

การแก้ไขข้อบกพร่อง

หากคุณต้องการแก้ปัญหาการใช้งานคอนเทนเนอร์ ให้เปิดใช้การบันทึกแบบละเอียดโดยการเรียกใช้ 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);

การเผยแพร่

หลังจากที่คุณได้ดูตัวอย่างคอนเทนเนอร์ และยืนยันว่าคอนเทนเนอร์ทำงานได้ตามที่ต้องการแล้ว คุณสามารถทำสิ่งต่อไปนี้ นำคอนเทนเนอร์ไปใช้จริง บัญชี ค่าของการกำหนดค่าคอนเทนเนอร์ แท็ก และเหตุการณ์จึงจะพร้อมใช้งานสำหรับผู้ใช้ในครั้งถัดไป มีการรีเฟรชคอนเทนเนอร์ ดูข้อมูลเพิ่มเติมเกี่ยวกับการรีเฟรชคอนเทนเนอร์

การกำหนดค่าขั้นสูง

ส่วนต่อไปนี้จะอธิบายตัวเลือกการกำหนดค่าขั้นสูงที่คุณต้องการใช้ในการกำหนดค่า การใช้ Google Tag Manager

การรีเฟรชคอนเทนเนอร์

โดยค่าเริ่มต้น คอนเทนเนอร์ของคุณจะมีสิทธิ์รีเฟรชทุก 12 ชั่วโมง วิธีรีเฟรชด้วยตนเอง คอนเทนเนอร์ ให้ใช้ ContainerHolder.refresh()

ContainerHolderSingleton.getContainerHolder().refresh();

การโทรนี้เป็นแบบไม่พร้อมกันซึ่งจะไม่ส่งคืนทันที เพื่อลดการจราจรของข้อมูลในเครือข่าย refresh() อาจ ถูกเรียกเพียง 1 ครั้งในทุกๆ 15 นาที ไม่เช่นนั้นจะไม่มีการใช้งาน

หมายเหตุ: ข้อมูลโค้ดนี้ใช้ คลาสยูทิลิตี ContainerHolderSingleton ที่อธิบายไว้ในตัวอย่างการเริ่มต้น ที่ด้านบน

ดูข้อมูลโค้ดจากแอปพลิเคชันตัวอย่าง

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