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

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

เกริ่นนำ

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

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

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

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

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

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

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

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

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

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

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 Tag Manager ทุกประการ การเรียกไปยัง 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 ชั่วโมง ดูวิธีรีเฟรชคอนเทนเนอร์ด้วยตนเอง

   การสร้าง ContainerHolder 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 Tag Manager

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

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

การพุชค่าไปยัง dataLayer

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

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

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

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 Tag Manager
   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() เพียงครั้งเดียวทุกๆ 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();
}