Android v4 - الخطوات الأولى

ملاحظة: يوضِّح هذا الدليل طريقة التنفيذ القديمة لعلامة Google. المدير في تطبيقات Android. على المستخدمين الجدد استخدام "إدارة العلامات من Google" + Firebase لتنفيذ أداة "إدارة العلامات من Google" في تطبيقات Android.

مقدمة

تتيح أداة "إدارة العلامات من Google" للمطوّرين تغيير قيم الضبط في تطبيق الأجهزة الجوّالة. باستخدام واجهة أداة "إدارة العلامات من Google" بدون الحاجة إلى إعادة إنشاء البرامج الثنائية للتطبيقات وإعادة إرسالها إلى أسواق التطبيقات.

يفيد ذلك في إدارة أي قيم تهيئة أو علامات في تطبيقك قد تحتاج إليها. للتغيير في المستقبل، بما في ذلك:

• إعدادات متنوعة لواجهة المستخدم وسلاسل عرض
• أحجام الإعلانات أو المواقع الجغرافية أو أنواع الإعلانات المعروضة في تطبيقك
• إعدادات مختلفة للألعاب

يمكن أيضًا تقييم قيم الإعدادات في وقت التشغيل باستخدام القواعد، ما يتيح تفعيل الإعدادات الديناميكية. من الإعدادات مثل:

• استخدام حجم الشاشة لتحديد حجم إعلان بانر
• استخدام اللغة والموقع لضبط عناصر واجهة المستخدم

وتعمل أداة "إدارة العلامات من Google" أيضًا على تفعيل التنفيذ الديناميكي لعلامات التتبّع ووحدات البكسل في التطبيقات. يمكن للمطوّرين إرسال الأحداث المهمة إلى طبقة بيانات وتحديد تلك الأحداث لاحقًا يجب تنشيط علامات التتبُّع أو وحدات البكسل.

قبل البدء

أكمل الخطوات التالية قبل البدء في دليل البدء هذا:

• ثبِّت حزمة تطوير البرامج (SDK) لنظام التشغيل Android.
• تنزيل حزمة تطوير البرامج (SDK) لخدمات Google Play
• أنشئ حسابًا على أداة "إدارة العلامات من Google".
• ضبط حاوية أداة "إدارة العلامات من Google"

بعد الانتهاء من هذه الخطوات، سترشدك بقية هذا الدليل إلى كيفية تهيئة أداة "إدارة العلامات من Google" واستخدامها داخل تطبيق Android.

البدء

بعد اتباع دليل الخطوات الأولى هذا، ستفهم كيفية:

• إضافة أداة "إدارة العلامات من Google" إلى مشروعك
• إعداد أداة "إدارة العلامات من Google" في تطبيقك
• الحصول على قيم الضبط من حاوية أداة "إدارة العلامات من Google"
• إرسال القيم والأحداث إلى dataLayer
• معاينة الحاوية وتصحيح الأخطاء ونشرها

يستخدم هذا الدليل مقتطفات الرموز من Cute Animals. تطبيق نموذجي مدرج في حزمة تطوير البرامج (SDK) لخدمات Google Play يتوفر المصدر الكامل لهذا المشروع في: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.

1. إضافة أداة "إدارة العلامات من Google" إلى مشروعك

لإضافة أداة "إدارة العلامات من Google" إلى مشروعك:

1. إعداد "حزمة تطوير البرامج (SDK) لخدمات Google Play"
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" لإعداد بيانات الحملة، أضِف ما يلي إلى ملف 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" عليك العودة إلى هذه الخطوة بعد إكمالها.

تستخدم أداة "إدارة العلامات من Google" حاوية تلقائية عند التشغيل الأول لتطبيقك. الإعداد التلقائي سيتم إيقاف استخدام الحاوية حالما يتمكن التطبيق من استرداد حاوية جديدة عبر الشبكة.

لتنزيل برنامج ثنائي لحاوية تلقائية وإضافتها إلى تطبيقك:

1. سجِّل الدخول إلى واجهة ويب أداة "إدارة العلامات من Google".
2. اختَر إصدار الحاوية التي تريد تنزيلها.
3. انقر على الزر تنزيل لاسترداد البرنامج الثنائي للحاوية.
4. أضف الملف الثنائي للحاوية الذي تم تنزيله إلى مشروعك كمورد أولي.
   1. إذا كان المجلد الفرعي raw ضمن <project-root>/res/ غير موجود. أنشئه.
   2. أعِد تسمية الملف الثنائي للحاوية إذا لزم الأمر. وهي تتألف من الأحرف الصغيرة والأرقام والشرطات السفلية.
   3. انسخ الملف الثنائي للحاوية إلى المجلد. <project-root>/res/raw

وعلى الرغم من أننا ننصح باستخدام الملف الثنائي، إذا لم تكن الحاوية تحتوي على قواعد أو علامات، يمكنك اختيار استخدام ملف JSON بسيط بدلاً من ذلك.

3- إعداد أداة "إدارة العلامات من Google"

لإعداد أداة "إدارة العلامات من Google" في تطبيقك:

1. الحصول على TagManager سينغلتون:

   TagManager tagManager = TagManager.getInstance(this);

2. يمكنك استخدام المفردة TagManager لإرسال طلب لتحميل حاوية، لتحديد رقم تعريف حاوية "إدارة العلامات من Google" بالإضافة إلى حاويتك التلقائية الملف. يجب أن يكون رقم تعريف الحاوية كبيرًا وأن يتطابق تمامًا مع رقم تعريف الحاوية في علامة Google. واجهة الويب للمدير. المكالمة إلى 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 ساعة. كيفية إعادة تحميل الحاوية يدويًا

   إنشاء ContainerHolder سينغلتون

   يجب الاحتفاظ بمثيل واحد من 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" على سبيل المثال، الطريقة التالية لاسترداد أحدث لون قررنا استخدامه في عنصر من عناصر واجهة المستخدم وإرجاعه عدد صحيح:

/**
 * 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.

5- دفع الأحداث والقيم إلى dataLayer

توفّر أداة "إدارة العلامات من Google" أيضًا رمز dataLayer يمكنك إرسال المعلومات إليه. عن تطبيقك والتي يمكن قراءتها في أجزاء أخرى من التطبيق أو استخدامها لتنشيط العلامات التي أعددتها في واجهة الويب لبرنامج "إدارة العلامات من Google"

دفع القيم إلى dataLayer

يوفّر dataLayer طبقة من المثابرة يمكنك استخدامها. لتخزين أزواج المفتاح/القيمة التي قد ترغب في استخدامها في أجزاء أخرى من التطبيق، أو كإدخالات لعلامات "إدارة العلامات من Google"

لإرسال قيمة إلى dataLayer، اتّبِع النمط التالي:

1. الحصول على DataLayer سينغلتون:

   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" في تطبيقك، يمكنك دفع أحداث الشاشة إلى dataLayer وتحديد علامات التتبّع من خلال واجهة الويب لبرنامج "إدارة العلامات من Google". يمنحك هذا مرونة لتعديل تلك العلامة أو إضافة علامات إضافية تتجاوب مع أحداث الشاشة، بدون تعديل رمز تطبيقك.

لإرسال حدث إلى dataLayer، اتّبِع النمط التالي:

1. الحصول على DataLayer سينغلتون:

   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" إمكانية معاينة إصدارات حاويتك عن طريق إنشاء روابط ورموز استجابة سريعة في واجهة الويب واستخدامها لفتح تطبيقك. يمكنك أيضًا تفعيل وضع التسجيل المطوَّل لتصحيح أخطاء أي سلوك غير متوقّع.

جارٍ المعاينة

لمعاينة إصدار من حاويتك، اتّبِع الخطوات التالية:

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"
   1. سجِّل الدخول إلى أداة "إدارة العلامات من Google".
   2. اختَر إصدار الحاوية لمعاينتها.
   3. انقر على الزرّ معاينة.
   4. أدخِل اسم حزمة التطبيق وانقر على إنشاء رابط بدء المعاينة.
3. استخدِم الرابط الذي تم إنشاؤه أو رمز الاستجابة السريعة لتشغيل تطبيقك.
4. يمكنك الخروج من وضع المعاينة من خلال اتّباع الرابط الذي تم إنشاؤه من خلال رابط إنشاء إنهاء المعاينة. في واجهة الويب.

تصحيح الأخطاء

إذا كنت بحاجة إلى تحديد المشاكل وحلّها في ما يتعلّق بتنفيذ الحاوية، عليك تفعيل التسجيل المطوَّل من خلال استدعاء 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);

النشر

بعد معاينة الحاوية والتحقق من أنها تعمل على النحو المنشود، يمكنك: انشر حاويتك. قيم تهيئة الحاوية والعلامات والأحداث للمستخدمين في المرة القادمة التي يمكنهم فيها يتم تحديث الحاويات. مزيد من المعلومات عن إعادة تحميل الحاويات

إعداد متقدم

تصف الأقسام التالية خيارات الضبط المتقدمة التي تريد استخدامها لإجراء مزيد من تخصيص تنفيذ "إدارة العلامات من Google".

إعادة تحميل الحاوية

بشكلٍ تلقائي، تصبح حاويتك مؤهَّلة لإعادة التحميل كل 12 ساعة. لإعادة التحميل يدويًا الحاوية، استخدم 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();
}