موصل PostHog
اربط PostHog بـ Brevo من خلال Tajo لمزامنة بيانات تحليلات المنتج، وأحداث سلوك المستخدم، وعضوية الفئات من أجل حملات تسويقية قائمة على البيانات وتفاعل شخصي مع العملاء.
نظرة عامة
| الخاصية | القيمة |
|---|---|
| المنصة | PostHog |
| الفئة | تحليلات المنتج (مخصص) |
| تعقيد الإعداد | متوسط |
| تكامل رسمي | لا |
| البيانات المُزامَنة | أحداث، أشخاص، علامات ميزات، فئات |
| طريقة المصادقة | مفتاح API شخصي / رمز المشروع |
الميزات
- مزامنة الأحداث - إعادة توجيه أحداث تحليلات PostHog إلى Brevo للاستهداف السلوكي
- مزامنة ملفات الأشخاص - مزامنة خصائص أشخاص PostHog مع سمات جهات اتصال Brevo
- التقسيم القائم على الفئات - تعيين فئات PostHog إلى قوائم جهات اتصال Brevo
- مزامنة علامات الميزات - تقسيم جهات الاتصال حسب علامات الميزات المُفعّلة
- بيانات القُمع - استخدام بيانات قُمع التحويل لإعادة المشاركة المستهدفة
- بيانات وصفية لإعادة تشغيل الجلسة - إثراء جهات الاتصال بمقاييس تفاعل الجلسة
المتطلبات الأساسية
قبل البدء، تأكد من توفر ما يلي:
- حساب PostHog (Cloud أو مستضاف ذاتيًا)
- مفتاح API شخصي من إعدادات PostHog
- مفتاح API الخاص بمشروعك (الرمز) من إعدادات المشروع
- حساب Brevo مع وصول إلى API
- حساب Tajo مع صلاحيات الموصلات
المصادقة
مفتاح API شخصي (نقاط النهاية الخاصة)
# Generate at https://app.posthog.com/settings/user-api-keysexport POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_keyexport POSTHOG_PROJECT_TOKEN=phc_your_project_tokenexport POSTHOG_HOST=https://us.posthog.com # or https://eu.posthog.comexport TAJO_API_KEY=your_tajo_api_keyexport BREVO_API_KEY=your_brevo_api_key// Private API endpoints use Bearer authenticationconst headers = { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`, 'Content-Type': 'application/json'};
// Public endpoints use the project tokenconst publicHeaders = { 'Content-Type': 'application/json'};// Token is passed in the request body for public endpointsأمان مفتاح API
يوفر مفتاح API الشخصي وصولاً كاملاً إلى الحساب. لا تكشف عنه أبدًا في الكود من جانب العميل. استخدم مفتاح API الخاص بالمشروع (الرمز) لنقاط النهاية العامة مثل التقاط الأحداث وتقييم علامات الميزات.
الإعداد
الإعداد الأساسي
connectors: posthog: enabled: true host: "${POSTHOG_HOST}" personal_api_key: "${POSTHOG_PERSONAL_API_KEY}" project_token: "${POSTHOG_PROJECT_TOKEN}" project_id: "12345"
sync: persons: true events: true cohorts: true feature_flags: true schedule: "0 */3 * * *" # Every 3 hours
event_filters: - "$pageview" - "purchase_completed" - "signup_completed" - "feature_used"
lists: all_users: 25 active_users: 26 power_users: 27تعيين الحقول
field_mapping: email: email $name: FIRSTNAME $browser: BROWSER $os: OS $initial_referrer: REFERRAL_SOURCE total_events: EVENT_COUNT last_seen: LAST_ACTIVE_DATE signup_date: SIGNUP_DATE plan: SUBSCRIPTION_PLAN company: COMPANY cohort_names: POSTHOG_COHORTSنقاط نهاية واجهة البرمجة
| نقطة النهاية | الطريقة | الوصف |
|---|---|---|
{host}/api/projects/{id}/persons/ | GET | سرد الأشخاص |
{host}/api/projects/{id}/events/ | GET | سرد الأحداث |
{host}/api/projects/{id}/cohorts/ | GET | سرد الفئات |
{host}/api/projects/{id}/feature_flags/ | GET | سرد علامات الميزات |
{host}/api/projects/{id}/feature_flags/evaluation/ | POST | تقييم العلامات |
{host}/api/projects/{id}/insights/ | GET | سرد الرؤى المحفوظة |
{host}/api/projects/{id}/query/ | POST | تشغيل استعلامات HogQL |
{host}/i/v0/e | POST | التقاط الأحداث (عام) |
{host}/decide/?v=3 | POST | قرارات علامات الميزات (عام) |
أمثلة على الكود
تهيئة الموصل
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
await tajo.connectors.connect('posthog', { host: process.env.POSTHOG_HOST, personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY, projectToken: process.env.POSTHOG_PROJECT_TOKEN, projectId: '12345'});مزامنة الأشخاص مع Brevo
// التقسيم عبر صفحات أشخاص PostHoglet nextUrl = `${posthogHost}/api/projects/${projectId}/persons/?` + new URLSearchParams({ limit: '100' });
while (nextUrl) { const response = await fetch(nextUrl, { headers: { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}` } });
const data = await response.json();
for (const person of data.results) { const email = person.properties.$email || person.properties.email; if (!email) continue;
await tajo.contacts.sync({ email, attributes: { FIRSTNAME: person.properties.$name || person.properties.name, LAST_ACTIVE_DATE: person.properties.$last_seen, SIGNUP_DATE: person.created_at, EVENT_COUNT: person.properties.$event_count, BROWSER: person.properties.$browser, OS: person.properties.$os, REFERRAL_SOURCE: person.properties.$initial_referrer }, listIds: [25] }); }
nextUrl = data.next;}مزامنة الفئات كقوائم Brevo
// الحصول على فئات PostHog ومزامنة أعضائها مع قوائم Brevoconst cohortsResponse = await fetch( `${posthogHost}/api/projects/${projectId}/cohorts/`, { headers: { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}` } });
const { results: cohorts } = await cohortsResponse.json();
for (const cohort of cohorts) { // الحصول على الأشخاص في هذه الفئة const personsResponse = await fetch( `${posthogHost}/api/projects/${projectId}/cohorts/${cohort.id}/persons/`, { headers: { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}` } } );
const { results: persons } = await personsResponse.json();
for (const person of persons) { const email = person.properties.$email || person.properties.email; if (email) { await tajo.contacts.update(email, { attributes: { POSTHOG_COHORTS: cohort.name } }); } }}تشغيل استعلامات HogQL للتحليلات
// استخدام HogQL للاستعلام عن بيانات التحليلاتconst queryResponse = await fetch( `${posthogHost}/api/projects/${projectId}/query/`, { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: { kind: 'HogQLQuery', query: ` SELECT properties.$email AS email, count() AS event_count, max(timestamp) AS last_event FROM events WHERE event = 'purchase_completed' AND timestamp > now() - interval 30 day GROUP BY email HAVING event_count > 3 ORDER BY event_count DESC LIMIT 1000 ` } }) });
const queryResult = await queryResponse.json();
for (const row of queryResult.results) { await tajo.contacts.update(row[0], { attributes: { PURCHASE_COUNT_30D: row[1], LAST_PURCHASE: row[2] } });}حدود المعدل
| فئة نقطة النهاية | الحد | ملاحظات |
|---|---|---|
| نقاط نهاية التحليلات | 240/دقيقة، 1,200/ساعة | GET للأشخاص، الأحداث، الرؤى |
| نقطة نهاية الاستعلام | 2,400/ساعة | HogQL والاستعلامات المخصصة |
| تقييم علامات الميزات | 600/دقيقة | نقطة نهاية التقييم المحلي |
| نقاط نهاية CRUD | 480/دقيقة، 4,800/ساعة | عمليات الإنشاء والتحديث والحذف |
| نقاط النهاية العامة (الالتقاط) | غير محدود | التقاط الأحداث، قرارات العلامات |
التصدير بالدفعات
لتصدير بيانات الأحداث على نطاق واسع، استخدم ميزة التصدير بالدفعات في PostHog بدلاً من API. تدعم صادرات الدفعات S3 وBigQuery وSnowflake ووجهات أخرى.
استكشاف الأخطاء وإصلاحها
| المشكلة | السبب | الحل |
|---|---|---|
| 401 Unauthorized | مفتاح API غير صالح | تحقق من مفتاح API الشخصي في الإعدادات |
| 400 Invalid project | معرّف مشروع خاطئ | تحقق من معرّف المشروع في عنوان URL الخاص بـ PostHog |
| قائمة أشخاص فارغة | لا يوجد مستخدمون معرَّفون | تأكد من استدعاء posthog.identify() |
| خصائص مفقودة | الخصائص غير مُعيَّنة | تحقق من استدعاءات $set في SDK العميل |
| خطأ حد المعدل 429 | طلبات كثيرة جدًا | طبّق التراجع، تحقق من ترويسات حد المعدل |
وضع التصحيح
connectors: posthog: debug: true log_level: verbose log_queries: true log_sync: trueأفضل الممارسات
- حدّد هوية المستخدمين - استدعِ
posthog.identify()دائمًا بالبريد الإلكتروني لتمكين مزامنة الأشخاص - استخدم الفئات للتقسيم - استفد من فئات PostHog السلوكية لقوائم Brevo
- جمّع طلبات API - استخدم التقسيم والمعالجة بالدفعات لمجموعات البيانات الكبيرة
- استخدم HogQL للاستعلامات المعقدة - استخرج تحليلات مخصصة باستعلامات شبيهة بـ SQL
- إعداد التصدير بالدفعات - للأحجام الكبيرة من البيانات، فضّل التصدير بالدفعات على استطلاع API
- صفِّ الأحداث ذات الصلة - زامن فقط الأحداث ذات الصلة بالتسويق لتقليل الضوضاء
الأمان
- مفتاح API شخصي - مصادقة Bearer token مقيدة النطاق
- رمز المشروع - رمز عام للعمليات من جانب العميل فقط
- HTTPS فقط - تتطلب جميع نقاط النهاية تشفير TLS
- قائمة IP المسموح بها - متاحة للمثيلات المستضافة ذاتيًا
- تحديد نطاق المفاتيح - إنشاء مفاتيح API بنطاقات صلاحيات محددة
- فحص أسرار GitHub - يتعاون PostHog مع GitHub لاكتشاف المفاتيح المسربة