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، أضِف الأذونات التالية إلى ملف 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. اختَر الحاوية Version لمعاينتها.
   3. انقر على الزرّ Preview (معاينة).
   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();
}