‫Android גרסה 4 (מדור קודם) – תחילת העבודה

מבוא

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

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

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

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

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

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

לפני שתתחיל

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

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

תחילת העבודה

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

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

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

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

  1. הגדרת ה-SDK של Google Play Services.
  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 משתמש במאגר תגים שמוגדר כברירת מחדל בהפעלה הראשונה של האפליקציה. השימוש במאגר התגים שמוגדר כברירת מחדל יופסק ברגע שהאפליקציה תוכל לאחזר מאגר תגים חדש דרך הרשת.

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

  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. משיגים את ה-singleton של TagManager:
    TagManager tagManager = TagManager.getInstance(this);
  2. משתמשים ב-singleton‏ 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);

    יצירת ContainerHolder Singleton

    צריך להחזיק רק מופע אחד של ContainerHolder בכל הפעלה של האפליקציה. לכן בדוגמה שלמעלה נעשה שימוש במחלקת שירות (utility class) מסוג 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;
        }
    }

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. משיגים את ה-singleton של 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. משיגים את ה-singleton של DataLayer:
    DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
  2. שולחים את האירוע באמצעות DataLayer.pushEvent():
    dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));

    DataLayer.mapOf() היא שיטת שירות שמאפשרת ליצור בקלות מפה של צמדי מפתח/ערך שיעדכנו את dataLayer באותו זמן שבו האירוע נשלח.

6. תצוגה מקדימה, ניפוי באגים ופרסום

לפני שמפרסמים גרסה של מאגר התגים, כדאי להציג אותה בתצוגה מקדימה כדי לוודא שהיא פועלת כמו שצריך. ב-Google Tag Manager אפשר לראות תצוגה מקדימה של גרסאות של מאגר התגים. כדי לעשות את זה, יוצרים קישורים וקודי QR בממשק האינטרנט ומשתמשים בהם כדי לפתוח את האפליקציה. אתם יכולים גם להפעיל מצב רישום מפורט (verbose) ביומן כדי לנפות באגים בהתנהגות בלתי צפויה.

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

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

  1. הוספת גרסת טרום-ההשקה (Preview) הזו של 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. משתמשים בקישור או בקוד ה-QR שנוצר כדי להפעיל את האפליקציה.
  4. כדי לצאת ממצב תצוגה מקדימה, אפשר ללחוץ על קישור שנוצר באמצעות האפשרות Generate end preview link בממשק האינטרנט.

ניפוי באגים

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