وضع العلامات من جهة الخادم لتطبيقات الأجهزة الجوّالة

يمكنك ضبط تطبيقاتك على الأجهزة الجوّالة باستخدام حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google لبرنامج Firebase" للعمل مع وضع علامات التتبُّع من جانب الخادم في Google Tag Manager.

تتيح لك ميزة "وضع العلامات من جهة الخادم" تنظيم بياناتك وإخفاء محتواها وتوسيعها قبل إرسالها إلى منتجات الوجهة، مثل "إحصاءات Google". مزيد من المعلومات عن وضع العلامات من جهة الخادم.

لإعداد ميزة "وضع العلامات من جهة الخادم" للتطبيقات على الأجهزة الجوّالة، اتّبِع الخطوات التالية:

1. إعداد تطبيقك لاستخدام ميزة "وضع العلامات من جهة الخادم"
2. ضبط حاوية الخادم لتتوافق مع الزيارات من الأجهزة الجوّالة
3. تفعيل ميزة "وضع علامات التتبُّع من جانب الخادم" في موقع "إحصاءات Google‏ 4 (GA4)"

المتطلبات الأساسية

• يجب تضمين حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google لبرنامج Firebase" في تطبيقك وربطها بموقع إحصاءات Google‏ 4. مزيد من المعلومات عن حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google لبرنامج Firebase".
• يجب أن يكون لديك حساب على أداة "إدارة العلامات من Google" وحاوية خادم. إذا لم يكن لديك حساب وحاوية، يمكنك إنشاء حساب وحاوية جديدَين على أداة "إدارة العلامات من Google".
• يجب إعداد خادم وضع العلامات.

الخطوة 1: إعداد تطبيقك لاستخدام ميزة "وضع العلامات من جهة الخادم"

iOS

1. فعِّل ميزة تحميل البيانات من ميزة "وضع العلامات من جهة الخادم" واضبط نظام عناوين URL المخصّص لوضع العلامات من جهة الخادم في وضع تصحيح الأخطاء في ملف Info.plist. استبدِل BUNDLE_ID في ما يلي بمعرّف حزمة التطبيق.

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
   ...
           <key>CFBundleURLTypes</key>
           <array>
                   <dict>
                           <key>CFBundleTypeRole</key>
                           <string>None</string>
                           <key>CFBundleURLName</key>
                           <string>BUNDLE_ID</string>
                           <key>CFBundleURLSchemes</key>
                           <array>
                                   <string>tagmanager.sgtm.c.BUNDLE_ID</string>
                           </array>
                   </dict>
           </array>
           <key>GOOGLE_ANALYTICS_SGTM_UPLOAD_ENABLED</key>
           <true/>
   </dict>
   </plist>
   

2. لتفعيل وضع تصحيح الأخطاء أو وضع المعاينة، أضِف طلبًا إلى Analytics.handleOpen(_:) في إحدى طرق مراحل النشاط لتمرير عنوان URL للتشغيل.

   SwiftUI

   @main
   struct MyApplication: App {
     var body: some Scene {
       WindowGroup {
         ContentView()
           .onOpenURL { url in
             Analytics.handleOpen(url)
           }
       }
     }
   }
   

   UIScene

   class SceneDelegate: UIResponder, UIWindowSceneDelegate {
   func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
           options connectionOptions: UIScene.ConnectionOptions) {
   ...
       if let urlContext = connectionOptions.urlContexts.first {
           let url = urlContext.url
           Analytics.handleOpen(url)
       }
     }
   }
   

   بالنسبة إلى التطبيقات التي لا تستخدِم SwiftUI أو UIScene، ليس مطلوبًا اتّخاذ أي إجراء. تتلقّى حزمة تطوير البرامج (SDK) عنوان URL للتشغيل من ApplicationDidFinishLaunchingNotification.

Android

1. ثبِّت أحدث إصدار من حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google لبرنامج Firebase".

2. فعِّل أداة "إدارة العلامات من Google" من جهة الخادم (sGTM) من خلال إضافة ما يلي إلى ملف AndroidManifest.xml الخاص بالتطبيق.

   <!-- Preview Activity to enable preview mode –->
     <activity
         android:name="com.google.firebase.analytics.GoogleAnalyticsServerPreviewActivity"
         android:exported="true"
         android:noHistory="true" >
       <intent-filter>
         <action android:name="android.intent.action.VIEW" />
         <category android:name="android.intent.category.DEFAULT" />
         <category android:name="android.intent.category.BROWSABLE" />
         <data android:scheme="tagmanager.sgtm.c.<APP_PACKAGE_ID>" />
       </intent-filter>
     </activity>
   
   <!-- Meta-data that enables uploads to sGTM –->
     <meta-data android:name="google_analytics_sgtm_upload_enabled" android:value="true" />
   

   ملاحظة: يجب أن تكون جميع الأحرف في <APP_PACKAGE_ID> صغيرة. تكون عملية مطابقة المخطط في إطار عمل Android حسّاسة لحالة الأحرف، على عكس RFC.

الخطوة 2: ضبط حاوية الخادم لتتوافق مع الزيارات من الأجهزة الجوّالة

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

إعداد برنامج "إحصاءات Google": ‏GA4 (التطبيق) من جهة العميل

البرنامج من جهة العميل هو نوع من موارد Tag Manager يعترض أنواعًا معيّنة من الطلبات الواردة ويُنشئ أحداثًا يمكن تمريرها إلى وجهة، مثل إحصاءات Google‏ 4. في هذه الحالة، يكون طلب HTTP حدثًا في "إحصاءات Google‏ 4"، لذا عليك ضبط برنامج "إحصاءات Google": ‏GA4 (التطبيق) من جهة العميل المضمّن. تحتاج إلى برنامج واحد فقط من جهة العميل في "إحصاءات Google‏ 4" لكل مصدر بيانات، مثل حزمة تطوير البرامج (SDK) في "إحصاءات Google" والموقع الإلكتروني. مزيد من المعلومات عن طريقة عمل البرامج من جهة العميل.

1. في حاوية الخادم، انتقِل إلى البرامج من جهة العميل وانقر على جديد.

2. انقر على ضبط البرنامج من جهة العميل، ثمّ اختَر إحصاءات Google: ‏GA4 (التطبيق).

   

3. أدخِل اسمًا للبرنامج من جهة العميل وانقر على حفظ.

ضبط علامة "إحصاءات Google": ‏GA4

لإرسال البيانات إلى "إحصاءات Google"، عليك إنشاء علامة "إحصاءات Google": ‏GA4 في حاوية الخادم. يحلّل البرنامج من جهة العميل طلب HTTP الوارد إلى عنصر بيانات حدث. ستأخذ العلامة عنصر بيانات الحدث هذا وتطابقه مع التنسيق الصحيح، ثمّ ترسله إلى "إحصاءات Google‏ 4".

1. في حاوية الخادم، انتقِل إلى العلامات وانقر على جديد.

2. انقر على ضبط العلامة، ثمّ اختَر إحصاءات Google: ‏GA4.

   

ستكتسب العلامة تلقائيًا جميع الحقول والمَعلمات ذات الصلة من عنصر بيانات الحدث الذي أنشأه البرنامج من جهة العميل:

• إذا كان طلب "إحصاءات Google‏ 4" الوارد يمرّ عبر برنامج إحصاءات Google: ‏GA4 (التطبيق) من جهة العميل، تكتسب العلامة رقم تعريف التطبيق ومَعلمات الحدث.
• إذا كان طلب "إحصاءات Google‏ 4" الوارد يمرّ عبر برنامج إحصاءات Google: ‏GA4 (الويب) من جهة العميل، تكتسب العلامة رقم تعريف القياس ومَعلمات الحدث.

ملاحظة: يمكنك اختياريًا استخدام عمليات التحويل لتضمين مَعلمات الحدث التي يعرضها البرنامج من جهة العميل أو استبعادها أو تعديلها قبل عرضها على العلامات. من خلال عمليات التحويل، يمكنك حماية المعلومات الحسّاسة والتحكّم بشكلٍ دقيق في مَعلمات الحدث المتاحة لعمليات معالجة إضافية.

إعداد عوامل تشغيل الزيارات من الأجهزة الجوّالة

عليك بعد ذلك تحديد متى يجب إطلاق علامة "إحصاءات Google‏ 4". يحلّل برنامج "إحصاءات Google": ‏GA4 (التطبيق) من جهة العميل الطلب الوارد إلى عنصر بيانات الأحداث، وستكتسب العلامة قيمه. لذلك، من المفترض أن يتم إطلاق العلامة كلما طالب البرنامج من جهة العميل في "إحصاءات Google‏ 4" بالطلب.

لإعداد عوامل التشغيل، اتّبِع الخطوات التالية:

1. في إعدادات العلامة، انقر على عوامل التشغيل.
2. لإنشاء عامل تشغيل جديد، انقر على رمز + في أعلى يسار الشاشة.
3. انقر على ضبط عامل التشغيل لاختيار نوع عامل التشغيل.

4. اختَر مخصّص أو حدث مخصّص من القائمة.

   • يُطلق نوع عامل التشغيل المخصّص العلامة تلقائيًا عندما يُنشئ برنامج من جهة العميل في الخادم أي حدث.
   • يمكن استخدام نوع عامل التشغيل حدث مخصّص لإطلاق العلامة عند اسم حدث معيّن أو حدث يطابق نمط تعبير عادي.

5. لتفعيل قائمة شروط التفعيل لعامل التشغيل هذا، مثل إطلاقه فقط عند بيانات أحداث الأجهزة الجوّالة أو الويب، اختَر بعض الأحداث.

   1. سيظهر لك اسم الحدث محدّدًا مسبقًا. انقر على أداة الاختيار هذه واختَر اختيار متغيّر غير قابل للتخصيص من القائمة.
   2. لعرض اسم البرنامج من جهة العميل الذي أنشأ الحدث تلقائيًا، اختَر اسم البرنامج من جهة العميل.

   3. استخدِم اسم البرنامج من جهة العميل الذي ضبطته سابقًا لضبط الشرط وفقًا لذلك. من المفترض أن يبدو عامل التشغيل على النحو التالي:

      

      ملاحظة: اسم البرنامج من جهة العميل هو ما حدّدته في الخطوة السابقة. نوع البرنامج من جهة العميل هو "إحصاءات Google": ‏GA4 (التطبيق). يعرض المتغيّر "اسم البرنامج من جهة العميل" الاسم وليس نوع البرنامج من جهة العميل.

6. احفظ عامل التشغيل وأدخِل اسمًا وصفيًا له. على سبيل المثال، يمكنك استخدام "كل أحداث التطبيق في إحصاءات Google‏ 4".

7. من المفترض أن تعود الآن إلى إعدادات العلامة مع ظهور عامل التشغيل الجديد في مكانه. احفظ العلامة وأدخِل اسمًا وصفيًا لها، مثل "إحصاءات Google‏ 4". من المفترض أن تظهر علامتك بالشكل التالي:

   

ملاحظة: لاستبعاد أحداث معيّنة من الإرسال، يمكنك اختيار استخدام عوامل تشغيل مخصّصة تتضمّن منطقًا شرطيًا يستند إلى اسم الحدث (أو بعض المتغيّرات الأخرى) أو إضافة استثناءات لعوامل التشغيل. مزيد من المعلومات عن إطلاق عوامل التشغيل واستثناءات عوامل التشغيل.

معاينة حاويتك

يمكنك استخدام أداة Google Tag Manager لمعاينة حاوية الخادم وتصحيح أخطائها قبل نشر التغييرات. يُرجى العِلم أنّ المعاينة لن تعمل إلى أن تفعِّل ميزة "وضع علامات التتبُّع من جانب الخادم" في موقع "إحصاءات Google‏ 4" (GA4) .

لكي تؤدي طلبات تطبيقك إلى إطلاق إعدادات المعاينة، عليك تنفيذ ما يلي:

1. انقر على معاينة أثناء استخدام حاوية الخادم في Google Tag Manager.
2. انقر على رمز المزيد من الإجراءات ⋮ في أعلى يسار الشاشة، ثمّ اختَر إرسال الطلبات من تطبيق.

3. أدخِل رقم تعريف تطبيقك وانقر على إنشاء رمز الاستجابة السريعة.

   ملاحظة: يجب أن يبدأ رقم تعريف التطبيق بحرف. بدلاً من ذلك، يمكنك استخدام أي رقم تعريف فريد يبدأ بحرف ما دام يطابق رقم التعريف المستخدَم في ملف Info.plist أو AndroidManifest.xml.

   

4. امسَح رمز الاستجابة السريعة ضوئيًا باستخدام تطبيق الكاميرا على هاتفك. تفاعَل مع تطبيقك كالمعتاد لإنشاء أحداث المعاينة.

5. انقر على حسنًا لإغلاق مربّع الحوار.

نشر حاويتك

بعد التحقّق من التغييرات، انشر الحاوية لتفعيل هذه التغييرات لجميع الزيارات. مزيد من المعلومات عن النشر والإصدارات والموافقات.

الخطوة 3: تفعيل ميزة "وضع علامات التتبُّع من جانب الخادم" في موقع "إحصاءات Google‏ 4" (GA4)

1. في موقعك على "إحصاءات Google‏ 4"، انتقِل إلى المشرف.
2. افتح مصادر البيانات.

3. اختَر إعدادات مصدر بيانات تطبيقك من علامة التبويب iOS أو Android.

   

4. انقر على ضبط إعدادات حزمة تطوير البرامج (SDK)، ثمّ على ضبط أداة "إدارة العلامات من Google" من جهة الخادم.

   

5. لتمكين حزمة تطوير البرامج (SDK) من إرسال بيانات القياس إلى عنوان URL لحاوية الخادم، اتّبِع الخطوات التالية:

   1. فعِّل الخيار إرسال البيانات إلى حاوية Tag Manager من جهة الخادم.
   2. انسخ عنوان URL لحاوية الخادم. يمكنك العثور على هذا العنوان في أداة "إدارة العلامات من Google" من خلال الانتقال إلى المشرف > إعدادات الحاوية > عناوين URL لحاوية الخادم.

   3. اختَر النسبة المئوية من الزيارات التي تريد توجيهها إلى حاوية الخادم. يمكنك اختيار خيار أقل من% 100 للتحقّق من إعداد الخادم وضبطه قبل استخدام ميزة "وضع العلامات من جهة الخادم" لجميع الزيارات.

      **ملاحظة:** استخدِم الخيار الأجهزة المخصّصة لتصحيح الأخطاء فقط لتمكين التطبيقات التي يتم فتحها باستخدام وضع المعاينة فقط من إرسال البيانات إلى خادمك.

   

6. انقر على حفظ. ستستردّ حزمة تطوير البرامج (SDK) عنوان URL لحاوية الخادم المعدَّل وتوجّه بيانات القياس إليه.

القيود المعروفة

• بالنسبة إلى تطبيقات Android:

  • تعتمد عمليات الشراء داخل التطبيق التي يتم تسجيلها تلقائيًا على التكامل مع Google Play من جهة الخادم ولن يتم إرسالها إلى حاوية الخادم.
  • لن يتم تسجيل حدث app_remove على Android.

• لا يزال من الضروري ربط مصادر بيانات تطبيقك في "إحصاءات Google" بحسابك على "إعلانات Google" لضمان استيراد بيانات حزمة تطوير البرامج (SDK) والإحالات الناجحة إلى "إعلانات Google". لا توفّر ميزة "وضع العلامات من جهة الخادم" أي تكامل أساسي بين حزمة تطوير البرامج (SDK) و"إعلانات Google".

ملاحظة: تم تصميم حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google لبرنامج Firebase" وتحسينها لإرسال البيانات إلى "إحصاءات Google‏ 4". يمكن بعد ذلك ربط "إحصاءات Google‏ 4" بـ "إعلانات Google" لإعداد تقارير الإحالات الناجحة وإنشاء الشرائح وتحسين الحملات ووضع النماذج. ويشمل ذلك ميزة وضع علامات التتبُّع من جانب الخادم للتطبيقات، ونشجّع العملاء على الاستفادة من التكامل بين إحصاءات Google ووضع علامات التتبُّع من جانب الخادم في Google Tag Manager.

واجهة برمجة التطبيقات

يمكنك استخدام Tag Manager REST API للوصول إلى بيانات إعدادات "إدارة العلامات من Google". لمزيد من المعلومات عن واجهة برمجة التطبيقات:

• راجِع دليل المطوّر لمعرفة كيفية استخدام واجهة برمجة التطبيقات.
• راجِع مرجع Tag Manager API للتعرّف على موارد "إدارة العلامات من Google" والعمليات المتاحة.