مرجع الـ SDK
كل استدعاء عام في SDK الويب 0.4.0 (المتغير العام datacub من وسم السكربت، وأنواعه في datacub.d.ts) وفي @datacub/react-native 0.1.0. ولا استدعاء يرمي خطأ أبد؛ والمرفوض ما يسوي شيء.
SDK الويب
import type { InitOptions, Properties } from './datacub'
const options: InitOptions = { apiHost: 'https://ingest.datacub.example', hashRouting: false, autocapture: true, release: '1.4.0' }
datacub.init('pk_live_YOUR_PROJECT_KEY', options)
const props: Properties = { plan: 'pro', seats: 3 }
datacub.track('plan_changed', props)
datacub.identify('user_8f3a2c', { account: 'ws_51', email: 'sara@example.sa', name: 'Sara', phone: '+966551234567' })
datacub.reset()
datacub.consent.revoke()| الاستدعاء | وش يسوي |
|---|---|
datacub.init(publicKey, options?) | يشغّل الـ SDK مرة وحدة؛ والاستدعاءات اللي بعده تنتجاهل. واللي قبله تنتظر (لين 100) |
datacub.track(event, properties?) | حدث مخصص. القواعد |
datacub.identify(userId, { account?, email?, name?, phone?, ...traits }) | بعد تسجيل الدخول: يربط نشاط هذا المتصفح بالمستخدم، والصفات توصفه. التفاصيل |
datacub.reset() | عند تسجيل الخروج: معرّف زائر وجلسة جديدة |
datacub.consent.grant(options?) | لوضع الموافقة أولًا: يبدأ الحفظ والإرسال. الخيارات: method و policyVersion و overrideGPC. ويلغي الرفض المحفوظ |
datacub.consent.revoke() | يشتغل في كل مشروع: يوقف، ويمسح باقي كوكيز الـ SDK والطابور، ويتذكر الرفض على هذا المتصفح |
خيارات init: apiHost (الافتراضي https://ingest.datacub.example)، و hashRouting (الافتراضي false)، و autocapture (الافتراضي true)، و release، و requireConsent (الافتراضي false: شوف طلب الموافقة). التفاصيل.
خصائص HTML: data-datacub-name="..." تسمّي نقرة أو نموذج؛ و class="datacub-no-capture" أو data-datacub-no-capture تستثني العنصر وكل اللي داخله. وخصائص وسم السكربت: data-key و data-api-host و data-require-consent.
الكوكيز، كلها من نفس موقعك: datacub_id (معرّف الزائر، 400 يوم)، و datacub_u (معرّف المستخدم)، و datacub_a (معرّف الحساب)، و datacub_ss (الجلسة، 30 دقيقة). وكل اسم ينتهي بـ _ وأول ثمانية أحرف بعد pk_live_ أو pk_test_ في مفتاحك (datacub_id_k7Qm2xPa): كل النطاقات الفرعية اللي تستخدم نفس المفتاح تتشارك زائرًا واحدًا وجلسة واحدة، والمفتاح الثاني على نفس الموقع له زائره الخاص. ومع requireConsent ما تنكتب إلا بعد grant(). وبعد revoke() الكوكي الوحيد هو datacub_optout (400 يوم، بدون أي معرّف).
نافذة الاستبيان
الأسئلة اللي تكتبها في صفحة الاستبيانات في لوحة التحكم تظهر عن طريق ملف منفصل، ما ينحمّل إلا في المواقع اللي تستخدمه. أضفه جنب الـ SDK:
<script src="https://ingest.datacub.example/v1/feedback.js" async></script>| الاستدعاء أو الخاصية | وش يسوي |
|---|---|
datacub.ask(questionId, { into? }) | يعرض سؤال مشغّله "من الكود حقي"؛ و into تحطه داخل عنصر أو selector |
<div data-datacub-ask="questionId"></div> | نفس الشيء داخل الصفحة، بدون كود |
datacub.feedback()، أو أي عنصر عليه data-datacub-feedback | يفتح نافذة "أرسل ملاحظاتك" العامة |
الاستدعاءين ما يكونون موجودين إلا بعد ما ينحمّل الملف.
@datacub/react-native
import datacub, { type InitOptions, VERSION } from '@datacub/react-native'
import { trackNavigation } from '@datacub/react-native/navigation'
const options: InitOptions = {
apiHost: 'https://ingest.datacub.example',
storage: { getItem: () => null, setItem: () => {}, removeItem: () => {} },
app: { applicationId: 'sa.example.shop', nativeApplicationVersion: '2.3.0', nativeBuildVersion: '87' },
}
datacub.init('pk_live_YOUR_PROJECT_KEY', options)
datacub.track('order_placed', { items: 2 })
datacub.screen('Checkout', { step: 'payment' })
datacub.identify('user_8f3a2c', { account: 'ws_51' })
datacub.reset()
datacub.consent.revoke()
await datacub.flush()
console.log(VERSION, typeof trackNavigation)| الاستدعاء | وش يسوي |
|---|---|
datacub.init(publicKey, options?) | يشغّل الـ SDK مرة وحدة. الخيارات: storage و app و apiHost و requireConsent |
datacub.track(event, properties?) | حدث مخصص |
datacub.screen(name, properties?) | مشاهدة شاشة؛ ونفس الاسم مرتين ورا بعض ينحسب مرة |
datacub.identify(userId, { account?, email?, name?, phone?, ...traits }) | بعد تسجيل الدخول، مثل الويب |
datacub.reset() | عند تسجيل الخروج |
datacub.flush() | يرسل اللي في الطابور؛ يخلص لما ينتهي أو يفشل، وما يرمي خطأ أبد |
datacub.consent.grant(options?)، datacub.consent.revoke() | مثل الويب؛ و grant ياخذ method و policyVersion. والرفض علامة داخل القيمة المحفوظة في تخزين الـ SDK |
trackNavigation(ref) من @datacub/react-native/navigation | مشاهدات الشاشات من ref حق React Navigation؛ يرجّع دالة لإلغاء الاشتراك |
الأحداث اللي يرسلها datacub عنك
| الحدث | الـ SDK | متى |
|---|---|---|
$pageview، $pageleave | الويب | مشاهدات الصفحات |
$click، $form_submit | الويب | النقرات والنماذج |
$screen | الجوال | datacub.screen أو trackNavigation |
$consent | الاثنين | datacub.consent.grant()، لما يطلب المشروع الموافقة أولًا |
$identify | الاثنين | datacub.identify لمستخدم جديد، مع أي صفات |
$set | الاثنين | datacub.identify بصفات لمستخدم متعرّف عليه أصلًا |
أسماء الأحداث اللي تبدأ بـ $ محجوزة لهذي.
HTTP
الـ SDK في الويب والجوال يرسل POST {apiHost}/v1/batch بجسم JSON فيه لين 100 حدث. ما تحتاج تستدعيه بنفسك. وإذا تمرّره عن طريق بروكسي، مرّر الجسم زي ما هو ورجّع حالة الرد كما هي، ومعها Retry-After.