# تكامل Google BigQuery
يقوم تكامل [Google BigQuery](https://cloud.google.com/bigquery) ببث أحداث رسائل Pushwoosh المحددة إلى مجموعة بيانات BigQuery الخاصة بك. استخدمه لتحليل أحداث دورة حياة الإشعارات الفورية (push) والبريد الإلكتروني والرسائل القصيرة (SMS) في BigQuery، أو بناء تقارير مخصصة، أو ربط البيانات بسير عمل التحليلات النهائية لديك.
## نظرة عامة على التكامل
### المتطلبات الأساسية
جهز ما يلي قبل أن تبدأ في إعداد التكامل.
1. استخدم مشروع Google Cloud مع تمكين الفوترة. يتم دعم أرصدة Free Trial. لا يكفي BigQuery Sandbox لأن Storage Write API يتطلب الفوترة.
2. تأكد من أن لديك حساب Pushwoosh مدفوع.
### التسعير
أنت تدفع لـ Google مباشرة مقابل استخدام BigQuery. لا تفرض Pushwoosh رسومًا على التكامل نفسه.
للاطلاع على الأسعار الحالية، والمستويات المجانية، والتفاصيل الإقليمية، راجع [تسعير BigQuery](https://cloud.google.com/bigquery/pricing).
يمكن أن تشمل التكاليف ما يلي:
- **استيعاب البيانات:** تقوم Pushwoosh ببث الأحداث باستخدام BigQuery Storage Write API.
- **التخزين:** يقوم BigQuery بتخزين الصفوف المكتوبة في جدول الوجهة الخاص بك.
- **الاستعلامات:** يفرض BigQuery رسومًا على الاستعلامات بناءً على نموذج التسعير الذي اخترته.
### نوع التكامل
**المصدر:** يتم إرسال البيانات من Pushwoosh إلى مجموعة بيانات BigQuery الخاصة بك.
### المنصات المدعومة
تقوم Pushwoosh ببث الأحداث من منصات iOS، وAndroid، وHuawei، وChrome، وSafari، وFirefox، وWeb.
### الكيانات المتزامنة
يتم بث أحداث دورة حياة الإشعارات الفورية (push) والبريد الإلكتروني والرسائل القصيرة (SMS) المحددة إلى BigQuery. تكتب Pushwoosh صفًا واحدًا لكل حدث محدد في جدول الوجهة.
### حالات الاستخدام
* **تحليلات الرسائل شبه الفورية:** تحليل أحداث دورة حياة الإشعارات الفورية (push) والبريد الإلكتروني والرسائل القصيرة (SMS) في BigQuery بعد وقت قصير من معالجتها في Pushwoosh.
* **التقارير المخصصة:** بناء تقارير BigQuery لأنواع الأحداث والتطبيقات والحملات ومعرفات الرسائل المحددة.
* **سير عمل البيانات النهائية:** ربط بيانات أحداث Pushwoosh بسير عمل التحليلات أو التقارير أو معالجة البيانات لديك.
### كيف يعمل التكامل
بعد حفظ التكوين، تبدأ Pushwoosh في بث أحداث الرسائل المحددة إلى جدول BigQuery الخاص بك في وقت شبه فوري.
لكل حدث رسالة يتدفق عبر Pushwoosh، يتحقق النظام مما إذا كان نوع الحدث محددًا في تكوينك.
إذا كان كذلك، تضيف Pushwoosh صفًا جديدًا إلى جدول الوجهة الخاص بك. إذا لم يكن الجدول موجودًا بعد، تقوم Pushwoosh بإنشائه تلقائيًا باستخدام المخطط الموضح أدناه.
تظهر الأحداث عادةً في BigQuery في غضون 30 ثانية من معالجتها في Pushwoosh.
## إعداد التكامل في Google Cloud
### اختر مشروع Google Cloud
سجّل الدخول إلى [Google Cloud Console](https://console.cloud.google.com)، ثم اختر أو أنشئ المشروع الذي سيمتلك مجموعة بيانات BigQuery.
### تمكين واجهات برمجة التطبيقات المطلوبة (APIs)
في 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 إلى جهاز الكمبيوتر الخاص بك.
### إنشاء مجموعة بيانات (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. أرسل إشعارًا فوريًا (push) تجريبيًا، أو قم بتشغيل رسالة أخرى تنتج أحد أنواع الأحداث التي حددتها.
2. انتظر حوالي 30 ثانية.
3. افتح [BigQuery Studio](https://console.cloud.google.com/bigquery).
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**.
```sql
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
```
لمراجعة أعداد الأحداث للساعة الأخيرة، قم بتشغيل هذا الاستعلام:
```sql
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 ثانية بواسطة الخدمة الأساسية. إذا قمت للتو بحفظ الإعدادات، فانتظر لحظة وافتح النافذة مرة أخرى. |
## الأسئلة الشائعة
##### هل يمكنني استخدام حساب Google Cloud مجاني؟
نعم، طالما أن الفوترة ممكّنة في المشروع. أرصدة Free Trial كافية لتشغيل هذا التكامل بأحجام نموذجية طوال فترة التجربة الكاملة. لن يعمل 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](mailto:support@pushwoosh.com) لحذف تكوين التكامل. تظل مجموعة البيانات والصفوف المكتوبة بالفعل في BigQuery في حساب Google Cloud الخاص بك.
##### هل هناك ضمانات للتسليم؟
يستخدم التكامل التسليم مرة واحدة على الأقل (at-least-once delivery). في ظل التشغيل العادي، تكون التكرارات نادرة. يمكن أن تؤدي إعادة تشغيل العملية بين عملية إلحاق وعملية تأكيد إلى إنتاج عدد صغير من الصفوف المكررة. قم بإزالة التكرارات في SQL إذا كان خط الأنابيب النهائي الخاص بك يتطلب نتائج مرة واحدة بالضبط (exactly-once).
##### لماذا لا يوجد حدث Push Clicked؟
تعرض Pushwoosh حاليًا **Push Sent**، و**Push Delivered**، و**Push Opened** للإشعارات الفورية في هذا التكامل. خطوة نقر مخصصة للإشعارات الفورية غير متاحة. البريد الإلكتروني والرسائل القصيرة لها أحداث دورة حياتها الخاصة.
### تمكين واجهات برمجة التطبيقات المطلوبة (APIs)
في 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 إلى جهاز الكمبيوتر الخاص بك.
### إنشاء مجموعة بيانات (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. أرسل إشعارًا فوريًا (push) تجريبيًا، أو قم بتشغيل رسالة أخرى تنتج أحد أنواع الأحداث التي حددتها.
2. انتظر حوالي 30 ثانية.
3. افتح [BigQuery Studio](https://console.cloud.google.com/bigquery).
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**.
```sql
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
```
لمراجعة أعداد الأحداث للساعة الأخيرة، قم بتشغيل هذا الاستعلام:
```sql
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 ثانية بواسطة الخدمة الأساسية. إذا قمت للتو بحفظ الإعدادات، فانتظر لحظة وافتح النافذة مرة أخرى. |
## الأسئلة الشائعة
##### هل يمكنني استخدام حساب Google Cloud مجاني؟
نعم، طالما أن الفوترة ممكّنة في المشروع. أرصدة Free Trial كافية لتشغيل هذا التكامل بأحجام نموذجية طوال فترة التجربة الكاملة. لن يعمل 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](mailto:support@pushwoosh.com) لحذف تكوين التكامل. تظل مجموعة البيانات والصفوف المكتوبة بالفعل في BigQuery في حساب Google Cloud الخاص بك.
##### هل هناك ضمانات للتسليم؟
يستخدم التكامل التسليم مرة واحدة على الأقل (at-least-once delivery). في ظل التشغيل العادي، تكون التكرارات نادرة. يمكن أن تؤدي إعادة تشغيل العملية بين عملية إلحاق وعملية تأكيد إلى إنتاج عدد صغير من الصفوف المكررة. قم بإزالة التكرارات في SQL إذا كان خط الأنابيب النهائي الخاص بك يتطلب نتائج مرة واحدة بالضبط (exactly-once).
##### لماذا لا يوجد حدث Push Clicked؟
تعرض Pushwoosh حاليًا **Push Sent**، و**Push Delivered**، و**Push Opened** للإشعارات الفورية في هذا التكامل. خطوة نقر مخصصة للإشعارات الفورية غير متاحة. البريد الإلكتروني والرسائل القصيرة لها أحداث دورة حياتها الخاصة.