تكامل Google BigQuery

مطلوب مساعدة المطور

ستحتاج إلى مساعدة من فريق التطوير أو مسؤول Google Cloud لإعداد التكامل. يرجى مشاركة هذا الدليل معهم.

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

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

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

جهز ما يلي قبل فتح إعداد التكامل.

1. استخدم مشروع Google Cloud مع تمكين الفوترة. يتم دعم أرصدة النسخة التجريبية المجانية. BigQuery Sandbox ليس كافيًا لأن Storage Write API يتطلب الفوترة.

2. تأكد من أن لديك حساب Pushwoosh مدفوع.

التسعير

أنت تدفع لـ Google مباشرة مقابل استخدام BigQuery. لا تفرض Pushwoosh رسومًا على التكامل نفسه.

للاطلاع على الأسعار الحالية، والمستويات المجانية، والتفاصيل الإقليمية، راجع تسعير BigQuery.

يمكن أن تشمل التكاليف:

• استيعاب البيانات: تقوم Pushwoosh بدفق الأحداث باستخدام BigQuery Storage Write API.
• التخزين: يخزن BigQuery الصفوف المكتوبة في جدول الوجهة الخاص بك.
• الاستعلامات: يفرض BigQuery رسومًا على الاستعلامات بناءً على نموذج التسعير الذي اخترته.

نوع التكامل

المصدر: يتم إرسال البيانات من Pushwoosh إلى مجموعة بيانات BigQuery الخاصة بك.

المنصات المدعومة

تقوم Pushwoosh بدفق الأحداث من منصات iOS، Android، Huawei، Chrome، Safari، Firefox، والويب.

الكيانات المتزامنة

يتم دفق أحداث دورة حياة الإشعارات الفورية والبريد الإلكتروني والرسائل القصيرة المحددة إلى BigQuery. تكتب Pushwoosh صفًا واحدًا لكل حدث محدد في جدول الوجهة.

حالات الاستخدام

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

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

بعد حفظ التكوين، تبدأ Pushwoosh في دفق أحداث الرسائل المحددة إلى جدول BigQuery الخاص بك في الوقت الفعلي تقريبًا. لكل حدث رسالة يتدفق عبر Pushwoosh، يتحقق النظام مما إذا كان نوع الحدث محددًا في تكوينك.

إذا كان كذلك، تضيف Pushwoosh صفًا جديدًا إلى جدول الوجهة الخاص بك. إذا لم يكن الجدول موجودًا بعد، تقوم Pushwoosh بإنشائه تلقائيًا باستخدام المخطط الموضح أدناه. تظهر الأحداث عادةً في BigQuery في غضون 30 ثانية من معالجتها في Pushwoosh.

إعداد التكامل في Google Cloud

اختر مشروع Google Cloud

سجّل الدخول إلى Google Cloud Console، ثم اختر أو أنشئ المشروع الذي سيمتلك مجموعة بيانات BigQuery.

نصيحة

لاحظ معرف المشروع (Project ID). استخدم المعرف القصير، على سبيل المثال my-company-12345، وليس اسم المشروع القابل للقراءة.

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

في Google Cloud Console، انتقل إلى APIs & Services → Library وقم بتمكين واجهات برمجة التطبيقات هذه:

• BigQuery API
• BigQuery Storage API

تستخدم Pushwoosh واجهات برمجة التطبيقات هذه لإنشاء جدول الوجهة ودفق الأحداث إلى BigQuery.

إنشاء حساب خدمة (Service Account)

تستخدم Pushwoosh حساب الخدمة لكتابة الأحداث إلى مجموعة بيانات BigQuery الخاصة بك.

1. انتقل إلى IAM & Admin → Service Accounts.

2. انقر على Create service account.

3. في Service account name، أدخل اسمًا، على سبيل المثال، pushwoosh-bigquery.

   يقوم Google Cloud تلقائيًا بإنشاء Service account ID من الاسم.

   

4. انقر على Create and continue.

منح أدوار IAM

1. امنح حساب الخدمة أدوار IAM التالية:

   • BigQuery Data Editor: يسمح لـ Pushwoosh بإنشاء الجدول وإلحاق الصفوف.
   • BigQuery User: يسمح لـ Pushwoosh باستخدام Storage Write API.
   

ملاحظة

يمكنك إرفاق الأدوار على مستوى المشروع أو على مستوى مجموعة البيانات. الوصول على مستوى المشروع هو الأسهل في الإعداد. الوصول على مستوى مجموعة البيانات أكثر تقييدًا ويوصى به للإنتاج.

2. انقر على Continue.

3. انقر على Done.

إنشاء مفتاح JSON

تستخدم Pushwoosh مفتاح JSON للمصادقة كحساب خدمة.

1. افتح حساب الخدمة الذي أنشأته.

2. انتقل إلى Keys → Add key → Create new key.

3. حدد JSON.

يقوم Google Cloud بتنزيل ملف مفتاح JSON إلى جهاز الكمبيوتر الخاص بك.

تنبيه

حافظ على ملف مفتاح JSON آمنًا. يمكن لأي شخص لديه هذا الملف الكتابة إلى مشروع BigQuery الخاص بك. لا تقم بإضافته إلى git أو مشاركته عبر الدردشة. تقوم Pushwoosh بتخزين المفتاح مشفرًا في حالة السكون ولا تعرضه من خلال واجهة المستخدم بعد التحميل.

إنشاء مجموعة بيانات (dataset)

مجموعة البيانات هي المكان الذي تخزن فيه Pushwoosh جدول الأحداث المتدفقة.

1. في Google Cloud Console، افتح BigQuery.

2. في Explorer، حدد المشروع الذي أعددته للتكامل.

3. انقر على Create dataset.

4. في Dataset ID، أدخل معرف مجموعة بيانات، على سبيل المثال pushwoosh_data.

5. في Data location، حدد منطقة مجموعة البيانات.

6. انقر على Create dataset.

تكوين التكامل في Pushwoosh

1. في حساب Pushwoosh الخاص بك، انتقل إلى Settings → 3rd Party Integrations للتطبيق الذي تريد توصيله.

2. ابحث عن Google BigQuery في قائمة الخدمات المتاحة وانقر على Configure.

3. املأ حقول التكوين.

• GCP Project ID: أدخل معرف المشروع من Google Cloud، على سبيل المثال my-company-12345.
• Service Account JSON: الصق المحتويات الكاملة لملف مفتاح JSON الذي قمت بتنزيله من Google Cloud.
• Dataset ID: بمجرد ملء GCP Project ID و Service Account JSON، تجلب Pushwoosh مجموعات البيانات التي يمكن لحساب الخدمة الخاص بك الوصول إليها. حدد مجموعة بيانات الوجهة. إذا كانت القائمة المنسدلة فارغة، تحقق من أن حساب الخدمة لديه حق الوصول وأن مجموعة البيانات موجودة في المشروع الذي حددته.
• Dataset region: حدد منطقة مجموعة بيانات BigQuery الخاصة بك.
• Table name: اتركه فارغًا لاستخدام الجدول الافتراضي pushwoosh_events. تقوم Pushwoosh بإنشاء الجدول بالمخطط الموضح أدناه.
• Events: حدد الأحداث التي تريد دفقها. يمكنك تغيير هذه القائمة لاحقًا.
• Stream events to BigQuery: قم بتمكين هذا المفتاح. قم بإيقاف تشغيله لإيقاف الدفق مؤقتًا دون حذف التكوين.

4. انقر على Test connection.

تقوم Pushwoosh بالتحقق من صحة بيانات الاعتماد مقابل BigQuery دون كتابة بيانات.

قد ترى إحدى حالات الاتصال التالية:

• Connection successful: بيانات الاعتماد تعمل ويمكن لحساب الخدمة الوصول إلى مجموعة البيانات.
• auth_failed: مفتاح JSON غير صالح أو تم إبطاله.
• dataset_not_found: معرف مجموعة البيانات غير صحيح أو لا يمكن لحساب الخدمة الوصول إليه.
• missing_permission: حساب الخدمة يفتقد أحد الأدوار المطلوبة.

5. انقر على Apply.

تحفظ Pushwoosh التكوين وتبدأ في استخدامه في غضون 30 ثانية تقريبًا. بعد ذلك، تبدأ الأحداث المحددة في التدفق إلى BigQuery.

التحقق من التكامل

1. أرسل إشعارًا فوريًا تجريبيًا، أو قم بتشغيل رسالة أخرى تنتج أحد أنواع الأحداث التي حددتها.

2. انتظر حوالي 30 ثانية.

3. افتح BigQuery Studio.

4. انتقل إلى مشروعك، ثم افتح مجموعة البيانات وجدول الوجهة الذي قمت بتكوينه. إذا تركت Table name فارغًا، افتح pushwoosh_events.

5. انقر على Preview.

يجب أن ترى صف الحدث في الجدول.

مخطط الجدول

تكتب Pushwoosh كل حدث محدد كصف منفصل في جدول الوجهة. لجعل الاستعلامات أسرع وأسهل في التصفية، يتم تقسيم الجدول حسب اليوم باستخدام timestamp وتجميعه حسب app_id و event_kind.

اسم الحقل	النوع	الوصف
event_kind	STRING	نوع حدث Pushwoosh، على سبيل المثال Push Sent أو Email Opened.
message_id	STRING	رمز رسالة Pushwoosh، مثل معرف الحملة أو الرسالة.
device_id	STRING	معرف جهاز Pushwoosh (HWID) الذي أنتج الحدث.
user_id	STRING	معرف المستخدم الخارجي الخاص بك إذا كان معروفًا. فارغ للأجهزة المجهولة.
timestamp	TIMESTAMP	وقت الحدث بالتوقيت العالمي المنسق (UTC).
app_id	STRING	رمز تطبيق Pushwoosh.
platform	STRING	المنصة المصدر، على سبيل المثال ios، android، أو web.
properties	JSON	حقول أحداث إضافية. استخدم JSON_VALUE للاستعلام عن الحقول، كما هو موضح أدناه.

خصائص الاستعلام

يخزن عمود properties حقول أحداث إضافية بتنسيق JSON. استخدم JSON_VALUE لاستخراج الحقول الفردية في استعلاماتك.

على سبيل المثال، لمعرفة الحملات التي أدت إلى أكبر عدد من الفتحات خلال الأيام السبعة الماضية، انقر على + لإنشاء استعلام جديد، والصق كود SQL أدناه، وانقر على Run.

SELECT
  event_kind,
  JSON_VALUE(properties, '$.campaign_id') AS campaign_id,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE event_kind = 'Push Opened'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY 1, 2
ORDER BY events DESC

لمراجعة أعداد الأحداث للساعة الأخيرة، قم بتشغيل هذا الاستعلام:

SELECT
  event_kind,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
GROUP BY event_kind
ORDER BY events DESC

تحديث التكامل

تدوير مفتاح حساب الخدمة

1. في Google Cloud Console، انتقل إلى IAM & Admin → Service Accounts.

2. افتح حساب الخدمة الخاص بك.

3. انتقل إلى Keys وأنشئ مفتاح JSON جديدًا.

4. احتفظ بالمفتاح القديم نشطًا حتى تتأكد من أن المفتاح الجديد يعمل.

5. في Pushwoosh، افتح نافذة تكوين Google BigQuery.

6. الصق JSON الجديد في Service Account JSON.

7. انقر على Apply.

تقوم Pushwoosh بالتحقق من صحة المفتاح الجديد، وتستبدل بيانات الاعتماد المخزنة، وتبدأ في استخدامه بعد إعادة تحميل التكوين التالية، والتي تستغرق حوالي 30 ثانية.

بعد التأكد من أن الأحداث لا تزال تتدفق، احذف المفتاح القديم في Google Cloud Console.

تغيير مجموعة بيانات أو جدول الوجهة

1. في Pushwoosh، انتقل إلى Settings → 3rd Party Integrations.

2. افتح إعدادات Google BigQuery.

3. حدد مجموعة بيانات مختلفة أو أدخل اسم جدول جديد.

4. انقر على Apply.

تعيد Pushwoosh فتح الدفق مع الوجهة الجديدة في غضون 30 ثانية تقريبًا. تبقى الصفوف المكتوبة بالفعل في الجدول القديم. لا تقوم Pushwoosh بملء البيانات التاريخية بأثر رجعي.

للحفاظ على مفتاح حساب الخدمة المخزن دون تغيير عند تحديث الإعدادات الأخرى، اترك Service Account JSON فارغًا قبل النقر على Apply.

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

المشكلة	ما يجب التحقق منه
فشل اختبار الاتصال مع auth_failed	ملف JSON لحساب الخدمة مشوه أو تم إبطال المفتاح في Google Cloud. أنشئ مفتاحًا جديدًا والصق ملف JSON الكامل مرة أخرى. يبدأ الملف بـ {، وينتهي بـ }، ويحتوي على كتلة private_key.
فشل اختبار الاتصال مع dataset_not_found	معرف مجموعة البيانات (Dataset ID) مكتوب بشكل خاطئ أو غير موجود في المشروع الذي حددته. معرفات مجموعات البيانات حساسة لحالة الأحرف. حدد مجموعة البيانات من القائمة المنسدلة لتجنب الأخطاء الإملائية.
فشل اختبار الاتصال مع missing_permission	حساب الخدمة يفتقد BigQuery Data Editor أو BigQuery User. امنح كلا الدورين على مستوى المشروع، أو امنحهما على مستوى مجموعة البيانات للوصول الأكثر تقييدًا.
نجح اختبار الاتصال، ولكن لا تظهر أي صفوف في BigQuery	انتظر 30 ثانية على الأقل. تحقق من أن نوع الحدث الذي ترسله محدد في Events. على سبيل المثال، إذا تم تحديد Push Opened فقط ولم يفتح أحد الإشعار، فلن تظهر أي صفوف.
يبدو التكوين صحيحًا، لكن النافذة تظهر حقولًا فارغة	أعد تحميل الصفحة. يتم جلب التكوين عند كل فتح للنافذة ويتم تخزينه مؤقتًا لمدة 30 ثانية بواسطة الخدمة الأساسية. إذا قمت للتو بحفظ الإعدادات، انتظر لحظة وافتح النافذة مرة أخرى.

ملاحظة

تسجل Pushwoosh Push Sent، و Email Sent، و SMS Sent بغض النظر عن حالة التسليم حتى تتطابق مجاميع BigQuery مع إحصائيات Pushwoosh الأساسية. بالنسبة لـ Delivered، و Opened، و Bounced، و Unsubscribed، تسجل Pushwoosh الأحداث الناجحة فقط.

الأسئلة الشائعة

هل يمكنني استخدام حساب Google Cloud مجاني؟

نعم، طالما أن الفوترة ممكّنة في المشروع. أرصدة النسخة التجريبية المجانية كافية لتشغيل هذا التكامل بأحجام نموذجية طوال فترة التجربة. BigQuery Sandbox بدون فوترة لن يعمل لأن Storage Write API يتطلب الفوترة.

هل ترى Pushwoosh بيانات BigQuery الخاصة بي؟

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

هل يمكنني التصدير إلى مجموعات بيانات BigQuery متعددة؟

يتم دعم وجهة واحدة لكل تطبيق. إذا كنت بحاجة إلى نفس الأحداث في مجموعتي بيانات، فقم بإعداد استعلام مجدول في BigQuery في مشروعك لنسخ البيانات من pushwoosh_events إلى جدول آخر.

هل يمكنني تغيير مخطط الجدول؟

المخطط ثابت لجميع العملاء. إذا كنت بحاجة إلى أعمدة إضافية، فاستخرجها من properties JSON في طرق العرض الخاصة بك أو الاستعلامات المجدولة.

ماذا يحدث إذا قمت بتعطيل التكامل مؤقتًا؟

قم بإيقاف تشغيل Stream events to BigQuery وانقر على Apply. تتوقف Pushwoosh عن إلحاق الأحداث لهذا التطبيق في غضون 30 ثانية تقريبًا.

الأحداث التي يتم إنتاجها أثناء إيقاف التكامل لا يتم تخزينها مؤقتًا أو ملؤها بأثر رجعي عند إعادة تشغيله. تحتفظ Pushwoosh بالتكوين، بما في ذلك بيانات الاعتماد ومجموعة البيانات واختيار الأحداث.

كيف يمكنني حذف التكامل بالكامل؟

اتصل بـ support@pushwoosh.com لحذف تكوين التكامل. تبقى مجموعة البيانات والصفوف المكتوبة بالفعل في BigQuery في حساب Google Cloud الخاص بك.

هل هناك ضمانات للتسليم؟

يستخدم التكامل التسليم مرة واحدة على الأقل. في ظل التشغيل العادي، تكون التكرارات نادرة. يمكن أن تؤدي إعادة تشغيل العملية بين الإلحاق والتثبيت إلى إنتاج عدد قليل من الصفوف المكررة. قم بإزالة التكرارات في SQL إذا كان خط الأنابيب النهائي الخاص بك يتطلب نتائج مرة واحدة بالضبط.

لماذا لا يوجد حدث Push Clicked؟

تعرض Pushwoosh حاليًا Push Sent، و Push Delivered، و Push Opened للإشعارات الفورية في هذا التكامل. خطوة نقر مخصصة للإشعارات الفورية غير متاحة. البريد الإلكتروني والرسائل القصيرة لها أحداث دورة حياتها الخاصة.