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

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

מבוא

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

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

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

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

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

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

לפני שתתחיל

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

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

כדי להוריד ולהוסיף לאפליקציה שלכם קובץ בינארי של מאגר תגים המוגדר כברירת מחדל:

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 שעות. איך מרעננים מאגר תגים באופן ידני

   יצירת Container Holder 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;
       }
   }
   
   

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

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

מוצגת תצוגה מקדימה

כדי לראות תצוגה מקדימה של גרסה של הכלי המכיל, בצעו את השלבים הבאים:

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. לוחצים על הלחצן Preview (תצוגה מקדימה).
   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();
}