Android v4 – תחילת העבודה

הערה: במדריך הזה מוסבר על ההטמעה הישנה של Google Tag. מנהל באפליקציות ל-Android. משתמשים חדשים צריכים להשתמש ב- Tag Manager ו-Firebase להטמעת Google Tag Manager באפליקציות שלהם ל-Android.

מבוא

Google Tag Manager מאפשר למפתחים לשנות ערכי תצורה באפליקציה שלהם לנייד באמצעות הממשק של Google Tag Manager ללא צורך לבנות מחדש ולשלוח מחדש את הקבצים הבינאריים של האפליקציות לזירות מסחר של אפליקציות.

האפשרות הזו שימושית לניהול ערכי תצורה או דגלים באפליקציה שלך שייתכן שדרושים לך שישתנו בעתיד, כולל:

• הגדרות שונות של ממשק המשתמש ומחרוזות תצוגה
• הגדלים, המיקומים או הסוגים של המודעות שמוצגות באפליקציה
• הגדרות שונות של משחקים

ניתן להעריך את ערכי ההגדרות גם בזמן הריצה באמצעות כללים, וכך לאפשר הגדרה דינמית מערכי הגדרות אישיות כמו:

• שימוש בגודל המסך כדי לקבוע את גודל הבאנר של המודעה
• שימוש בשפה ובמיקום להגדרת רכיבים בממשק המשתמש

Google Tag Manager מאפשר גם הטמעה דינמית של תגי מעקב ופיקסלים תרגום מכונה. המפתחים יכולים לדחוף אירועים חשובים לשכבת נתונים ולהחליט מאוחר יותר תגי מעקב או פיקסלים.

לפני שתתחיל

לפני שמתחילים את המדריך לתחילת העבודה, צריך לפעול לפי השלבים הבאים:

• התקנת Android SDK
• להורדת Google Play Services SDK
• יוצרים חשבון Google Tag Manager.
• הגדרת מאגר תגים של Google Tag Manager

לאחר ביצוע השלבים האלה, המשך המדריך הזה ינחה אתכם איך מגדירים את Google Tag Manager ומשתמשים בו באפליקציה ל-Android.

תחילת העבודה

אחרי שתבצעו את המדריך לתחילת העבודה, תוכלו להבין איך:

• הוספת Google Tag Manager לפרויקט
• מפעילים את Tag Manager באפליקציה
• קבלת ערכי הגדרות ממאגר תגים של Tag Manager
• דחיפת ערכים ואירועים לתוך dataLayer
• תצוגה מקדימה, ניפוי באגים ופרסום של מאגר התגים

המדריך הזה משתמש בקטעי קוד מתוך Cute Animals אפליקציה לדוגמה שכלולה Google Play Services SDK. המקור המלא של הפרויקט הזה זמין ב: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. הוספה של Google Tag Manager לפרויקט

כדי להוסיף את Google Tag Manager לפרויקט:

1. מגדירים את Google Play Services SDK
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. לוחצים על הלחצן Download (הורדה) כדי לאחזר את הקובץ הבינארי של מאגר התגים.
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 ממשק אינטרנט למנהל. הקריאה אל 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 בכל הרצה של תרגום מכונה. לכן בדוגמה שלמעלה נעשה שימוש במחלקה מסוג 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;
       }
   }

קטע קוד מהאפליקציה לדוגמה

קטע הקוד הבא מציגה את הדפוס המלא שמוטמע ב-method 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. לדוגמה, אפשר להשתמש בשיטה הבאה מאחזרת את הצבע האחרון שהחלטנו להשתמש בו עבור רכיב בממשק המשתמש ומחזירה אותו מספר שלם:

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

הקוד הזה מבצע שתי פעולות כדי לאחזר את שם הצבע ממאגר התגים:

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 מאפשר לך להציג גרסאות של מאגר התגים בתצוגה מקדימה באמצעות יצירת קישורים וקודי 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 Tag Manager
   1. נכנסים אל Google Tag Manager.
   2. בוחרים את מאגר התגים Version כדי להציג אותו בתצוגה מקדימה.
   3. לוחצים על הלחצן תצוגה מקדימה.
   4. מזינים את שם החבילה של האפליקציה ולוחצים על יצירת קישור לתצוגה מקדימה של התחלת.
3. יש להשתמש בקישור או בקוד ה-QR שנוצר כדי להפעיל את האפליקציה
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();
}