Google Analytics SDK ל-Android v1 (מדור קודם)

בעזרת Google Analytics for Mobile Apps SDK ל-Android קל להטמיע את Google Analytics באפליקציות מבוססות Android. מסמך זה מתאר כיצד לשלב את ה-SDK עם האפליקציות שלך.

סקירה כללית של SDK

ערכת ה-SDK הזו משתמשת במודל מעקב כדי לעקוב אחר משתמשים באתרים מסורתיים ולנהל אינטראקציה עם ווידג'טים בדפי אינטרנט מסורתיים. מסיבה זו, המונחים שמפורטים בהמשך משקפים את מודל המעקב הרגיל של האתר וממופים למעקב אחר אפליקציות לנייד. כדי להבין איך ה-SDK הזה עובד, כדאי להכיר את מעקב Analytics.

תוכלו להשתמש ב-SDK למעקב בנייד כדי לעקוב אחר אפליקציות הטלפון שלכם באמצעות סוגי האינטראקציה הבאים ב-Analytics:

מעקב אחר צפיות בדפים
צפייה בדף היא אמצעי רגיל למדידת נפח התנועה לאתר רגיל. אפליקציות לנייד לא כוללות דפי HTML, ולכן עליך להחליט מתי (ובאיזו תדירות) להפעיל בקשה לצפייה בדף. כמו כן, מכיוון שהבקשות להצגת דפים מיועדות לדיווח על מבני ספריות, עליך לספק שמות תיאוריים לבקשות כדי לנצל את השמות של נתיבי הדפים בדוחות התוכן ב-Analytics. השמות שיוצגו בדוחות יאוכלסו בדוחות כנתיבי דפים, למרות שהם לא דפי HTML בפועל. עם זאת, כדאי להשתמש בהם כדי ליצור קבוצות נוספות לשיחות.
מעקב אחר אירועים
ב-Analytics, אירועים מיועדים למעקב אחר אינטראקציות של משתמשים עם רכיבי דף אינטרנט, בנפרד מבקשות לצפייה בדף. ניתן להשתמש בתכונה 'מעקב אחר אירועים' ב-Google Analytics כדי לקבל שיחות נוספות שדווחו בקטע 'מעקב אחר אירועים' בממשק הדוח של Analytics. האירועים מקובצים לפי קטגוריות, ועשויים גם להשתמש בתוויות לכל אירוע כדי לספק גמישות בדיווח. לדוגמה, אפליקציית מולטימדיה יכולה לבצע פעולות הפעלה/עצירה/השהיה עבור קטגוריית הסרטון שלה ולהקצות תווית לכל שם סרטון. לאחר מכן, דוחות Google Analytics יצברו אירועים עבור כל האירועים שתויגו עם הקטגוריה סרטון. למידע נוסף על מעקב אחר אירועים, ניתן לעיין במדריך למעקב אחר אירועים
מעקב אחר מסחר אלקטרוני
מומלץ להשתמש בתכונת המעקב אחר מסחר אלקטרוני כדי לעקוב אחר עסקאות של עגלת קניות ורכישות מתוך האפליקציה. כדי לעקוב אחר עסקה, יש להשתמש במחלקה Transaction כדי לייצג את פרטי הרכישה הכוללים, וכן במחלקה Item כדי לייצג כל מוצר בסל הקניות. לאחר מכן הנתונים יוצגו בקטע 'דיווח על מסחר אלקטרוני' בממשק של Google Analytics. למידע נוסף על מעקב אחר מסחר אלקטרוני, מומלץ לעיין במדריך למעקב אחר מסחר אלקטרוני.
משתנים מותאמים אישית
משתנים מותאמים אישית הם תגי זוג של שם-ערך שניתן להוסיף לקוד המעקב כדי לצמצם את המעקב של Google Analytics. מידע נוסף על אופן השימוש במשתנים מותאמים אישית מפורט במדריך למשתנים מותאמים אישית.

תחילת העבודה

דרישות

כדי לשלב את יכולות המעקב של Google Analytics' תצטרכו את הדברים הבאים:

הגדרה

  • מוסיפים את libGoogleAnalytics.jar לספרייה /libs של הפרויקט.
  • יש להוסיף את ההרשאות הבאות לקובץ המניפסט של הפרויקט: AndroidManifest.xml
    • <uses-permission android:name="android.permission.INTERNET" />
    • <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

SDK כולל אפליקציה לדוגמה שמדגים איך הפרויקט אמור להיראות אם הוא יוגדר בהצלחה. אפשר להשתמש בה כתבנית לאפליקציות המשולבות ב-Analytics.

שימוש ב-SDK

לפני שמתחילים להשתמש ב-SDK, קודם צריך ליצור חשבון בחינם בכתובת www.google.com/analytics וליצור נכס אינטרנט חדש בחשבון הזה באמצעות כתובת URL מזויפת אבל תיאורית (למשל http://mymobileapp.mywebsite.com). אחרי יצירת הנכס, יש לרשום או לשמור עותק של מזהה נכס האינטרנט שנוצר עבור הנכס החדש.

עליך לציין בפני המשתמשים שלך, באפליקציה עצמה או בתנאים ובהגבלות, שאת/ה שומר/ת את הזכות לעקוב באופן אנונימי אחר פעילות של משתמש בתוך האפליקציה שלך. השימוש ב-SDK של Google Analytics כפוף גם הוא לתנאים ולהגבלות של Google Analytics, שהסכמת להם בעת ההרשמה לחשבון.

דוגמאות ושיטות מומלצות

את קוד לדוגמה ואת השיטות המומלצות אפשר למצוא בכתובת code.google.com בפרויקט analytics-api-sample.

ספרייה ב-EasyTracker

יש ספרייה ב-EasyTracker. היא מספקת מעקב אחר אפליקציות ו פעילות ללא מאמץ פיתוח. אפשר למצוא אותו בקטע הורדות בפרויקט analytics-api-sample.

הפעלת הכלי למעקב

כדי לקבל את הסינגל למעקב, עליך להתקשר ל-GoogleAnalyticsTracker.getInstance(). לאחר מכן מפעילים את השיטה startNewSession, ומעבירים את מזהה נכס האינטרנט ואת הפעילות שבמעקב. אפשר לקרוא לשיטה הזו ישירות בשיטת onCreate של הפעילות, אם לאפליקציה שלך יש פעילות אחת בלבד. למשל:

package com.google.android.apps.analytics.sample;

import com.google.android.apps.analytics.GoogleAnalyticsTracker;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class TestActivity extends Activity {

  GoogleAnalyticsTracker tracker;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    tracker = GoogleAnalyticsTracker.getInstance();

    // Start the tracker in manual dispatch mode...
    tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", this);

    // ...alternatively, the tracker can be started with a dispatch interval (in seconds).
    //tracker.startNewSession("UA-YOUR-ACCOUNT-HERE", 20, this);

    setContentView(R.layout.main);
    Button createEventButton = (Button)findViewById(R.id.NewEventButton);
    createEventButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        tracker.trackEvent(
            "Clicks",  // Category
            "Button",  // Action
            "clicked", // Label
            77);       // Value
      }
    });

    Button createPageButton = (Button)findViewById(R.id.NewPageButton);
    createPageButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Add a Custom Variable to this pageview, with name of "Medium" and value "MobileApp" and
        // scope of session-level.
        tracker.setCustomVar(1, "Navigation Type", "Button click", 2);
        // Track a page view. This is probably the best way to track which parts of your application
        // are being used.
        // E.g.
        // tracker.trackPageView("/help"); to track someone looking at the help screen.
        // tracker.trackPageView("/level2"); to track someone reaching level 2 in a game.
        // tracker.trackPageView("/uploadScreen"); to track someone using an upload screen.
        tracker.trackPageView("/testApplicationHomeScreen");
      }
    });

    Button quitButton = (Button)findViewById(R.id.QuitButton);
    quitButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        finish();
      }
    });

    Button dispatchButton = (Button)findViewById(R.id.DispatchButton);
    dispatchButton.setOnClickListener(new OnClickListener() {
      @Override
      public void onClick(View v) {
        // Manually start a dispatch, not needed if the tracker was started with a dispatch
        // interval.
        tracker.dispatch();
      }
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    // Stop the tracker when it is no longer needed.
    tracker.stopSession();
  }
}

אם האפליקציה שלכם כוללת מספר פעילויות, תוכלו להשתמש בספריית EasyTracker שסופקה בקטע הורדות בפרויקט analytics-api-sample.

מעקב אחר צפיות בדפים ואירועים

המעקב אחר צפיות בדפים ואירועים הוא פשוט: פשוט קוראים ל-trackPageView מאובייקט המעקב בכל פעם שרוצים להפעיל צפייה בדף. צריך להתקשר אל trackEvent כדי להקליט אירוע. מידע נוסף על צפיות בדף ואירועים זמין למעלה בקטע סקירה כללית של SDK.

שימוש במשתנים מותאמים אישית

פשוט מוסיפים משתנה מותאם אישית: פשוט משתמשים בשיטה setCustomVar שמסופקת על ידי ה-SDK לנייד. מומלץ לתכנן מראש את האינדקס של כל משתנה מותאם אישית, כדי שלא תחליפו משתנה קיים. מידע נוסף על משתנים מותאמים אישית מפורט במדריך ליצירת משתנים מותאמים אישית. הערה: השיטה setCustomVar לא שולחת ישירות נתונים. במקום זאת, הנתונים נשלחים עם הצפייה בדף או האירוע הבאים שבמעקב. צריך להתקשר אל setCustomVar לפני מעקב אחר צפייה בדף או אירוע. הערה: היקף ברירת המחדל של משתנים מותאמים אישית הוא ברמת הדף.

שימוש במעקב אחר מסחר אלקטרוני

יש 4 שיטות שבהן אתם משתמשים כדי להפעיל מעקב אחר מסחר אלקטרוני באפליקציה שלכם:

  • addTransaction
  • addItem
  • trackTransactions
  • clearTransactions

קריאה ל-addTransaction ול-addItem מוסיפה את העסקה או הפריט למאגר נתונים פנימי של מסחר אלקטרוני, שאליו ניתן להוסיף עוד פריטים ועסקאות. רק בזמן שמתקשרים אל trackTransactions, העסקאות והפריטים יישלחו למגישי הבקשות ותורצו לשלוח אותם אל Google Analytics.

כדי לנקות את המאגר, אפשר לקרוא לשיטה clearTransactions. הערה: היא לא זוכרת עסקאות קודמות שנשלחו למוקדן או עסקאות שכבר נאספו על ידי Google Analytics.

קוד הדוגמה הבא יכול לעזור לכם להתחיל. אנחנו מניחים שהשיטה onPurchaseCompleted נקראת כשהרכישה תאושר או תידחה.

  /**
   * The purchase was processed.  We will track the transaction and its associated line items
   * now, but only if the purchase has been confirmed.
   *
   * @param purchase A PurchaseObject containing all of the transaction information needed to
   *     send the ecommerce hit to Google Analytics.
   */
  public void onPurchaseCompleted(PurchaseObject purchase) {
    tracker.addTransaction(new Transaction.Builder(
        purchase.getTransactionId(),
        purchase.getTotal())
        .setStoreName(purchase.getStoreName())
        .setTotalTax(purchase.getTotalTax())
        .setShippingCost(purchase.getShippingCost())
        .build());
    for (PurchaseLineItem lineItem : purchase.getLineItems()) {
        tracker.addItem(new Item.Builder(
            purchase.getTransactionId(),
            lineItem.getItemSKU(),
            lineItem.getItemCost(),
            lineItem.getQuantity())
            .setItemName(lineItem.getItemName())
            .setItemCategory(lineItem.getItemCategory())
            .build());
    }
    if (purchase.isConfirmed()) {
      tracker.trackTransactions();
    } else {
      // The purchase was denied or failed in some way.  We need to clear out
      // any data we've already put in the Ecommerce buffer.
      tracker.clearTransactions();
    }
  }

למידע נוסף על מסחר אלקטרוני, מומלץ לעיין במדריך למעקב אחר מסחר אלקטרוני.

הסתר זהות IP

כדי להגדיר אנונימיזציה של פרטי כתובת ה-IP של המשתמש, יש להשתמש בשיטה setAnonymizeIp. פעולה זו מורה ל-Google Analytics לבצע אנונימיזציה של המידע שנשלח על ידי ה-SDK, על ידי הסרת התווים האחרונים של כתובת ה-IP לפני האחסון שלה.

אפשר להתקשר אל setAnonymizeIp בכל שלב.

הגדרת קצב דגימה

אפשר להגדיר את תדירות הדגימה באמצעות השיטה setSampleRate. אם האפליקציה שלכם יוצרת הרבה תנועת גולשים ב-Analytics, הגדרת קצב הדגימה עשויה למנוע את יצירת הדוחות באמצעות נתונים שנדגמו. הדגימה מתבצעת באופן עקבי אצל משתמשים ייחודיים, כך שיש תקינות בדיווח ובדיווחים כאשר מופעל שיעור הדגימה. השיטה setSampleRate מקבלת פרמטר int אחד. הערכים החוקיים לפרמטר זה הם מספרים שלמים בין 0 ל-100, כולל.

שיעור 0 משבית את יצירת ההיטים, ואילו קצב של 100 שולח את כל הנתונים אל Google Analytics. עדיף להתקשר אל setSampleRate לפני שמתקשרים לשיטות מעקב.

לקבלת מידע נוסף על דגימה, אתם יכולים לעיין במדריך לקונספט של דגימה.

להיטי אצווה

כדי לחסוך בחיבור ובתקורה של הסוללה, מומלץ לקבץ את בקשות המעקב. ניתן לקרוא ל-dispatch באובייקט המעקב בכל פעם שרוצים לשלוח בקשת אצווה, וניתן לעשות זאת באופן ידני או במרווחי זמן ספציפיים.

בעיות ידועות

  • קריאה לשיטות של Google AnalyticsTracker בשרשורים שונים עלולה לגרום לשגיאות מעורפלות. צריך להקפיד לבצע את כל השיחות מאותו שרשור.
  • מעקב אחר קמפיינים

    ה-SDK תומך בשני סוגים של מעקב אחר קמפיינים.

    - מעקב אחר קמפיינים של Google Play – מאפשר לך לעקוב אחר הפניות להתקנה דרך Google Play.
    - מעקב כללי אחר קמפיינים – מאפשר לכם לעקוב אחר קמפיינים שמפנים משתמשים אל האפליקציה שלכם.

    מעקב אחר קמפיינים ב-Google Play

    גרסת Android 1.6 תומכת בשימוש בפרמטר referrer של כתובת URL בקישורים להורדה אל Google Play. ה-SDK של Google Analytics ל-Android משתמש בפרמטר הזה כדי לאכלס באופן אוטומטי מידע על קמפיינים ב-Google Analytics עבור האפליקציה שלכם. כך ניתן לתעד את המקור של התקנת האפליקציה ולשייך אותו לצפיות ולאירועים עתידיים. אירוע זה יכול לעזור לכם למדוד את היעילות של פרסומת מסוימת באפליקציה, לדוגמה.

    כדי שמעקב ההפניות יפעל, עליך להוסיף את קטע הקוד הבא לפרויקט המניפסט AndroidManifest.xml:

    <!-- Used for install referrer tracking -->
    <receiver android:name="com.google.android.apps.analytics.AnalyticsReceiver" android:exported="true">
      <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
      </intent-filter>
    </receiver>
    

    כדי להגדיר מעקב אחר קמפיינים ב-Google Analytics דרך Google Play, משתמשים בכלי ליצירת כתובות URL שבהמשך כדי ליצור קישור מפנה. השתמש בקישור כדי להפנות משתמשים לאפליקציה שלך. מערכת Analytics SDK תנתח ותתעד באופן אוטומטי את פרטי ההפניה ותאכלס אותם בדוח Analytics.

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

    מעקב כללי אחר קמפיינים

    עם גרסה 1.3 של Google Analytics SDK ל-Android, ניתן עכשיו לעקוב אחר קמפיינים עבור מקורות שאינם Google Play. לדוגמה, אם אתם רוצים לדעת שהאפליקציה שלכם הושקה מקישור במודעה, תוכלו לבדוק את פרטי ההפניה של הקמפיין מתוך כוונה שגרמה להפעלת האפליקציה. לאחר מכן, עליכם לשמור את פרטי הקמפיין ב-Google Analytics.

    כדי להגדיר את פרטי ההפניה לקמפיין, צריך להשתמש בשיטה setReferrer, כך:

      tracker.setReferrer(referrer);
    

    יש שתי הגבלות על השימוש בתכונה זו. לפני שמתקשרים, צריך להתקשר למספר startNewSession. setReferrer צריך לעשות זאת כי מסד הנתונים של SQLite המשמש את Google Analytics אינו מוגדר לפני הקריאה ל-startNewSession ול-setReferrer הוא דרוש למסד הנתונים. אם לא התקשרת startNewSession, נציג לך IllegalStateException.

    ההגבלה השנייה היא שמחרוזת ההפניה שהועברה אל setReferrer צריכה להיות בפורמט ספציפי. הוא חייב להיות בצורת קבוצה של פרמטרים של כתובת URL ועליו לכלול לפחות פרמטר gclid או פרמטר אחד מכל utm_campaign, utm_medium ו-utm_source. במקרה השני, הוא יכול לכלול גם פרמטרים מסוג utm_term ו-utm_content.

    הפרמטר GCLID הוא חלק מתכונת התיוג האוטומטי שמקשרת את Google Analytics באופן אוטומטי ל-Google Ads. דוגמה למיקוד של קמפיין באמצעות תיוג אוטומטי עשויה להיראות כך:

    referrer = “gclid=gclidValue”;
    

    מחרוזת ההפניה הידנית של הקמפיין עשויה להיראות כך:

    referrer = “utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;
    

    אם תעבירו מחרוזת גורם מפנה בפורמט שגוי אל setReferrer, הפרטים של הגורם המפנה לא ישתנו ותקבלו ערך החזרה של False. ערך החזרה של true מציין שהגורם המפנה עודכן ויתווסף לכל היט בהמשך.

    כמו כן, כדאי להפעיל סשן חדש כשמתקשרים ל-setReferrer ומחזירה את הערך true.

    פרמטר חובה תיאור דוגמאות
    utm_campaign כן שם הקמפיין; משמש לניתוח של מילות מפתח כדי לזהות קידום ספציפי של מוצר או קמפיין אסטרטגי utm_campaign=spring_sale
    utm_source כן מקור הקמפיין, משמש לזיהוי מנוע חיפוש, ניוזלטר או מקור אחר utm_source=google
    utm_medium כן אמצעי ההגעה לאתר של הקמפיין; משמש לזיהוי אמצעי הגעה לאתר, כמו כתובת אימייל או עלות לקליק (CPC) utm_medium=cpc
    utm_term לא מונח הקמפיין. נעשה שימוש בחיפוש בתשלום כדי לספק את מילות המפתח למודעות utm_term=running+shoes
    utm_content לא תוכן הקמפיין. משמש לבדיקת A/B ולמודעות שמטרגטות תוכן כדי להבדיל בין מודעות או קישורים שמפנים לאותה כתובת URL utm_content=logolink
    utm_content=textlink