اندروید نسخه 4 - شروع به کار

توجه: این راهنما پیاده سازی قدیمی گوگل تگ منیجر را در برنامه های اندرویدی توضیح می دهد. کاربران جدید باید از Tag Manager + Firebase برای پیاده سازی Google Tag Manager در برنامه های اندرویدی خود استفاده کنند.

معرفی

Google Tag Manager به توسعه دهندگان این امکان را می دهد تا مقادیر پیکربندی را در برنامه تلفن همراه خود با استفاده از رابط Google Tag Manager بدون نیاز به بازسازی و ارسال مجدد باینری های برنامه به بازارهای برنامه تغییر دهند.

این برای مدیریت مقادیر پیکربندی یا پرچم‌ها در برنامه‌تان که ممکن است در آینده نیاز به تغییر داشته باشید، مفید است، از جمله:

• تنظیمات UI مختلف و رشته های نمایش
• اندازه، مکان یا انواع تبلیغات ارائه شده در برنامه شما
• تنظیمات مختلف بازی

مقادیر پیکربندی همچنین ممکن است در زمان اجرا با استفاده از قوانین ارزیابی شوند و تنظیمات پویا مانند:

• استفاده از اندازه صفحه برای تعیین اندازه بنر تبلیغاتی
• استفاده از زبان و مکان برای پیکربندی عناصر UI

Google TagManager همچنین اجرای پویا ردیابی برچسب ها و پیکسل ها را در برنامه ها فعال می کند. توسعه‌دهندگان می‌توانند رویدادهای مهم را به لایه داده فشار دهند و بعداً تصمیم بگیرند که کدام تگ‌ها یا پیکسل‌های ردیابی باید اجرا شوند.

قبل از اینکه شروع کنی

قبل از شروع این راهنمای شروع مراحل زیر را کامل کنید:

• Android SDK را نصب کنید
• Google Play Services SDK را دانلود کنید
• یک حساب Google Tag Manager ایجاد کنید
• یک ظرف Google Tag Manager را پیکربندی کنید

هنگامی که این مراحل را کامل کردید، بقیه این راهنما نحوه پیکربندی و استفاده از Google Tag Manager را در برنامه Android خود به شما آموزش می دهد.

شروع شدن

پس از دنبال کردن این راهنمای شروع، خواهید فهمید که چگونه:

• Google Tag Manager را به پروژه خود اضافه کنید
• Tag Manager را در برنامه خود راه اندازی کنید
• مقادیر پیکربندی را از ظرف مدیریت برچسب دریافت کنید
• مقادیر و رویدادها را به dataLayer فشار دهید
• پیش نمایش، اشکال زدایی، و انتشار ظرف خود را

این راهنما از تکه‌های کد از برنامه نمونه Cute Animals استفاده می‌کند که همراه با Google Play Services SDK است. منبع کامل این پروژه در: < android-sdk-directory >/extras/google/google_play_services/tagmanager/cuteanimals موجود است.

1. اضافه کردن Google Tag Manager به پروژه شما

برای افزودن Google Tag Manager به پروژه خود:

1. Google Play Services SDK را تنظیم کنید .
2. اگر از یک IDE غیر از Android Studio استفاده می کنید، مجوزهای زیر را به فایل AndroidManifest.xml اضافه کنید:

   <!-- For TagManager SDK -->
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   

3. برای فعال کردن InstallReferrerReceiver برای فراخوانی گیرنده Google Analytics برای تنظیم داده های کمپین، موارد زیر را به فایل AndroidManifest.xml اضافه کنید:

   <!-- Used for install referrer tracking-->
   <service android:name="com.google.android.gms.tagmanager.InstallReferrerService" />
   <receiver
     android:name="com.google.android.gms.tagmanager.InstallReferrerReceiver"
     android:exported="true">
     <intent-filter>
       <action android:name="com.android.vending.INSTALL_REFERRER" />
     </intent-filter>
   </receiver>
   

2. افزودن یک فایل کانتینر پیش فرض به پروژه خود

توجه : اگر هنوز ظرف خود را در رابط وب Google Tag Manager پیکربندی نکرده‌اید، پس از انجام این کار به این مرحله بازگردید.

Google Tag Manager در اولین اجرای برنامه شما از یک ظرف پیش فرض استفاده می کند. به محض اینکه برنامه بتواند یک کانتینر جدید را از طریق شبکه بازیابی کند، کانتینر پیش‌فرض دیگر استفاده نخواهد شد.

برای دانلود و افزودن یک باینری کانتینر پیش فرض به برنامه خود:

1. به رابط وب Google Tag Manager وارد شوید.
2. نسخه ظرف مورد نظر برای دانلود را انتخاب کنید.
3. برای بازیابی باینری کانتینر روی دکمه دانلود کلیک کنید.
4. فایل باینری کانتینر دانلود شده را به عنوان منبع خام به پروژه خود اضافه کنید.
   1. اگر زیرپوشه raw در <project-root>/res/ وجود ندارد، آن را ایجاد کنید.
   2. در صورت لزوم نام فایل باینری کانتینر را تغییر دهید. فقط از حروف کوچک، اعداد و زیرخط تشکیل شده است.
   3. فایل باینری کانتینر را در پوشه <project-root>/res/raw کپی کنید.

اگرچه استفاده از فایل باینری توصیه می شود، اما اگر ظرف شما حاوی قوانین یا برچسب نیست، می توانید به جای آن از یک فایل JSON ساده استفاده کنید.

3. راه اندازی گوگل تگ منیجر

برای مقداردهی اولیه Google Tag Manager در برنامه خود:

1. TagManager singleton:

   TagManager tagManager = TagManager.getInstance(this);
   

   دریافت کنید
2. از TagManager singleton برای درخواست بارگیری یک کانتینر استفاده کنید و شناسه کانتینر Google Tag Manager و همچنین فایل کانتینر پیش فرض خود را مشخص کنید. شناسه کانتینر باید با حروف بزرگ باشد و دقیقاً با شناسه کانتینر در رابط وب Google Tag Manager مطابقت داشته باشد. فراخوانی loadContainerPreferNonDefault() غیر مسدود است و یک PendingResult برمی گرداند:

   PendingResult<ContainerHolder> pending =
           tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
           R.raw.defaultcontainer_binary);
   

3. از ResultCallback برای بازگرداندن ContainerHolder پس از اتمام بارگیری یا اتمام زمان استفاده کنید:

   // The onResult method will be called as soon as one of the following happens:
   //     1. a saved container is loaded
   //     2. if there is no saved container, a network container is loaded
   //     3. the 2-second timeout occurs
   pending.setResultCallback(new ResultCallback<ContainerHolder>() {
       @Override
       public void onResult(ContainerHolder containerHolder) {
           ContainerHolderSingleton.setContainerHolder(containerHolder);
           Container container = containerHolder.getContainer();
           if (!containerHolder.getStatus().isSuccess()) {
               Log.e("CuteAnimals", "failure loading container");
               displayErrorToUser(R.string.load_error);
               return;
           }
           ContainerLoadedCallback.registerCallbacksForContainer(container);
           containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
           startMainActivity();
       }
   }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
   

   توجه : به‌طور پیش‌فرض، هر 12 ساعت یک کانتینر واجد شرایط به‌روزرسانی از طریق شبکه می‌شود. با نحوه بازخوانی دستی یک ظرف آشنا شوید .

   ایجاد یک ظرف نگهدارنده Singleton

   شما باید فقط یک نمونه از ContainerHolder را در هر اجرای برنامه خود نگه دارید. به همین دلیل است که مثال بالا از یک کلاس ابزار ContainerHolderSingleton برای مدیریت دسترسی به نمونه ContainerHolder استفاده می کند. در اینجا به نظر می رسد کلاس ContainerHolderSingleton :

   package com.google.android.tagmanager.examples.cuteanimals;
   
   import com.google.android.gms.tagmanager.ContainerHolder;
   
   /**
    * Singleton to hold the GTM Container (since it should be only created once
    * per run of the app).
    */
   public class ContainerHolderSingleton {
       private static ContainerHolder containerHolder;
   
       /**
        * Utility class; don't instantiate.
        */
       private ContainerHolderSingleton() {
       }
   
       public static ContainerHolder getContainerHolder() {
           return containerHolder;
       }
   
       public static void setContainerHolder(ContainerHolder c) {
           containerHolder = c;
       }
   }
   
   

یک قطعه کد از نمونه برنامه را ببینید

قطعه زیر الگوی کامل پیاده‌سازی شده در متد onCreate() نمونه Activity را نشان می‌دهد:

package com.google.android.tagmanager.examples.cuteanimals;

import java.util.concurrent.TimeUnit;
import java.util.Map;

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.content.Intent;
import android.os.Bundle;
import android.util.Log;

import com.google.android.gms.common.api.PendingResult;
import com.google.android.gms.common.api.ResultCallback;
import com.google.android.gms.tagmanager.Container;
import com.google.android.gms.tagmanager.Container.FunctionCallMacroCallback;
import com.google.android.gms.tagmanager.Container.FunctionCallTagCallback;
import com.google.android.gms.tagmanager.ContainerHolder;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Displays simple splash screen while GTM container is loading. Once the container is loaded,
 * launches the {@link MainActivity}.
 */
public class SplashScreenActivity extends Activity {
    private static final long TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS = 2000;
    private static final String CONTAINER_ID = "GTM-XXXX";

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_splashscreen);

        TagManager tagManager = TagManager.getInstance(this);

        // Modify the log level of the logger to print out not only
        // warning and error messages, but also verbose, debug, info messages.
        tagManager.setVerboseLoggingEnabled(true);

        PendingResult<ContainerHolder> pending =
                tagManager.loadContainerPreferNonDefault(CONTAINER_ID,
                R.raw.defaultcontainer_binary);

        // The onResult method will be called as soon as one of the following happens:
        //     1. a saved container is loaded
        //     2. if there is no saved container, a network container is loaded
        //     3. the 2-second timeout occurs
        pending.setResultCallback(new ResultCallback<ContainerHolder>() {
            @Override
            public void onResult(ContainerHolder containerHolder) {
                ContainerHolderSingleton.setContainerHolder(containerHolder);
                Container container = containerHolder.getContainer();
                if (!containerHolder.getStatus().isSuccess()) {
                    Log.e("CuteAnimals", "failure loading container");
                    displayErrorToUser(R.string.load_error);
                    return;
                }
                ContainerLoadedCallback.registerCallbacksForContainer(container);
                containerHolder.setContainerAvailableListener(new ContainerLoadedCallback());
                startMainActivity();
            }
        }, TIMEOUT_FOR_CONTAINER_OPEN_MILLISECONDS, TimeUnit.MILLISECONDS);
  // Rest of the Activity definition.
}

4. گرفتن مقادیر پیکربندی از کانتینر

پس از بارگیری کانتینر، می توانید مقادیر پیکربندی را با استفاده از هر یک از متدهای Container.get <type> () بازیابی کنید. مقادیر پیکربندی با استفاده از متغیرهای مجموعه ارزش Google Tag Manager تعریف می شوند. به عنوان مثال، روش زیر آخرین رنگی را که ما تصمیم گرفته ایم برای یک عنصر UI استفاده کنیم، بازیابی می کند و آن را به صورت یک عدد صحیح برمی گرداند:

/**
 * Returns an integer representing a color.
 */
private int getColor(String key) {
    return colorFromColorName(containerHolder.getContainer().getString(key));
}

این کد دو کار را برای بازیابی نام رنگ از ظرف انجام می دهد:

1. Container از ContainerHolder با استفاده از ContainerHolder.getContainer() دریافت می کند.
2. مقدار رنگ را با استفاده از Container.getString( key ) دریافت می کند، جایی که شما کلید و مقدار را در رابط وب Google Tag Manager تعریف کرده اید.

5. فشار دادن رویدادها و مقادیر به dataLayer

Google Tag Manager همچنین یک dataLayer ارائه می‌کند که می‌توانید اطلاعات مربوط به برنامه‌تان را که می‌توان در قسمت‌های دیگر برنامه‌تان خواند یا برای فعال کردن برچسب‌هایی که در رابط وب Google Tag Manager پیکربندی کرده‌اید، استفاده کرد.

فشار دادن مقادیر به dataLayer

dataLayer لایه ای از ماندگاری را ارائه می دهد که می توانید از آن برای ذخیره جفت های کلید-مقدار که ممکن است بخواهید در قسمت های دیگر برنامه خود یا به عنوان ورودی تگ های Google Tag Manager استفاده کنید، استفاده کنید.

برای فشار دادن یک مقدار به dataLayer ، این الگو را دنبال کنید:

1. DataLayer singleton:

   DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
   

   دریافت کنید
2. رویداد را با استفاده از DataLayer.push() :

   // Put the image_name into the data layer for future use.
   TagManager.getInstance(this).getDataLayer().push(IMAGE_NAME_KEY, imageName);
   

   فشار دهید

برای دریافت مقدار از dataLayer ، از DataLayer.get( key ) استفاده کنید.

فشار دادن رویدادها به dataLayer

فشار دادن رویدادها به dataLayer به شما این امکان را می دهد که کد برنامه خود را از برچسب هایی که ممکن است بخواهید در پاسخ به آن رویدادها شلیک کنید جدا کنید.

به عنوان مثال، به‌جای کدگذاری سخت تماس‌های ردیابی نمایش‌نمایش Google Analytics در برنامه‌تان، می‌توانید رویدادهای صفحه را روی dataLayer فشار دهید و برچسب‌های ردیابی خود را از طریق رابط وب Google Tag Manager تعریف کنید. این به شما انعطاف‌پذیری می‌دهد تا آن برچسب را تغییر دهید، یا برچسب‌های اضافی اضافه کنید که به رویدادهای صفحه پاسخ می‌دهند، بدون اینکه کد برنامه‌تان را به‌روزرسانی کنید.

برای فشار دادن یک رویداد به dataLayer ، این الگو را دنبال کنید:

1. DataLayer singleton:

   DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
   

   دریافت کنید
2. با استفاده از DataLayer.pushEvent() رویداد را فشار دهید:

   dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
   

   DataLayer.mapOf() یک روش ابزاری است که می توانید از آن برای ایجاد آسان نقشه ای از جفت های کلید-مقدار استفاده کنید که همزمان با فشار دادن رویداد، dataLayer را به روز می کند.

یک قطعه کد از نمونه برنامه را ببینید

کلاس ابزار زیر نحوه فشار دادن رویدادها، مانند اطلاعات مربوط به باز شدن و بسته شدن صفحه در برنامه شما را در dataLayer نشان می دهد:

package com.google.android.tagmanager.examples.cuteanimals;

import android.content.Context;

import com.google.android.gms.tagmanager.DataLayer;
import com.google.android.gms.tagmanager.TagManager;

/**
 * Utility class.
 */
public class Utils {
    private Utils() {
        // private constructor.
    }

    /**
     * Push an "openScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushOpenScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));
    }

    /**
     * Push a "closeScreen" event with the given screen name. Tags that match that event will fire.
     */
    public static void pushCloseScreenEvent(Context context, String screenName) {
        DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
        dataLayer.pushEvent("closeScreen", DataLayer.mapOf("screenName", screenName));
    }
}

6. پیش نمایش، اشکال زدایی، و انتشار

قبل از انتشار نسخه‌ای از کانتینر خود، می‌خواهید پیش‌نمایش آن را مشاهده کنید تا مطمئن شوید که طبق برنامه کار می‌کند. Google Tag Manager به شما این امکان را می دهد که با ایجاد پیوندها و کدهای QR در رابط وب و استفاده از آنها برای باز کردن برنامه خود، نسخه های ظرف خود را پیش نمایش کنید. همچنین می‌توانید یک حالت ورود به سیستم پرمخاطب را برای رفع اشکال هر رفتار غیرمنتظره فعال کنید.

پیش نمایش

برای پیش نمایش نسخه ای از کانتینر خود، این مراحل را دنبال کنید:

1. افزودن این Activity پیش‌نمایش به فایل AndroidManifest شما:

   <!--  Add preview activity. -->
   <activity
       android:name="com.google.android.gms.tagmanager.PreviewActivity"
       android:label="@string/app_name"
       android:noHistory="true">  <!-- optional, removes the previewActivity from the activity stack. -->
       <intent-filter>
         <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
         <action android:name="android.intent.action.VIEW" />
         <category android:name="android.intent.category.DEFAULT" />
         <category android:name="android.intent.category.BROWSABLE"/>
       </intent-filter>
   </activity>
   

   مطمئن شوید که این خط را تغییر دهید تا نام بسته برنامه شما در آن لحاظ شود:

   <data android:scheme="tagmanager.c.com.google.android.tagmanager.examples.cuteanimals" />
   

2. یک پیوند پیش نمایش در رابط وب Google Tag Manager ایجاد کنید
   1. وارد گوگل تگ منیجر شوید
   2. نسخه ظرف را برای پیش نمایش انتخاب کنید
   3. روی دکمه Preview کلیک کنید
   4. نام بسته برنامه خود را وارد کنید و روی ایجاد پیوند پیش‌نمایش شروع کلیک کنید
3. از پیوند ایجاد شده یا کد QR برای راه اندازی برنامه خود استفاده کنید
4. با دنبال کردن پیوندی که توسط گزینه Generate end preview link در رابط وب ایجاد شده است، می توانید از حالت پیش نمایش خارج شوید.

اشکال زدایی

اگر نیاز به عیب‌یابی پیاده‌سازی کانتینر خود دارید، با فراخوانی TagManager.setVerboseLoggingEnabled(true) :

// Modify the log level of the logger to print out not only
// warning and error messages, but also verbose, debug, info messages.
tagManager.setVerboseLoggingEnabled(true);

Logging کامل را فعال کنید.

انتشار

پس از اینکه کانتینر خود را پیش‌نمایش کردید و تأیید کردید که طبق برنامه کار می‌کند، می‌توانید کانتینر خود را منتشر کنید . مقادیر، برچسب‌ها و رویدادهای پیکربندی کانتینر شما دفعه بعد که کانتینرهایشان بازخوانی می‌شود برای کاربران فعال می‌شوند. درباره ظروف طراوت بیشتر بیاموزید .

پیکربندی پیشرفته

بخش‌های زیر گزینه‌های پیکربندی پیشرفته‌ای را که می‌خواهید برای سفارشی‌سازی بیشتر پیاده‌سازی Google Tag Manager خود استفاده کنید، توضیح می‌دهند.

تازه کردن ظرف

به‌طور پیش‌فرض، کانتینر شما هر ۱۲ ساعت واجد شرایط به‌روزرسانی می‌شود. برای بازخوانی دستی ظرف، از ContainerHolder.refresh() استفاده کنید:

ContainerHolderSingleton.getContainerHolder().refresh();

این یک تماس ناهمزمان است که بلافاصله بر نمی گردد. برای کاهش ترافیک شبکه، refresh() فقط هر 15 دقیقه یک بار فراخوانی می شود، در غیر این صورت بدون عملیات خواهد بود.

توجه : این قطعه از کلاس ابزار ContainerHolderSingleton استفاده می کند که در مثال مقداردهی اولیه در بالا توضیح داده شده است.

یک قطعه کد از نمونه برنامه را ببینید

public void refreshButtonClicked(@SuppressWarnings("unused") View view) {
    Log.i(TAG, "refreshButtonClicked");
    ContainerHolderSingleton.getContainerHolder().refresh();

    // Push the "refresh" event to trigger firing an analytics tag.
    TagManager.getInstance(this).getDataLayer().push("event", "refresh");
    // Push the "custom tag" event to trigger firing a custom function call tag.
    TagManager.getInstance(this).getDataLayer().push("event", "custom_tag");
    updateCategories();
}