במדריך הזה למפתחים נסביר איך להטמיע את Google Tag Manager ליישום לנייד.
מבוא
Google Tag Manager מאפשר למפתחים לשנות את התצורה באפליקציות לנייד באמצעות Google Tag Manager ללא צורך ליצור מחדש את הקבצים הבינאריים של האפליקציות ולשלוח אותם מחדש זירות מסחר.
האפשרות הזו שימושית לניהול ערכי תצורה או סימונים באפליקציה שייתכן שתצטרכו לשנות בעתיד, כולל:
- הגדרות שונות של ממשק המשתמש ומחרוזות תצוגה
- הגדלים, המיקומים או הסוגים של המודעות שמוצגות באפליקציה
- הגדרות של משחקים
אפשר להעריך את ערכי ההגדרות גם בזמן הריצה באמצעות כללים, הפעלת הגדרות דינמיות, כמו:
- שימוש בגודל המסך כדי לקבוע את גודל הבאנר של המודעה
- שימוש בשפה ובמיקום להגדרת רכיבים בממשק המשתמש
Google Tag Manager מאפשר גם הטמעה דינמית של תגי מעקב ופיקסלים באפליקציות. המפתחים יכולים לדחוף אירועים חשובים לנתונים בשכבת זרימת הנתונים ולהחליט מאוחר יותר אילו תגי מעקב או פיקסלים יופעלו. TagManager תומך כרגע בתגים הבאים:
- Analytics לאפליקציות לנייד של Google
- תג קריאה לפונקציה מותאמת אישית
לפני שתתחיל
כדי להשתמש במדריך לתחילת העבודה, אתם צריכים:
- חשבון Google Tag Manager
- Tag Manager חדש מאקרו של איסוף ערכים ומאגרי קונטיינר
- אפליקציה לנייד ל-Android שבה צריך להטמיע את Google Tag Manager
- שירותי Google Analytics SDK, שמכיל את ספריית Tag Manager.
אם זו הפעם הראשונה שאתם משתמשים ב-Google Tag Manager, מומלץ מידע נוסף על מאגרים, פקודות מאקרו וכללים (מרכז העזרה) לפני המשך המדריך הזה.
תחילת העבודה
הקטע הזה ינחה את המפתחים בתהליך העבודה הרגיל של Tag Manager:
- מוסיפים את Google Tag Manager SDK לפרויקט
- הגדרת ערכי ברירת מחדל למאגר תגים
- פתיחת המאגר
- קבלת ערכי תצורה מהמאגר
- דחיפת אירועים לשכבת הנתונים
- תצוגה מקדימה ו פרסום מאגר התגים
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
בקריאה החוזרת של containerAvailable
, אנחנו מוודאים
ה-thread הראשי לא חסום. אם המאגר השמור מלפני יותר מ-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. דחיפת ערכים לשכבת הנתונים
שכבת הנתונים היא מפה שמאפשרת למאגר התגים ב-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
. ממשיכים מכאן
את כתובת האתר של התצוגה המקדימה, כי תצטרכו אותה בשלבים הבאים.
בשלב הבא, צריך להוסיף את הפעילות הבאה
קובץ 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()
בעיות
קריאות חוזרות (callback) במחזור החיים, כדי שהקוד יוכל לגלות מתי
הטעינה מתחילה, האם היא נכשלת או מצליחה, והאם
הקונטיינר נטען בסופו של דבר מהדיסק או מהרשת.
אלא אם האפליקציה שלך יכולה להשתמש בערכי ברירת המחדל, תצטרכו להשתמש בקריאות החוזרות האלה כדי לדעת מתי הרשת או המאגר נטען. לתשומת ליבך, לא ניתן לטעון פריט שמור מאגר רשת, אם זו הפעם הראשונה שהאפליקציה מופעלת ואין חיבור לרשת.
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
, שה-method 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 של תג קריאה לפונקציה באפליקציה באמצעות
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
ערכת ה-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);