تكامل 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 و Web.

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

يتم دفق أحداث دورة حياة الإشعارات والبريد الإلكتروني والرسائل القصيرة المحددة إلى 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 الخاصة بي؟

لا. بيانات اعتماد حساب الخدمة (Service Account) التي تقوم بتحميلها تفوض 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 لإشعارات الدفع في هذا التكامل. لا تتوفر خطوة مخصصة لنقرة الدفع. البريد الإلكتروني والرسائل القصيرة لها أحداث دورة حياتها الخاصة.