مقدمة
تتيح أداة Google Tag Manager للمطوّرين تغيير قيم الإعدادات في تطبيقاتهم للأجهزة الجوّالة باستخدام واجهة Google Tag Manager بدون الحاجة إلى إعادة إنشاء الملفات الثنائية للتطبيقات وإعادة إرسالها إلى أسواق التطبيقات.
ويُعدّ ذلك مفيدًا لإدارة أي قيم أو علامات إعداد في تطبيقك قد تحتاج إلى تغييرها في المستقبل، بما في ذلك:
- إعدادات واجهة المستخدم المختلفة وسلاسل العرض
- أحجام الإعلانات المعروضة في تطبيقك أو مواقعها أو أنواعها
- إعدادات ألعاب مختلفة
يمكن أيضًا تقييم قيم الإعدادات أثناء التشغيل باستخدام القواعد، ما يتيح استخدام الإعدادات الديناميكية، مثل:
- استخدام حجم الشاشة لتحديد حجم إعلان البانر
- استخدام اللغة والموقع الجغرافي لضبط عناصر في واجهة المستخدم
تتيح أداة Google Tag Manager أيضًا التنفيذ الديناميكي لعلامات التتبُّع ووحدات البكسل في التطبيقات. يمكن للمطوّرين إرسال الأحداث المهمة إلى طبقة بيانات وتحديد علامات التتبّع أو وحدات البكسل التي يجب تفعيلها لاحقًا.
قبل البدء
أكمِل الخطوات التالية قبل البدء في دليل البدء هذا:
- تثبيت حزمة تطوير البرامج (SDK) لنظام التشغيل Android
- نزِّل حزمة تطوير البرامج (SDK) لخدمات Google Play
- إنشاء حساب على Google Tag Manager
- إعداد حاوية Google Tag Manager
بعد إكمال هذه الخطوات، سيشرح لك الجزء المتبقي من هذا الدليل كيفية ضبط Google Tag Manager واستخدامه في تطبيق Android.
البدء
بعد اتّباع دليل البدء هذا، ستتعرّف على كيفية:
- إضافة Google Tag Manager إلى مشروعك
- إعداد Tag Manager في تطبيقك
- الحصول على قيم الإعدادات من حاوية في Tag Manager
- إرسال القيم والأحداث إلى
dataLayer - معاينة الحاوية وتصحيح الأخطاء فيها ونشرها
يستخدم هذا الدليل مقتطفات من الرموز البرمجية من Cute Animals
نموذج التطبيق المضمّن في
حزمة تطوير البرامج (SDK) لخدمات Google Play.
يتوفّر المصدر الكامل لهذا المشروع في: <android-sdk-directory>/extras/google/google_play_services/tagmanager/cuteanimals.
1. إضافة Google Tag Manager إلى مشروعك
لإضافة Google Tag Manager إلى مشروعك:
- إعداد حزمة تطوير البرامج (SDK) لخدمات Google Play
- إذا كنت تستخدم بيئة تطوير متكاملة (IDE) غير استوديو Android، أضِف الأذونات التالية إلى ملف
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 Tag Manager حاوية تلقائية عند تشغيل تطبيقك لأول مرة. سيتوقف استخدام الحاوية التلقائية فور تمكُّن التطبيق من استرداد حاوية جديدة عبر الشبكة.
لتنزيل ملف ثنائي تلقائي للحاوية وإضافته إلى تطبيقك:
- سجِّل الدخول إلى واجهة الويب في Google Tag Manager.
- اختَر إصدار الحاوية التي تريد تنزيلها.
- انقر على الزر تنزيل لاسترداد الملف الثنائي للحاوية.
- أضِف ملف الحاوية الثنائي الذي تم تنزيله إلى مشروعك كمورد أوّلي.
- إذا لم يكن المجلد الفرعي
rawضمن<project-root>/res/متوفّرًا، عليك إنشاؤه. - أعِد تسمية الملف الثنائي للحاوية إذا لزم الأمر. ويتألف من أحرف صغيرة وأرقام وشرطات سفلية فقط.
- انسخ الملف الثنائي للحاوية إلى المجلد
<project-root>/res/raw.
- إذا لم يكن المجلد الفرعي
على الرغم من أنّه يُنصح باستخدام الملف الثنائي، إذا كانت الحاوية لا تحتوي على قواعد أو علامات، يمكنك اختيار استخدام ملف JSON بسيط بدلاً من ذلك.
3- جارٍ إعداد Google Tag Manager
لإعداد Google Tag Manager في تطبيقك:
- احصل على عنصر سينغلتون
TagManager:TagManager tagManager = TagManager.getInstance(this);
- استخدِم العنصر المفرد
TagManagerلتقديم طلب تحميل حاوية، مع تحديد رقم تعريف حاوية في Google Tag Manager وملف الحاوية التلقائية. يجب أن يكون رقم تعريف الحاوية مكتوبًا بأحرف لاتينية كبيرة وأن يتطابق تمامًا مع رقم تعريف الحاوية في واجهة الويب في Google Tag Manager. لا يسبب استدعاء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 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; } }
4. الحصول على قيم الإعدادات من الحاوية
بعد تحميل الحاوية، يمكنك استرداد قيم الإعدادات باستخدام أي من طرق Container.get<type>(). يتم تحديد قيم الإعدادات باستخدام
متغيّرات جمع القِيم في Google Tag Manager. على سبيل المثال، تستردّ الطريقة التالية آخر لون قرّرنا استخدامه لعنصر في واجهة المستخدم وتعرضه كعدد صحيح:
/** * 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 Tag Manager.
5- إرسال الأحداث والقيم إلى dataLayer
توفّر أداة Google Tag Manager أيضًا dataLayer، يمكنك من خلالها إرسال معلومات
عن تطبيقك يمكن قراءتها في أجزاء أخرى من تطبيقك أو استخدامها لتشغيل العلامات
التي أعددتها في واجهة الويب لأداة Google Tag Manager.
إرسال القيم إلى dataLayer
توفّر dataLayer طبقة من الثبات يمكنك استخدامها
لتخزين أزواج المفاتيح والقيم التي قد تريد استخدامها في أجزاء أخرى من تطبيقك، أو
كمدخلات لعلامات Google Tag Manager.
لإرسال قيمة إلى 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 Tag Manager. يمنحك ذلك المرونة لتعديل هذه العلامة أو إضافة علامات أخرى تستجيب لأحداث الشاشة، بدون تعديل الرمز البرمجي للتطبيق.
لإرسال حدث إلى dataLayer، اتّبِع هذا النمط:
- احصل على عنصر سينغلتون
DataLayer:DataLayer dataLayer = TagManager.getInstance(context).getDataLayer();
- أرسِل الحدث باستخدام
DataLayer.pushEvent():dataLayer.pushEvent("openScreen", DataLayer.mapOf("screenName", screenName));DataLayer.mapOf()هي طريقة مساعِدة يمكنك استخدامها لإنشاء خريطة لأزواج المفتاح/القيمة بسهولة، والتي ستعدّلdataLayerفي الوقت نفسه الذي يتم فيه إرسال الحدث.
6. المعاينة وتصحيح الأخطاء والنشر
قبل نشر نسخة من الحاوية، عليك معاينتها للتأكّد من أنّها تعمل على النحو المطلوب. تتيح لك أداة Google Tag Manager معاينة إصدارات الحاوية من خلال إنشاء روابط ورموز استجابة سريعة في واجهة الويب واستخدامها لفتح تطبيقك. يمكنك أيضًا تفعيل وضع التسجيل المطوَّل لتصحيح أي سلوك غير متوقَّع.
جارٍ المعاينة
لمعاينة نسخة من الحاوية، اتّبِع الخطوات التالية:
- إضافة هذه النسخة الحصرية من
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 Tag Manager
- تسجيل الدخول إلى Google Tag Manager
- اختَر إصدار الحاوية الذي تريد معاينته
- انقر على الزرّ معاينة
- أدخِل اسم حزمة تطبيقك وانقر على إنشاء رابط بدء المعاينة
- استخدِم الرابط أو رمز الاستجابة السريعة الذي تم إنشاؤه لتشغيل تطبيقك
- يمكنك الخروج من وضع المعاينة من خلال اتّباع رابط تم إنشاؤه باستخدام خيار إنشاء رابط إنهاء المعاينة في واجهة الويب.
تصحيح الأخطاء
إذا كنت بحاجة إلى تحديد المشاكل وحلّها في عملية تنفيذ الحاوية، فعِّل التسجيل المطوَّل من خلال استدعاء
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 Tag Manager بشكل أكبر.
إعادة تحميل الحاوية
تلقائيًا، تصبح الحاوية مؤهَّلة لإعادة التحميل كل 12 ساعة. لإعادة تحميل الحاوية يدويًا، استخدِم ContainerHolder.refresh():
ContainerHolderSingleton.getContainerHolder().refresh();
هذا استدعاء غير متزامن لن يتم عرضه على الفور. لتقليل حركة بيانات الشبكة، يمكن استدعاء refresh() مرة واحدة فقط كل 15 دقيقة، وإلا لن يتم تنفيذ أي إجراء.