الوجهات
ادفع الجماهير إلى Meta Ads و Google Ads وأنواع webhook مخصصة بنقرة واحدة. البيانات تُخزَّن في KMS envelopes.
3 قنوات
Meta CAPI · Google Ads · Webhook
ثلاثة أنواع وجهات. كلها تشترك في نفس بنية ربط الجمهور + سجل الإرسال + dedup.
Meta CAPI
Meta CAPIادفع email + phone بعد الـ hash إلى Custom Audience. SHA-256 lowercase trim + E.164 — بحسب مواصفات Meta تماماً.
Google Ads Customer Match
Google Adsتدفق OAuth 2.0 + developer_token على مستوى المنصة. Customer Match API لإدارة قوائم المستخدمين المُهَشَة.
Webhook (مخصص)
Custom webhookادفع إلى نظامك الخاص. ترويسة توقيع HMAC-SHA256 + JSON body + دعم retry/dedup.
إعداد Meta CAPI
إعداد خطوة بخطوة
Pixel ID + Access Token + Test Event Code من Facebook Business Manager — 4 خطوات للوصول إلى live.
- 01
تجهيز Pixel + Business Manager
Facebook Business Manager → Events Manager → انسخ Pixel ID. تأكد من امتلاكك صلاحيات إنشاء Custom Audience.
- 02
ولّد System User Access Token
Business Settings → Users → System Users → 'Generate Token' → scopes: ads_management + business_management. انسخ الـ token مرة واحدة.
- 03
أضف البيانات في Gurulu
/app/destinations → 'New Meta CAPI' → Pixel ID + Access Token + (اختياري) Test Event Code. تُخزَّن البيانات في KMS envelope؛ وتُعرض في UI آخر 4 خانات فقط.
- 04
اربط الجمهور + الإرسال
زاوج destination + audience. في أول إرسال، يُنشأ Custom Audience إن لم يكن موجوداً؛ ثم ينطلق الدفع التزايدي الساعي.
// Hash format: lowercase, trim, SHA-256
// E.164 phone: '+901234567890' → sha256 hex
import { createHash } from 'node:crypto';
function hashPii(value: string): string {
return createHash('sha256').update(value.trim().toLowerCase()).digest('hex');
}
// Audience üye listesi push
await fetch('https://graph.facebook.com/v18.0/{pixel_id}/users', {
method: 'POST',
headers: { Authorization: 'Bearer ' + ACCESS_TOKEN },
body: JSON.stringify({
payload: {
schema: ['EMAIL_SHA256', 'PHONE_SHA256'],
data: members.map((m) => [hashPii(m.email), hashPii(m.phone)]),
},
}),
});Google Ads OAuth
تدفق OAuth + developer token
أنشئ OAuth Client في Google Cloud Console وتقدّم للحصول على developer_token — يُفتح وصول Customer Match API.
- 01
Google Cloud Console — OAuth Client
APIs & Services → Credentials → 'Create OAuth Client ID' → Application type: Web. سجّل redirect URI كما هو بالضبط في callback الخاص بـ Gurulu.
- 02
طلب Developer Token
Google Ads → Tools → API Center → تقدّم بطلب Developer Token. قد يستغرق Standard Access 2-3 أيام.
- 03
ابدأ OAuth من Gurulu
/app/destinations → 'New Google Ads' → 'Connect with Google' → شاشة الموافقة → عند callback يُخزَّن refresh_token في KMS envelope.
# OAuth callback URI (Google Cloud Console'a kayıtla):
https://api.gurulu.io/v1/destinations/oauth/google/callback
# Developer token başvurusu — Google Ads API erişimi için
# https://developers.google.com/google-ads/api/docs/first-call/dev-tokenتكامل Webhook
تحقق HMAC-SHA256 + retry
تحقق في خادمك، dedup، ack. Gurulu تدير الـ retries.
Node.js / Bun / TypeScript
// Node.js — HMAC-SHA256 verify
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyGuruluSignature(
rawBody: string,
header: string | undefined,
secret: string,
): boolean {
if (!header?.startsWith('sha256=')) return false;
const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
const received = header.slice(7);
return (
expected.length === received.length &&
timingSafeEqual(Buffer.from(expected), Buffer.from(received))
);
}Python 3.10+
# Python — HMAC-SHA256 verify
import hmac, hashlib
def verify_gurulu_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
if not header or not header.startswith("sha256="):
return False
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
received = header[7:]
return hmac.compare_digest(expected, received)نموذج Payload
{
"audience_id": "aud_01H8XYZ",
"tenant_id": "tnt_01H8ABC",
"members": [
{ "person_id": "per_01H8DEF", "email_sha256": "…", "joined_at": "2026-05-29T06:00:00Z" }
],
"delta": "joined",
"dispatched_at": "2026-05-29T07:00:00Z"
}تشفير KMS
شفافية بيانات الاعتماد
Meta access token و Google refresh token و webhook secret — جميعها تُخزَّن في KMS envelopes.
كيف تُخزَّن
كل اعتماد يُشفَّر بـ Data Encryption Key (DEK) من نوع AES-GCM؛ وتُغلَّف DEK بمفتاح KMS الجذر. الـ worker فقط يفك التشفير — UI لا يلمس النص الصريح أبداً.
- docsModules.destinations.kms.how.bullets.envelope
- فك التشفير من جهة الخادم في الـ worker فقط — UI و API لا يريان النص الصريح أبداً
- قائمة البيانات في UI تعرض قناع آخر 4 خانات (مثل '••••••a8f3')
{
"kid": "kms_2026_q2_primary",
"encrypted_dek": "AQEDAH4...",
"iv": "5b9e8c7a4f3d2e1b6c0a9d8e",
"tag": "a1b2c3d4...",
"ciphertext": "f7e8d9..."
}Dispatch + dedup
Dedup لمدة 24 ساعة + retry بتراجع أسي
نفس (audience، member، payload) لن يُرسَل مرتين خلال 24 ساعة. عند الفشل، retry بتراجع أسي.
Dedup عبر payload-hash
يُحسَب payload_hash لكل dispatch + تُحفَظ نافذة dedup لمدة 24 ساعة. نفس hash → تخطّي (idempotent).
Retry بتراجع أسي
30s → 2m → 10m → 1h → 6h. بعد 5 محاولات: DLQ. جدول dispatches يعرض كل محاولة + كود الخطأ.
وثائق ذات صلة
اقرأ بعد ذلك
أنشئ جمهوراً أولاً، ثم اربطه بوجهة. تعمّق أكثر عبر مرجع الـ API.