مرجع الـ 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.