تكامل Google Analytics

تحتاج إلى مساعدة المطور

ستحتاج إلى مساعدة من فريق التطوير الخاص بك لإعداد التكامل. يرجى مشاركة هذا الدليل معهم.

أرسل معرّف المستخدم نفسه (user ID) إلى Google Analytics 4 وPushwoosh، وستتعامل الأداتان مع الشخص الذي يزور موقعك الإلكتروني أو تطبيقك على أنه مستخدم واحد. بعد ذلك يمكنك مراسلة المستخدمين الذين تحلّلهم في Google Analytics، وإنشاء شرائح Pushwoosh من بيانات Google Analytics.

نظرة عامة على التكامل

نوع التكامل

الوجهة: تتحوّل جماهير Google Analytics وتصدير Google Analytics إلى BigQuery إلى شرائح في Pushwoosh. ينتقل معرّف المستخدم من موقعك الإلكتروني أو تطبيقك إلى كل أداة على حدة. لا يرسل Pushwoosh أي بيانات إلى Google Analytics.

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

• حساب Pushwoosh وPushwoosh SDK (Web أو Android أو iOS) على الموقع الإلكتروني أو في التطبيق الذي ترسل منه معرّف المستخدم.
• موقع Google Analytics 4 يجمع البيانات من الموقع الإلكتروني أو التطبيق نفسه.

لاستيراد جماهير Google Analytics، تحتاج أيضًا إلى:

• حساب خدمة في Google Cloud ومفتاح JSON الخاص به. راجع Create and delete service account keys.
• تفعيل Google Analytics Data API وAdmin API في مشروع حساب الخدمة هذا.
• الدور Viewer لحساب الخدمة على موقع Google Analytics. راجع Add, edit, and delete users and user groups.

للاستعلام عن تصدير BigQuery، تحتاج أيضًا إلى:

• ربط موقع Google Analytics 4 بـ BigQuery. راجع Set up BigQuery Export.
• مفتاح حساب خدمة يملك الدورين BigQuery Data Viewer وBigQuery Job User. راجع BigQuery roles and permissions.

كيف يعمل التكامل؟

يطابق Pushwoosh المستخدمين حسب معرّفاتهم:

1. يرسل موقعك الإلكتروني أو تطبيقك معرّف المستخدم نفسه إلى Google Analytics وإلى Pushwoosh.
2. يقرأ Pushwoosh معرّفات المستخدمين من جمهور Google Analytics أو من تصدير BigQuery الخاص بك.
3. ينضم المستخدم إلى الشريحة عندما يتطابق معرّفه مع User ID في Pushwoosh.

تتحدّث الشريحة بشكل مختلف حسب المصدر:

• تتحدّث الشريحة المنشأة من جمهور مرة واحدة يوميًا تقريبًا ما دمت تستخدمها.
• تعكس الشريحة المنشأة من BigQuery النشاط حتى اليوم السابق.

إعداد التكامل

يتكوّن الإعداد من جزأين. أولًا، يرسل مطوّروك معرّف المستخدم من موقعك الإلكتروني أو تطبيقك. ثم تنشئ شريحة من بيانات Google Analytics في Control Panel.

1. بالتعاون مع مطوّريك، اختر معرّف المستخدم.
2. يرسله مطوّروك إلى Google Analytics وإلى Pushwoosh من موقعك الإلكتروني أو تطبيقك للجوال.
3. اختياريًا، أنشئ شريحة Pushwoosh من بيانات Google Analytics. يمكنك بعد ذلك استخدامها مثل أي شريحة أخرى.

أرسل معرّف المستخدم إلى Google Analytics وPushwoosh

يتولّى مطوّروك هذا الجزء. شارك معهم الأقسام التالية.

اختر معرّف المستخدم

استخدم معرّفًا يملكه نظامك الخاص بالفعل لكل مستخدم، مثل معرّف الحساب من قاعدة بياناتك. تُرسَل القيمة نفسها إلى Google Analytics بوصفها user ID الخاص به، وإلى Pushwoosh بوصفها User ID.

لا تستخدم معلومات شخصية في معرّف المستخدم

لا تسمح سياسات Google Analytics بالمعلومات الشخصية في user ID. لا تستخدم عنوان بريد إلكتروني أو رقم هاتف أو أي معلومات شخصية أخرى.

عيّن المعرّف في لحظة تسجيل المستخدم للدخول أو التعرّف عليه بطريقة أخرى.

أرسل معرّف المستخدم من موقعك الإلكتروني

مرّر المعرّف إلى Google Analytics في المعامل user_id ضمن علامة Google الخاصة بك. إذا كنت تستخدم Google Tag Manager، فعيّن بدلًا من ذلك الحقل user_id في إعدادات علامة Google. راجع Send user IDs في وثائق Google.

JavaScript

gtag('config', 'G-XXXXXXXXXX', {
  'user_id': 'USER_ID'
});

مرّر المعرّف نفسه إلى Pushwoosh باستخدام Web Push SDK:

JavaScript

Pushwoosh.push((api) => {
  api.registerUser('USER_ID');
});

أرسل معرّف المستخدم من تطبيقك للجوال

ترسل تطبيقات الجوال البيانات إلى Google Analytics 4 عبر Firebase. عيّن المعرّف باستخدام setUserId من Firebase Analytics (راجع Set a user ID في وثائق Firebase)، وعيّن القيمة نفسها باستخدام Pushwoosh SDK.

Android

Java

FirebaseAnalytics.getInstance(context).setUserId("USER_ID");
Pushwoosh.getInstance().setUserId("USER_ID");

iOS

Swift

Analytics.setUserID("USER_ID")
Pushwoosh.sharedInstance().setUserId("USER_ID")

أنشئ شريحة من بيانات Google Analytics

تنفّذ هذا الجزء بنفسك في Control Panel، بعد أن يرسل مطوّروك معرّف المستخدم. يمكن لـ Pushwoosh تحويل بيانات Google Analytics إلى شريحة بطريقتين، كلتاهما من خلال الشرائح الخارجية:

• استيراد جمهور Google Analytics: اختر جمهورًا أنشأته بالفعل في Google Analytics. لا حاجة إلى SQL ولا إلى BigQuery.
• الاستعلام عن تصدير BigQuery: اكتب استعلام SQL الخاص بك على الأحداث الأولية التي يصدّرها Google Analytics إلى BigQuery، للشروط التي لا يستطيع الجمهور التعبير عنها.

استيراد جمهور Google Analytics

اطلب من المطوّر أو من مسؤول Google Cloud تنفيذ هذه الخطوات في Google Cloud وGoogle Analytics:

1. جهّز حساب خدمة ومفتاح JSON الخاص به. راجع Create and delete service account keys في وثائق Google Cloud.
2. في مشروع Google Cloud الخاص بحساب الخدمة، فعّل Google Analytics Data API وGoogle Analytics Admin API.
3. في Google Analytics، انتقل إلى Admin ← Property access management وأضف البريد الإلكتروني لحساب الخدمة بالدور Viewer. الدور الممنوح في Google Cloud IAM لا يمنح الوصول إلى Google Analytics.

ثم نفّذ هذه الخطوات في Control Panel:

1. أنشئ شريحة خارجية مع تعيين نوع قاعدة البيانات إلى Google Analytics 4 audience.

2. أدخل معرّف موقع GA4. يمكنك العثور عليه في Google Analytics ضمن Admin ← Property details.

3. الصق مفتاح JSON من القائمة الأولى في Service account JSON.

4. انقر على تحميل الجماهير واختر الجمهور.

   

5. انقر على التحقق من الاتصال.

6. انقر على إنشاء.

يحدّث Pushwoosh الشريحة عندما يقرأ الشريحة كاملة، على سبيل المثال عندما ترسل إليها حملة أو Journey أو تحسب حجمها:

• إذا كان عمر البيانات أقل من 24 ساعة، يستخدمها Pushwoosh كما هي، لأن Google Analytics يحدّث عضوية الجمهور مرة واحدة يوميًا تقريبًا.
• إذا كان عمرها أكثر من 24 ساعة، يستخدم Pushwoosh البيانات الحالية ويحدّث الشريحة في الخلفية.
• إذا كان عمرها أكثر من 72 ساعة، ينتظر Pushwoosh حتى يكتمل التحديث.

لا يمكنك تحديث الشريحة أكثر من مرة واحدة يوميًا. إذا لم تُحدَّث منذ أكثر من يوم، احسب حجم الشريحة قبل الإرسال بوقت كافٍ. يؤدي ذلك إلى بدء التحديث في الخلفية، فيستخدم الإرسال بيانات أحدث.

الاستعلام عن تصدير BigQuery

إذا كنت تصدّر بيانات Google Analytics 4 إلى BigQuery، فيمكنك اختيار المستخدمين بأي شرط SQL على أحداثهم، على سبيل المثال كل من أجرى عملية شراء خلال آخر 30 يومًا.

اطلب من المطوّر أو من مسؤول Google Cloud تنفيذ هذه الخطوات في Google Cloud وGoogle Analytics:

1. اربط موقع Google Analytics 4 الخاص بك بمشروع BigQuery وفعّل التصدير اليومي. اتبع Set up BigQuery Export في وثائق Google.

   بعد ذلك يكتب Google Analytics أحداث كل يوم في جدول باسم events_YYYYMMDD ضمن مجموعة بيانات باسم analytics_<property ID>. يوجد معرّف المستخدم الذي أرسلته في الأقسام السابقة في العمود user_id.

2. أنشئ مفتاح حساب خدمة يملك الدورين BigQuery Data Viewer وBigQuery Job User. يشغّل التحقق من الاتصال والتحقق من الاستعلام مهمة استعلام تجريبية في مشروعك، لذلك يفشلان بدون BigQuery Job User.

ثم أنشئ في Control Panel شريحة خارجية مع تعيين نوع قاعدة البيانات إلى Google BigQuery. أدخل مفتاح حساب الخدمة للاتصال واستعلامًا يُرجع معرّفات المستخدمين الذين تريدهم.

على سبيل المثال، يُرجع هذا الاستعلام المستخدمين الذين أجروا عملية شراء خلال آخر 30 يومًا. استبدل my-project بمعرّف مشروع Google Cloud الخاص بك وanalytics_123456789 باسم مجموعة البيانات الخاصة بك:

SQL

SELECT DISTINCT user_id
FROM `my-project.analytics_123456789.events_*`
WHERE event_name = 'purchase'
  AND user_id IS NOT NULL
  AND _TABLE_SUFFIX >= FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))

تعكس الشريحة النشاط حتى اليوم السابق، لأن Google Analytics يصدّر البيانات مرة واحدة يوميًا.

كيف تعرف أن التكامل يعمل؟

• معرّف المستخدم: في Pushwoosh، انتقل إلى الجمهور ← مستكشف المستخدمين وابحث حسب User ID عن معرّف أرسلته إلى Google Analytics. إذا عُثر على المستخدم، فإن الأداتين تملكان المعرّف نفسه.
• الشرائح: في الجمهور ← الشرائح الخارجية، تكون حالة الشريحة صالحة. لمعرفة عدد المستخدمين المطابقين، تحقّق من حجم الشريحة.

استكشاف الأخطاء وإصلاحها

يظهر خطأ عند تحميل الجماهير أو التحقق من الاتصال

يسجّل الزرّان الدخول باستخدام مفتاح حساب الخدمة ويقرآن قائمة جماهير الموقع، ويعرض النموذج الخطأ الذي يُرجعه Google Analytics. تحقّق مما يلي:

• Service account JSON هو مفتاح حساب خدمة. تُرفض ملفات بيانات اعتماد Google الأخرى.
• معرّف موقع GA4 هو الرقم الموجود في Admin ← Property details.
• يملك حساب الخدمة الدور Viewer في Google Analytics ضمن Admin ← Property access management. الدور الممنوح في Google Cloud IAM لا يُحتسب.
• Google Analytics Admin API مفعّلة في مشروع Google Cloud الخاص بحساب الخدمة.

قائمة الجماهير فارغة

لا يحتوي الموقع على أي جماهير بعد. أنشئ جمهورًا في Google Analytics ضمن Admin ← Audiences، ثم انقر على تحميل الجماهير مرة أخرى.

لا يدخل أحد إلى الشريحة

• تأكّد من تفعيل Google Analytics Data API. لا يختبرها التحقق من الاتصال، لكن Pushwoosh يحتاج إليها لقراءة أعضاء الجمهور.
• تأكّد من أن موقعك الإلكتروني أو تطبيقك يرسل معرّف المستخدم نفسه إلى Google Analytics وإلى Pushwoosh. لا يدخل الشريحة إلا المستخدمون الذين يتطابق user ID الخاص بهم في Google Analytics مع User ID في Pushwoosh. أما المستخدمون الذين لا يعرفهم Google Analytics إلا من خلال client ID المجهول، فلا يدخلونها.

يفشل التحقق من الاتصال أو التحقق من الاستعلام في BigQuery

يشغّل كلا الفحصين مهمة استعلام تجريبية في مشروع Google Cloud الخاص بك دون قراءة أي بيانات. تحقّق مما يلي:

• يملك حساب الخدمة الدورين BigQuery Data Viewer وBigQuery Job User معًا. بدون BigQuery Job User لا يمكن تشغيل أي من الفحصين.
• يستخدم الاستعلام معرّف مشروعك واسم مجموعة البيانات analytics_<property ID>، وقد كتب التصدير بالفعل جدولًا يوميًا واحدًا على الأقل من نوع events_YYYYMMDD.
• يُرجع الاستعلام عمودًا واحدًا بالضبط باسم user_id.