مقدمة
تتيح أداة "إدارة العلامات من 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" إلى مشروعك:
- إعداد "حزمة تطوير البرامج (SDK) لخدمات Google Play"
- في حال استخدام بيئة تطوير متكاملة (IDE) بخلاف
Android Studio، أضِف الأذونات التالية إلى
ملف
AndroidManifest.xml
:<!-- For TagManager SDK --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
- لتمكين
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".
- اختَر إصدار الحاوية التي تريد تنزيلها.
- انقر على الزر تنزيل لاسترداد البرنامج الثنائي للحاوية.
- أضف الملف الثنائي للحاوية الذي تم تنزيله إلى مشروعك كمورد أولي.
- إذا كان المجلد الفرعي
raw
ضمن<project-root>/res/
غير موجود. أنشئه. - أعِد تسمية الملف الثنائي للحاوية إذا لزم الأمر. وهي تتألف من الأحرف الصغيرة والأرقام والشرطات السفلية.
- انسخ الملف الثنائي للحاوية إلى المجلد.
<project-root>/res/raw
- إذا كان المجلد الفرعي
وعلى الرغم من أننا ننصح باستخدام الملف الثنائي، إذا لم تكن الحاوية تحتوي على قواعد أو علامات، يمكنك اختيار استخدام ملف JSON بسيط بدلاً من ذلك.
3- إعداد أداة "إدارة العلامات من Google"
لإعداد أداة "إدارة العلامات من Google" في تطبيقك:
- الحصول على
TagManager
سينغلتون:TagManager tagManager = TagManager.getInstance(this);
- يمكنك استخدام المفردة
TagManager
لإرسال طلب لتحميل حاوية، لتحديد رقم تعريف حاوية "إدارة العلامات من Google" بالإضافة إلى حاويتك التلقائية الملف. يجب أن يكون رقم تعريف الحاوية كبيرًا وأن يتطابق تمامًا مع رقم تعريف الحاوية في علامة Google. واجهة الويب للمدير. المكالمة إلىloadContainerPreferNonDefault()
لا تحظر ويُرجعPendingResult
:PendingResult<ContainerHolder> pending = tagManager.loadContainerPreferNonDefault(CONTAINER_ID, R.raw.defaultcontainer_binary);
- استخدام
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);
إنشاء 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)); }
تقوم هذه التعليمة البرمجية بأمرين لاسترداد اسم اللون من الحاوية:
- يحصل على
Container
منContainerHolder
باستخدامContainerHolder.getContainer()
- تحصل على قيمة اللون باستخدام
Container.getString(key)
، حيث لديك حددت المفتاح والقيمة في واجهة الويب لبرنامج إدارة العلامات من Google.
5- دفع الأحداث والقيم إلى dataLayer
توفّر أداة "إدارة العلامات من Google" أيضًا رمز dataLayer
يمكنك إرسال المعلومات إليه.
عن تطبيقك والتي يمكن قراءتها في أجزاء أخرى من التطبيق أو استخدامها لتنشيط العلامات
التي أعددتها في واجهة الويب لبرنامج "إدارة العلامات من Google"
دفع القيم إلى dataLayer
يوفّر dataLayer
طبقة من المثابرة يمكنك استخدامها.
لتخزين أزواج المفتاح/القيمة التي قد ترغب في استخدامها في أجزاء أخرى من التطبيق، أو
كإدخالات لعلامات "إدارة العلامات من Google"
لإرسال قيمة إلى dataLayer
، اتّبِع النمط التالي:
- الحصول على
DataLayer
سينغلتون:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- إرسال الحدث باستخدام
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
، اتّبِع النمط التالي:
- الحصول على
DataLayer
سينغلتون:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- إرسال الحدث باستخدام
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" إمكانية معاينة إصدارات حاويتك عن طريق إنشاء روابط ورموز استجابة سريعة في واجهة الويب واستخدامها لفتح تطبيقك. يمكنك أيضًا تفعيل وضع التسجيل المطوَّل لتصحيح أخطاء أي سلوك غير متوقّع.
جارٍ المعاينة
لمعاينة إصدار من حاويتك، اتّبِع الخطوات التالية:
- جارٍ إضافة معاينة "
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" />
- إنشاء رابط معاينة في واجهة ويب "إدارة العلامات من Google"
- سجِّل الدخول إلى أداة "إدارة العلامات من Google".
- اختَر إصدار الحاوية لمعاينتها.
- انقر على الزرّ معاينة.
- أدخِل اسم حزمة التطبيق وانقر على إنشاء رابط بدء المعاينة.
- استخدِم الرابط الذي تم إنشاؤه أو رمز الاستجابة السريعة لتشغيل تطبيقك.
- يمكنك الخروج من وضع المعاينة من خلال اتّباع الرابط الذي تم إنشاؤه من خلال رابط إنشاء إنهاء المعاينة. في واجهة الويب.
تصحيح الأخطاء
إذا كنت بحاجة إلى تحديد المشاكل وحلّها في ما يتعلّق بتنفيذ الحاوية، عليك تفعيل التسجيل المطوَّل من خلال استدعاء
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 دقيقة، وإلا فلن يتم حل المشكلة.
الاطلاع على مقتطف رمز من نموذج تطبيق
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(); }