במדריך למפתחים הזה מוסבר איך להטמיע את Google Tag Manager באפליקציה לנייד.
מבוא
Google Tag Manager מאפשר למפתחים לשנות ערכי הגדרות באפליקציות לנייד באמצעות הממשק של Google Tag Manager, בלי צורך לבנות מחדש את הקבצים הבינאריים של האפליקציה ולשלוח אותם מחדש לחנויות האפליקציות.
האפשרות הזו שימושית לניהול ערכי הגדרות או דגלים באפליקציה, שאולי תצטרכו לשנות בעתיד, כולל:
- הגדרות שונות של ממשק המשתמש ומחרוזות תצוגה
- הגודל, המיקום או הסוג של המודעות שמוצגות באפליקציה
- הגדרות של משחקים
אפשר גם להעריך את ערכי ההגדרות בזמן הריצה באמצעות כללים, וכך להפעיל הגדרות דינמיות כמו:
- שימוש בגודל המסך כדי לקבוע את גודל מודעת הבאנר
- שימוש בשפה ובמיקום כדי להגדיר רכיבים בממשק המשתמש
Google Tag Manager גם מאפשר הטמעה דינמית של תגי מעקב ופיקסלים באפליקציות. המפתחים יכולים להעביר אירועים חשובים לשכבת נתונים ולהחליט מאוחר יותר אילו תגי מעקב או פיקסלים יופעלו. TagManager תומך בתגים הבאים:
- Google Analytics לאפליקציות לנייד
- תג מותאם אישית של בקשה להפעלת פונקציה
לפני שתתחיל
לפני שמשתמשים במדריך לתחילת הדרך הזה, צריך:
- חשבון Google Tag Manager
- מאגר תגים חדש של Tag Manager ומאקרו לאיסוף ערכים
- אפליקציה ל-Android שבה רוצים להטמיע את Google Tag Manager
- ערכת פיתוח תוכנה ל-Google Analytics Services, שמכילה את הספרייה של Tag Manager.
אם זו הפעם הראשונה שאתם משתמשים ב-Google Tag Manager, מומלץ לקרוא מידע נוסף על מאגרי תגים, פקודות מאקרו וכללים (במרכז העזרה) לפני שתמשיכו לקרוא את המדריך הזה.
תחילת העבודה
בקטע הזה נסביר למפתחים על תהליך עבודה אופייני ב-Tag Manager:
- הוספת ה-SDK של Google Tag Manager לפרויקט
- הגדרת ערכי ברירת מחדל למאגר
- פתיחת המאגר
- קבלת ערכי הגדרה מהמאגר
- העברת אירועים אל dataLayer
- תצוגה מקדימה ופרסום של מאגר התגים
1. הוספת ה-SDK של Google Tag Manager לפרויקט
לפני שמשתמשים ב-Google Tag Manager SDK, צריך לחלץ את חבילת ה-SDK, להוסיף את הספרייה לנתיב ה-build של הפרויקט ולהוסיף הרשאות לקובץ 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.
- בוחרים את הגרסה של מאגר התגים שרוצים להוריד.
- לוחצים על הלחצן Download כדי לאחזר את הקובץ הבינארי של מאגר התגים.
- מוסיפים את הקובץ הבינארי לנתיב הבא:
<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
שכבת הנתונים היא מפה שמאפשרת להעביר מידע בזמן ריצה על האפליקציה, כמו אירועי מגע או צפיות במסך, לפקודות מאקרו ולתגים של 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) שיופעלו בכל צפייה במסך. כדי לעשות את זה, צריך ליצור את הכלל הבא: שווה ל-"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 לנייד יש כמה אפשרויות הגדרה מתקדמות שמאפשרות לכם לבחור ערכים על סמך תנאים בזמן הריצה באמצעות כללים, לרענן את מאגר התגים באופן ידני ולקבל אפשרויות נוספות לפתיחת מאגרי תגים. בקטעים הבאים מתוארות כמה מההגדרות המתקדמות הנפוצות ביותר.
אפשרויות מתקדמות לפתיחת קונטיינרים
ה-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() מפעיל כמה קריאות חוזרות במחזור חיים כדי שהקוד שלכם יוכל לזהות מתי בקשת הטעינה מתחילה, אם היא נכשלת או מצליחה ולמה, ואם הקונטיינר נטען בסופו של דבר מהדיסק או מהרשת.
אם אתם לא רוצים שהאפליקציה תשתמש בערכי ברירת המחדל, תצטרכו להשתמש בקריאות החוזרות האלה כדי לדעת מתי נטען מאגר תגים שנשמר או מאגר תגים ברשת. שימו לב: לא תוכלו לטעון מאגר שמור או מאגר רשת אם זו הפעם הראשונה שהאפליקציה פועלת ואין חיבור לרשת.
TagManager.openContainer() מעביר את הערכים הבאים של enum כארגומנטים לקריאות החוזרות האלה:
RefreshType
| ערך | תיאור |
|---|---|
Container.Callback.SAVED
|
בקשת הרענון טוענת מאגר שנשמר באופן מקומי. |
Container.Callback.NETWORK
|
בקשת הרענון טוענת מאגר תגים דרך הרשת. |
RefreshFailure
| ערך | תיאור |
|---|---|
Container.Callback.NO_SAVED_CONTAINER
|
אין קונטיינר שמור זמין. |
Container.Callback.IO_ERROR
|
שגיאת קלט/פלט (I/O) מנעה את רענון המאגר. |
Container.Callback.NO_NETWORK
|
אין חיבור לרשת. |
Container.Callback.NETWORK_ERROR
|
אירעה שגיאה בחיבור לרשת. |
Container.Callback.SERVER_ERROR
|
אירעה שגיאה בשרת. |
Container.Callback.UNKNOWN_ERROR
|
אירעה שגיאה שלא ניתן לסווג. |
שיטות לפתיחת מאגרי תגים חדשים ולא מוגדרים כברירת מחדל
ContainerOpener כולל את TagManager.openContainer() ומספק שתי שיטות נוחות לפתיחת מאגרי תגים: ContainerOpener.openContainer(..., Notifier notifier) ו-ContainerOpener.openContainer(..., Long timeoutInMillis).
כל אחת מהשיטות האלה מקבלת ספירה שמבקשת מאגר שהוא לא ברירת מחדל או מאגר חדש.
האפשרות OpenType.PREFER_NON_DEFAULT מומלצת לרוב האפליקציות. היא מנסה להחזיר את מאגר התגים הראשון שזמין, שהוא לא ברירת המחדל, בתוך פרק זמן נתון, מהדיסק או מהרשת, גם אם מאגר התגים הזה נוצר לפני יותר מ-12 שעות. אם הוא מחזיר מאגר שמור לא עדכני, הוא גם ישלח בקשה לאחזור מהרשת אסינכרונית כדי לקבל מאגר עדכני.
כשמשתמשים ב-OpenType.PREFER_NON_DEFAULT, אם אין מאגר תגים זמין או אם חלף הזמן הקצוב לתפוגה, יוחזר מאגר תגים שמוגדר כברירת מחדל.
OpenType.PREFER_FRESH מנסה להחזיר קונטיינר חדש מהדיסק או מהרשת בתוך פרק הזמן הקצוב שניתן.
הפונקציה מחזירה מאגר תגים שמור אם אין חיבור לרשת או אם חלף פרק הזמן הקצוב לתפוגה.
לא מומלץ להשתמש ב-OpenType.PREFER_FRESH במקומות שבהם זמן בקשה ארוך יותר עלול להשפיע באופן ניכר על חוויית המשתמש, כמו בדגלים של ממשק המשתמש או במחרוזות תצוגה. אפשר גם להשתמש ב-Container.refresh() בכל שלב כדי לאלץ בקשה של מאגר תגים ברשת.
שתי השיטות האלה לא חוסמות.
השיטה ContainerOpener.openContainer(..., Long timeoutInMillis) מחזירה אובייקט ContainerOpener.ContainerFuture, שהשיטה get שלו מחזירה Container ברגע שהיא נטענת (אבל היא תחסום עד אז).
השיטה ContainerOpener.openContainer(..., Notifier notifier) מקבלת קריאה חוזרת (callback) אחת, שמופעלת כשהמאגר זמין, ואפשר להשתמש בה כדי למנוע חסימה של ה-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 של תג בקשה להפעלת פונקציה באפליקציה באמצעות
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. } } });
הגדרת תקופת רענון בהתאמה אישית
אם עברו יותר מ-12 שעות מאז שהמאגר הנוכחי נוצר, ה-SDK של Google Tag Manager ינסה לאחזר מאגר חדש. כדי להגדיר תקופת רענון בהתאמה אישית של מאגר התגים, משתמשים ב-Timer, כמו בדוגמה הבאה:
timer.scheduleTask(new TimerTask() { @Override public void run() { mContainer.refresh(); } }, delay, <new_period_in milliseconds>);
ניפוי באגים באמצעות Logger
כברירת מחדל, ה-SDK של Google Tag Manager מדפיס שגיאות ואזהרות ביומנים.
כדי להפעיל רישום מפורט יותר ביומן, שיכול לעזור בניפוי באגים, אפשר להטמיע 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);