Google Analytics SDK for Android v1 (Legacy)

Google Analytics for Mobile Apps SDK for Android پیاده سازی Google Analytics را در برنامه های مبتنی بر اندروید آسان می کند. این سند نحوه ادغام SDK با برنامه های خود را شرح می دهد.

نمای کلی SDK

این SDK از یک مدل ردیابی استفاده می کند که برای ردیابی کاربران به وب سایت های سنتی و تعامل با ویجت ها در صفحات وب سنتی طراحی شده است. به همین دلیل، عبارات استفاده شده در زیر منعکس کننده مدل مرسوم ردیابی وب سایت هستند و برای ردیابی برنامه های تلفن همراه نگاشت می شوند. برای درک نحوه عملکرد این SDK باید با ردیابی Analytics آشنا باشید.

از SDK ردیابی تلفن همراه برای ردیابی برنامه های تلفن خود با انواع تعامل Analytics زیر استفاده کنید:

ردیابی مشاهده صفحه
نمایش صفحه یک ابزار استاندارد برای اندازه گیری حجم ترافیک به یک وب سایت سنتی است. از آنجایی که برنامه های تلفن همراه حاوی صفحات HTML نیستند، باید تصمیم بگیرید که چه زمانی (و چند وقت یکبار) درخواست مشاهده صفحه را راه اندازی کنید. همچنین، از آنجایی که درخواست‌های مشاهده صفحه برای گزارش ساختارهای دایرکتوری طراحی شده‌اند، باید نام‌های توصیفی برای درخواست‌ها ارائه کنید تا از نام‌گذاری مسیر صفحه در گزارش‌های محتوا در Analytics استفاده کنید. نام‌هایی که انتخاب می‌کنید در گزارش‌های Analytics شما به‌عنوان مسیرهای صفحه پر می‌شوند، حتی اگر در واقع صفحات HTML نیستند، اما می‌توانید با ساختاردهی مسیرها برای ارائه گروه‌بندی‌های اضافی برای تماس‌های خود، از این به نفع خود استفاده کنید.
ردیابی رویداد
در Analytics، رویدادها برای ردیابی تعامل کاربر با عناصر صفحه وب به طور متمایز از درخواست‌های مشاهده صفحه طراحی شده‌اند. می توانید از ویژگی ردیابی رویداد گوگل آنالیتیکس برای برقراری تماس های اضافی استفاده کنید که در بخش ردیابی رویداد رابط گزارش آنالیتیکس گزارش می شود. رویدادها با استفاده از دسته‌ها گروه‌بندی می‌شوند و ممکن است از برچسب‌های هر رویداد نیز استفاده کنند که انعطاف‌پذیری در گزارش‌دهی را فراهم می‌کند. به عنوان مثال، یک برنامه چندرسانه‌ای می‌تواند عملکردهای پخش/توقف/مکث برای دسته ویدیوی خود داشته باشد و برای هر نام ویدیو یک برچسب اختصاص دهد. سپس گزارش‌های Google Analytics رویدادها را برای همه رویدادهای برچسب‌گذاری شده با دسته ویدیو جمع‌آوری می‌کند. برای اطلاعات بیشتر در مورد ردیابی رویداد، به راهنمای ردیابی رویداد مراجعه کنید
ردیابی تجارت الکترونیک
از ویژگی ردیابی تجارت الکترونیک برای ردیابی تراکنش های سبد خرید و خریدهای درون برنامه ای استفاده کنید. برای ردیابی تراکنش، از کلاس Transaction برای نمایش اطلاعات کلی خرید و همچنین از کلاس Item برای نمایش هر محصول در سبد خرید استفاده کنید. پس از جمع‌آوری، داده‌ها را می‌توان در بخش گزارش‌دهی تجارت الکترونیک در رابط Google Analytics مشاهده کرد. برای اطلاعات بیشتر در مورد ردیابی تجارت الکترونیک، به راهنمای ردیابی تجارت الکترونیک مراجعه کنید.
متغیرهای سفارشی
متغیرهای سفارشی تگ‌های جفت نام-مقدار هستند که می‌توانید در کد رهگیری خود وارد کنید تا ردیابی Google Analytics را اصلاح کنید. برای اطلاعات بیشتر در مورد نحوه استفاده از متغیرهای سفارشی، راهنمای متغیر سفارشی را بخوانید.

شروع شدن

الزامات

برای ادغام قابلیت‌های ردیابی Google Analytics با برنامه Android خود، به موارد زیر نیاز دارید:

برپایی

  • 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 ) . پس از ایجاد ویژگی، یک کپی از شناسه ویژگی وب که برای ویژگی جدید ایجاد شده است را یادداشت کنید یا نگه دارید.

شما باید به کاربران خود، چه در خود برنامه یا در شرایط خدمات خود، نشان دهید که این حق را برای خود محفوظ می دارید که به صورت ناشناس فعالیت یک کاربر را در برنامه خود پیگیری و گزارش دهید. استفاده شما از Google Analytics SDK علاوه بر این، تحت شرایط خدمات Google Analytics است که هنگام ثبت نام برای یک حساب، باید با آن موافقت کنید.

نمونه ها و بهترین روش ها

می‌توانید کد نمونه و بهترین روش‌ها را در code.google.com تحت پروژه analytics-api-samples بیابید.

کتابخانه EasyTracker

یک کتابخانه EasyTracker در دسترس است. ردیابی سطح برنامه و فعالیت را تقریباً بدون هیچ تلاشی برای توسعه فراهم می کند. می توانید آن را در بخش دانلودهای پروژه analytics-api-samples پیدا کنید.

راه اندازی ردیاب

ردیاب singleton را با تماس با GoogleAnalyticsTracker.getInstance() دریافت کنید. سپس متد startNewSession آن را فراخوانی کنید و شناسه ویژگی وب و فعالیت در حال پیگیری را ارسال کنید. اگر برنامه شما فقط یک فعالیت داشته باشد، می‌توانید مستقیماً این روش را در متد onCreate Activity خود فراخوانی کنید. مثلا:

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-samples استفاده کنید.

پیگیری بازدید از صفحه و رویدادها

ردیابی بازدید از صفحه و رویدادها ساده است: هر بار که می‌خواهید نمایش صفحه را فعال کنید، به سادگی با 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 کنید، روی شی ردیابی تماس بگیرید، و می توانید این کار را به صورت دستی یا در فواصل زمانی مشخص انجام دهید.

مشکلات شناخته شده

  • فراخوانی متدهای GoogleAnalyticsTracker در رشته‌های مختلف می‌تواند منجر به خطاهای مبهم شود. مطمئن شوید که همه تماس های خود را از یک تاپیک انجام دهید.

    • ردیابی کمپین ها

    SDK از دو نوع ردیابی کمپین پشتیبانی می کند.

    - ردیابی کمپین Google Play - به شما امکان می دهد ارجاعات نصب را از طریق Google Play ردیابی کنید.
    - ردیابی کمپین عمومی - به شما امکان می دهد هر کمپینی را که کاربران را به برنامه شما ارجاع می دهد ردیابی کنید.

    ردیابی کمپین Google Play

    نسخه سیستم عامل Android 1.6 از استفاده از پارامتر URL referrer در لینک های دانلود به Google Play پشتیبانی می کند. Google Analytics SDK برای 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 برای اندروید، اکنون می توانید کمپین ها را برای منابعی غیر از 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 یک جلسه جدید شروع می شود و درست برمی گردد.

    پارامتر ضروری شرح مثال ها)
    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