במדריך הזה למפתחים מוסבר איך להטמיע את Google Tag Manager באפליקציה לנייד.
מבוא
Google Tag Manager מאפשר למפתחים לשנות ערכי הגדרה באפליקציות לנייד באמצעות הממשק של Google Tag Manager, בלי לבנות מחדש את הקבצים הבינאריים של האפליקציה ולשלוח אותם מחדש לחנויות האפליקציות.
האפשרות הזו שימושית לניהול של ערכי הגדרה או דגלים באפליקציה שאולי תצטרכו לשנות בעתיד, כולל:
- הגדרות שונות של ממשק המשתמש ומחרוזות תצוגה
- גדלים, מיקומים או סוגים של מודעות שמוצגות באפליקציה
- הגדרות של משחקים
יכול להיות שהמערכת תעריך את ערכי ההגדרה בזמן הריצה באמצעות כללים, כדי לאפשר הגדרות דינמיות כמו:
- שימוש בגודל המסך כדי לקבוע את הגודל של מודעת באנר
- שימוש בשפה ובמיקום כדי להגדיר רכיבי ממשק משתמש
Google Tag Manager מאפשר גם הטמעה דינמית של תגי מעקב ופיקסלים באפליקציות. מפתחים יכולים להעביר אירועים חשובים לשכבת נתונים ולהחליט בהמשך אילו תגי מעקב או פיקסלים יופעלו. TagManager תומך בתגים הבאים:
- Google Mobile App Analytics
- תג Custom Function Call (בקשה להפעלת פונקציה בהתאמה אישית)
לפני שתתחיל
לפני שמשתמשים במדריך הזה למתחילים, צריך:
- חשבון Google Tag Manager
- מאגר תגים חדש של Tag Manager ומאקרו לאיסוף ערכים
- אפליקציה ל-Android שבה רוצים להטמיע את Google Tag Manager
- ערכת פיתוח תוכנה ל-Google Analytics Services, שכוללת את הספרייה Tag Manager.
אם אתם חדשים ב-Google Tag Manager, מומלץ לקרוא מידע נוסף על מאגרי תגים, פקודות מאקרו וכללים (מרכז העזרה) לפני שתמשיכו במדריך הזה.
תחילת העבודה
בקטע הזה נסביר למפתחים על תהליך עבודה אופייני ב-Tag Manager:
- הוספת Google Tag Manager SDK לפרויקט
- הגדרת ערכי ברירת מחדל למאגר התגים
- פתיחת המאגר
- קבלת ערכי הגדרה מהמאגר
- העברת אירועים אל DataLayer
- תצוגה מקדימה ופרסום של מאגר התגים
1. הוספת Google Tag Manager SDK לפרויקט
לפני שמשתמשים ב-Google Tag Manager SDK, צריך לחלץ את חבילת ה-SDK, להוסיף את הספרייה לנתיב הבנייה של הפרויקט ולהוסיף הרשאות לקובץ AndroidManifest.xml.
קודם כול, מוסיפים את ספריית Google Tag Manager לתיקייה /libs של הפרויקט.
לאחר מכן, מעדכנים את הקובץ AndroidManifest.xml כדי להשתמש בהרשאות הבאות:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" />
2. הוספת קובץ מאגר תגים שמוגדר כברירת מחדל לפרויקט
Google Tag Manager משתמש במאגר תגים שמוגדר כברירת מחדל בהפעלה הראשונה של האפליקציה. מאגר התגים שמוגדר כברירת מחדל ישמש עד שהאפליקציה תוכל לאחזר מאגר תגים חדש דרך הרשת.
כדי להוריד ולהוסיף קובץ בינארי של מאגר תגים שמוגדר כברירת מחדל לאפליקציה:
- נכנסים לממשק האינטרנט של Google Tag Manager.
- בוחרים את הגרסה של מאגר התגים שרוצים להוריד.
- לוחצים על הלחצן הורדה כדי לאחזר את הקובץ הבינארי של מאגר התגים.
- מוסיפים את הקובץ הבינארי לנתיב הבא:
<project-root>/assets/tagmanager/
שם הקובץ שמוגדר כברירת מחדל צריך להיות מזהה מאגר התגים (לדוגמה, GTM-1234). אחרי שמורידים את הקובץ הבינארי, צריך להסיר את סיומת הגרסה משם הקובץ כדי לוודא שפועלים בהתאם למוסכמת השמות הנכונה.
מומלץ להשתמש בקובץ הבינארי, אבל אם מאגר התגים לא מכיל כללים או תגים, אפשר להשתמש בקובץ JSON במקום זאת. הקובץ צריך להיות בתיקייה חדשה /assets/tagmanager
בפרויקט Android, והשם שלו צריך להיות לפי המוסכמה הבאה:
<Container_ID>.json. לדוגמה, אם מזהה מאגר התגים הוא GTM-1234, צריך להוסיף את ערכי מאגר התגים שמוגדרים כברירת מחדל אל /assets/tagmanager/GTM-1234.json.
3. פתיחת מאגר תגים
לפני שליפת ערכים ממכולה, האפליקציה צריכה לפתוח את המכולה. כשפותחים מאגר, הוא נטען מהדיסק (אם הוא זמין) או שהוא נשלח מהרשת (אם צריך).
הדרך הקלה ביותר לפתוח קונטיינר ב-Android היא באמצעות ContainerOpener.openContainer(..., Notifier notifier), כמו בדוגמה הבאה:
import com.google.tagmanager.Container; import com.google.tagmanager.ContainerOpener; import com.google.tagmanager.ContainerOpener.OpenType; import com.google.tagmanager.TagManager; import android.app.Activity; import android.os.Bundle; public class RacingGame { // Add your public container ID. private static final String CONTAINER_ID = "GTM-YYYY"; volatile private Container mContainer; @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); TagManager mTagManager = TagManager.getInstance(this); // The container is returned to containerFuture when available. ContainerOpener.openContainer( mTagManager, // TagManager instance. CONTAINER_ID, // Tag Manager Container ID. OpenType.PREFER_NON_DEFAULT, // Prefer not to get the default container, but stale is OK. null, // Time to wait for saved container to load (ms). Default is 2000ms. new ContainerOpener.Notifier() { // Called when container loads. @Override public void containerAvailable(Container container) { // Handle assignment in callback to avoid blocking main thread. mContainer = container; } } ); // Rest of your onCreate code. } }
בדוגמה הזו, ContainerOpener.openContainer(..., Notifier notifier) משמש לבקשת מאגר שמור מהאחסון המקומי. הקצאת הערך mContainer ב-callback containerAvailable מבטיחה שהשרשור הראשי לא ייחסם. אם מאגר התגים השמור ישן יותר מ-12 שעות, הקריאה גם תתזמן בקשה לאחזור אסינכרוני של מאגר תגים חדש ברשת.
הדוגמה הזו להטמעה מייצגת את הדרך הפשוטה ביותר לפתוח קונטיינר ולאחזר ממנו ערכים באמצעות המחלקה הנוחה ContainerOpener.
אפשרויות הטמעה מתקדמות נוספות מפורטות במאמר הגדרה מתקדמת.
4. קבלת ערכי הגדרה מהמאגר
אחרי פתיחת מאגר התגים, אפשר לאחזר את ערכי ההגדרה באמצעות השיטות get<type>Value():
// Retrieving a configuration value from a Tag Manager Container. // Get the configuration value by key. String title = mContainer.getStringValue("title_string");
בקשות שמוגשות עם מפתח שלא קיים יחזירו ערך ברירת מחדל שמתאים לסוג המבוקש:
// Empty keys will return a default value depending on the type requested. // Key does not exist. An empty string is returned. string subtitle = container.getStringValue("Non-existent-key"); subtitle.equals(""); // Evaluates to true.
5. העברת ערכים ל-dataLayer
DataLayer היא מפה שמאפשרת למידע בזמן ריצה על האפליקציה, כמו אירועי מגע או צפיות במסך, להיות זמין לפקודות מאקרו ולתגים של Tag Manager במאגר תגים.
לדוגמה, אם מעבירים מידע על צפיות במסך למיפוי של DataLayer, אפשר להגדיר תגים בממשק האינטרנט של Tag Manager כדי להפעיל פיקסלים של המרות וקריאות מעקב בתגובה לצפיות במסך, בלי צורך להוסיף אותם לקוד האפליקציה.
האירועים מועברים אל DataLayer באמצעות push() ושיטת העזר DataLayer.mapOf():
// // MainActivity.java // Pushing an openScreen event with a screen name into the data layer. // import com.google.tagmanager.TagManager; import com.google.tagmanager.DataLayer; import android.app.Activity; import android.os.Bundle; public MainActivity extends Activity { public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); } // This screen becomes visible when Activity.onStart() is called. public void onStart() { super.onStart(); // The container should have already been opened, otherwise events pushed to // the DataLayer will not fire tags in that container. DataLayer dataLayer = TagManager.getInstance(this).getDataLayer(); dataLayer.push(DataLayer.mapOf("event", "openScreen", // The event type. This value should be used consistently for similar event types. "screenName", // Writes a key "screenName" to the dataLayer map. "Home Screen") // Writes a value "Home Screen" for the "screenName" key. ); } // Rest of the Activity implementation }
בממשק האינטרנט, אפשר ליצור עכשיו תגים (כמו תגי Google Analytics) להפעלה בכל צפייה במסך על ידי יצירת הכלל הבא: equals "openScreen". כדי להעביר את שם המסך לאחד מהתגים האלה, צריך ליצור מאקרו של שכבת נתונים שמפנה למפתח screenName בשכבת הנתונים. אפשר גם ליצור תג (למשל פיקסל המרה של Google Ads) שיופעל רק בתצוגות מסך ספציפיות, על ידי יצירת כלל שבו שווה ל-"openScreen" וגם שווה ל-"ConfirmationScreen".
6. תצוגה מקדימה ופרסום של מאגר תגים
ערכי המאקרו תמיד יתאימו לגרסה הנוכחית שפורסמה. לפני שמפרסמים את הגרסה האחרונה של מאגר תגים, אפשר לראות תצוגה מקדימה של טיוטת מאגר התגים.
כדי לראות תצוגה מקדימה של מאגר, יוצרים כתובת URL לתצוגה מקדימה בממשק האינטרנט של Google Tag Manager. לשם כך, בוחרים את גרסת המאגר שרוצים לראות בתצוגה מקדימה ולוחצים על Preview. שומרים את כתובת ה-URL של התצוגה המקדימה כי תצטרכו אותה בשלבים הבאים.
לאחר מכן, מוסיפים את הפעילות הבאה לקובץ AndroidManifest.xml של האפליקציה:
<!-- Google Tag Manager Preview Activity --> <activity android:name="com.google.tagmanager.PreviewActivity" android:label="@string/app_name" android:noHistory="true" > <!-- Optional, removes the PreviewActivity from activity stack. --> <intent-filter> <data android:scheme="tagmanager.c.application_package_name" /> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE"/> </intent-filter> </activity>
פותחים את הקישור באמולטור או במכשיר פיזי כדי לראות תצוגה מקדימה של מאגר הטיוטות באפליקציה.
כשמוכנים להפוך את ערכי ההגדרות של הטיוטה לזמינים באפליקציה, מפרסמים את מאגר התגים.
הגדרה מתקדמת
ב-Google Tag Manager for Mobile יש מספר אפשרויות מתקדמות להגדרה שמאפשרות לכם לבחור ערכים על סמך תנאי זמן ריצה באמצעות כללים, לרענן ידנית את מאגר התגים ולקבל אפשרויות נוספות לפתיחת מאגרי תגים. בקטעים הבאים מפורטות כמה מההגדרות המתקדמות הנפוצות ביותר.
אפשרויות מתקדמות לפתיחת מאגרי תגים
ערכת ה-SDK של Google Tag Manager מספקת כמה שיטות לפתיחת מאגרי תגים, שיכולות לתת לכם יותר שליטה בתהליך הטעינה:
TagManager.openContainer()
TagManager.openContainer() היא רמת ה-API הנמוכה ביותר והגמישה ביותר לפתיחת מאגר תגים. הפונקציה מחזירה מיד מאגר ברירת מחדל, וגם טוענת באופן אסינכרוני מאגר מהדיסק או מהרשת אם לא קיים מאגר שמור, או אם המאגר השמור לא עדכני (גילו יותר מ-12 שעות).
mContainer = tagManager.openContainer(CONTAINER_ID, new Container.Callback() { // Called when a refresh is about to begin for the given refresh type. @Override public void containerRefreshBegin(Container container, RefreshType refreshType) { // Notify UI that the Container refresh is beginning. } // Called when a successful refresh occurred for the given refresh type. @Override public void containerRefreshSuccess(Container container, RefreshType refreshType]) { // Notify UI that Container is ready. } // Called when a refresh failed for the given refresh type. @Override public void containerRefreshFailure(Container container, RefreshType refreshType, RefreshFailure refreshFailure) { // Notify UI that the Container refresh has failed. }
במהלך תהליך הטעינה, TagManager.openContainer() מפעיל כמה קריאות חוזרות (callback) של מחזור החיים, כדי שהקוד יוכל לדעת מתי מתחילה בקשת הטעינה, אם היא נכשלת או מצליחה ולמה, ואם בסופו של דבר המאגר נטען מהדיסק או מהרשת.
אלא אם מקובל שהאפליקציה תשתמש בערכי ברירת המחדל, תצטרכו להשתמש בפונקציות הקריאה החוזרת האלה כדי לדעת מתי מאגר תגים שנשמר או מאגר תגים של הרשת נטען. שימו לב שלא תוכלו לטעון מאגר תגים שמור או מאגר תגים של רשת אם זו הפעם הראשונה שבה מפעילים את האפליקציה ואין חיבור לרשת.
הפונקציה TagManager.openContainer() מעבירה את הערכים הבאים enum
כארגומנטים לפונקציות הקריאה החוזרת האלה:
RefreshType
| ערך | תיאור |
|---|---|
Container.Callback.SAVED
|
בקשת הרענון טוענת מאגר תגים שנשמר באופן מקומי. |
Container.Callback.NETWORK
|
בקשת הרענון טוענת מאגר תגים ברשת. |
RefreshFailure
| ערך | תיאור |
|---|---|
Container.Callback.NO_SAVED_CONTAINER
|
אין מאגר חוויות מאוחסנות זמין. |
Container.Callback.IO_ERROR
|
שגיאת קלט/פלט מנעה את רענון המאגר. |
Container.Callback.NO_NETWORK
|
אין חיבור לרשת. |
Container.Callback.NETWORK_ERROR
|
אירעה שגיאת רשת. |
Container.Callback.SERVER_ERROR
|
אירעה שגיאה בשרת. |
Container.Callback.UNKNOWN_ERROR
|
אירעה שגיאה שלא ניתן לסווג. |
שיטות לפתיחת מאגרי תגים חדשים או מאגרי תגים שאינם ברירת המחדל
ContainerOpener wraps TagManager.openContainer()
and provides two convenience methods for opening containers:
ContainerOpener.openContainer(..., Notifier notifier) and
ContainerOpener.openContainer(..., Long timeoutInMillis).
כל אחת מהשיטות האלה מקבלת ספירה שמבקשת מאגר תגים לא ברירת מחדל או מאגר תגים חדש.
מומלץ לרוב האפליקציות ומנסה להחזיר את המאגר הראשון שזמין ושאינו ברירת מחדל בתוך תקופת זמן קצובה, מדיסק או מרשת, גם אם המאגר ישן יותר מ-12 שעות.OpenType.PREFER_NON_DEFAULT אם הפונקציה מחזירה מאגר תגים ישן שנשמר, היא גם תבצע בקשה אסינכרונית ברשת למאגר תגים חדש.
כשמשתמשים ב-OpenType.PREFER_NON_DEFAULT, אם אין מאגר אחר זמין או אם חלף הזמן הקצוב לתפוגה, המערכת תחזיר מאגר ברירת מחדל.
OpenType.PREFER_FRESH מנסה להחזיר מאגר חדש מהדיסק או מהרשת בתוך פרק הזמן שמוגדר כטיימאאוט.
הפונקציה מחזירה מאגר תגים שמור אם החיבור לרשת לא זמין או אם חלף הזמן הקצוב לתפוגה.
לא מומלץ להשתמש ב-OpenType.PREFER_FRESH
במקומות שבהם זמן בקשה ארוך יותר עלול להשפיע באופן משמעותי על חוויית המשתמש, כמו בדגלים של ממשק המשתמש או במחרוזות לתצוגה. אפשר גם להשתמש ב-Container.refresh() בכל שלב כדי לכפות בקשה של מאגר תגים לרשת.
שתי השיטות האלה נוחות לשימוש ולא חוסמות את התהליך.
הפונקציה ContainerOpener.openContainer(..., Long timeoutInMillis) מחזירה אובייקט ContainerOpener.ContainerFuture, והשיטה get שלו מחזירה אובייקט Container ברגע שהוא נטען (אבל היא תיחסם עד אז).
השיטה ContainerOpener.openContainer(..., Notifier notifier) מקבלת קריאה חוזרת אחת, שנקראת כשהקונטיינר זמין, ואפשר להשתמש בה כדי למנוע חסימה של ה-thread הראשי.
בשתי השיטות, הזמן הקצוב לתפוגה שמוגדר כברירת מחדל הוא 2000 אלפיות השנייה.
הערכה של פקודות מאקרו בזמן ריצה באמצעות כללים
מאגרי תגים יכולים להעריך ערכים בזמן הריצה באמצעות כללים. הכללים יכולים להתבסס על קריטריונים כמו שפת המכשיר, הפלטפורמה או כל ערך מאקרו אחר. לדוגמה, אפשר להשתמש בכללים כדי לבחור מחרוזת תצוגה מותאמת לשפה המקומית על סמך השפה של המכשיר בזמן הריצה. אפשר להגדיר את זה באמצעות הכלל הבא:
לאחר מכן אפשר ליצור פקודות מאקרו לאיסוף ערכים לכל שפה, ולהוסיף את הכלל הזה לכל מאקרו, תוך הוספת קוד השפה המתאים. כשמאגר התגים הזה מתפרסם, האפליקציה יכולה להציג מחרוזות תצוגה מותאמות לשוק המקומי, בהתאם לשפה של מכשיר המשתמש בזמן הריצה.
שימו לב: אם מאגר התגים שמוגדר כברירת מחדל צריך כללים, אתם צריכים להשתמש בקובץ מאגר תגים בינארי כמאגר התגים שמוגדר כברירת מחדל.
מידע נוסף על הגדרת כללים (מרכז העזרה)
קובצי מאגרים בינאריים שמוגדרים כברירת מחדל
מאגרי תגים שמוגדרים כברירת מחדל וצריכים כללים צריכים להשתמש בקובץ בינארי של מאגר תגים במקום בקובץ JSON כמאגר התגים שמוגדר כברירת מחדל. מאגרי תגים בינאריים תומכים בקביעת ערכי מאקרו בזמן ריצה באמצעות כללים של Google Tag Manager, בעוד שקבצי JSON לא תומכים בכך.
אפשר להוריד קבצים בינאריים של מאגרי תגים מממשק האינטרנט של Google Tag Manager, ולהוסיף אותם לתיקייה /assets/tagmanager/ של הפרויקט. הקבצים צריכים להיות בפורמט /assets/tagmanager/GTM-XXXX, כאשר שם הקובץ מייצג את מזהה מאגר התגים.
במקרים שבהם יש קובץ JSON וגם קובץ בינארי של מאגר תגים, ה-SDK ישתמש בקובץ הבינארי של מאגר התגים כמאגר ברירת המחדל.
שימוש בפקודות מאקרו של בקשה להפעלת פונקציה
פקודות מאקרו של קריאה לפונקציה הן פקודות מאקרו שמוגדרות לערך שמוחזר מפונקציה שצוינה באפליקציה. אפשר להשתמש בפקודות מאקרו של קריאה לפונקציה כדי לשלב ערכים של זמן ריצה עם הכללים של Google Tag Manager, למשל כדי לקבוע בזמן ריצה איזה מחיר להציג למשתמש על סמך השפה והמטבע שהוגדרו במכשיר.
כדי להגדיר פקודת מאקרו של קריאה לפונקציה:
- מגדירים את מאקרו קריאת הפונקציה בממשק האינטרנט של Google Tag Manager. אפשר להגדיר את הארגומנטים כצמדי מפתח/ערך.
- רושמים
FunctionCallMacroHandlerבאפליקציה באמצעותContainer.registerFunctionCallMacroHandler()ושם הפונקציה שהגדרתם בממשק האינטרנט של Google Tag Manager, ומבטלים את השיטהgetValue():/** * Registers a function call macro handler. * * @param functionName The function name field, as defined in the Google Tag * Manager web interface. */ mContainer.registerFunctionCallMacroHandler(functionName, new FunctionCallMacroHandler() { /** * This code will execute when any custom macro's rule(s) evaluate to true. * The code should check the functionName and process accordingly. * * @param functionName Corresponds to the function name field defined * in the Google Tag Manager web interface. * @param parameters An optional map of parameters * as defined in the Google Tag Manager web interface. */ @Override public Object getValue(String functionName, Map<String, Object> parameters)) { if (functionName.equals("myConfiguredFunctionName")) { // Process and return the calculated value of this macro accordingly. return macro_value } return null; } });
שימוש בתגי קריאה לפונקציה
תגי קריאה לפונקציה מאפשרים להפעיל פונקציות שנרשמו מראש בכל פעם שאירוע נדחף לשכבת הנתונים והכללים של התג מוערכים כ-true.
כדי להגדיר תג של קריאה לפונקציה:
- מגדירים את תג קריאת הפונקציה בממשק האינטרנט של Google Tag Manager. אפשר להגדיר את הארגומנטים כצמדי מפתח/ערך.
- רושמים handler של תג מסוג function call באפליקציה באמצעות
Container.registerFunctionCallTagHandler():/** * Register a function call tag handler. * * @param functionName The function name, which corresponds to the function name field * Google Tag Manager web interface. */ mContainer.registerFunctionCallTagHandler(functionName, new FunctionCallTagHandler() { /** * This method will be called when any custom tag's rule(s) evaluates to true. * The code should check the functionName and process accordingly. * * @param functionName The functionName passed to the functionCallTagHandler. * @param parameters An optional map of parameters as defined in the Google * Tag Manager web interface. */ @Override public void execute(String functionName, Map<String, Object> parameters) { if (functionName.equals("myConfiguredFunctionName")) { // Process accordingly. } } });
הגדרת תקופת רענון בהתאמה אישית
ערכת ה-SDK של Google Tag Manager תנסה לאחזר מאגר תגים חדש אם הגיל הנוכחי של מאגר התגים עולה על 12 שעות. כדי להגדיר תקופת רענון מותאמת אישית של קונטיינר, משתמשים ב-Timer, כמו בדוגמה הבאה:
timer.scheduleTask(new TimerTask() { @Override public void run() { mContainer.refresh(); } }, delay, <new_period_in milliseconds>);
ניפוי באגים באמצעות Logger
Google Tag Manager SDK מדפיס שגיאות ואזהרות ביומנים כברירת מחדל.
הפעלת רישום מפורט יותר ביומן יכולה לעזור בניפוי באגים. אפשר לעשות זאת על ידי הטמעה של Logger משלכם עם TagManager.setLogger, כמו בדוגמה הזו:
TagManager tagManager = TagManager.getInstance(this); tagManager.setLogger(new Logger() { final String TAG = "myGtmLogger"; // Log output with verbosity level of DEBUG. @Override public void d(String arg0) { Log.d(TAG, arg0); } // Log exceptions when provided. @Override public void d(String arg0, Throwable arg1) { Log.d(TAG, arg0); arg1.printStackTrace(); } // Rest of the unimplemented Logger methods. });
אפשר גם להגדיר את LogLevel של Logger קיים באמצעות
TagManager.getLogger().setLogLevel(LogLevel)
,
כמו בדוגמה הזו:
// Change the LogLevel to INFO to enable logging at INFO and higher levels. TagManager tagManager = TagManager.getInstance(this); tagManager.getLogger().setLogLevel(LogLevel.INFO);