تتيح لك هذه الوحدة إدارة الأحداث والخصائص — وهي أزواج مفتاح/قيمة دائمة تُرفَق تلقائيًا بكل حدث يتم تعقّبه.

تُخزَّن الخصائص الفائقة محليًا وتُدمَج في حمولة كل حدث عند تعقّب الأحداث.

لمعرفة المزيد حول إدارة الأحداث في واجهة OpenReplay، تفضّل بزيارة Data Management.

متاحة في:

tracker.analytics.events

تُخزَّن الخصائص الفائقة في حزمة تطوير البرمجيات (SDK) وتُدمَج في كل حدث ضمن properties.

تُمرَّر خصائص الحدث فقط من أجل استدعاء واحد لـ track/sendEvent، ولا تُحفَظ كخصائص فائقة.

هذه المفاتيح محجوزة ولا يمكن إنشاؤها/إزالتها عبر مساعِدات الخصائص الفائقة:

• properties
• token
• timestamp

// Track an event.
// The `properties` argument is per-event only (not persisted).
tracker.analytics.events.sendEvent(eventName: string, properties?: Record<string, any>, options?: { send_immediately: boolean })

// Create/update super properties (persisted)
tracker.analytics.events.setProperty(name: string, value: any): void
tracker.analytics.events.setProperty(properties: Record<string, any>): void

// Create super properties only if they don't exist yet (persisted)
tracker.analytics.events.setPropertiesOnce(name: string, value: any): void
tracker.analytics.events.setPropertiesOnce(properties: Record<string, any>): void

// Remove super properties (persisted)
tracker.analytics.events.unsetProperties(name: string): void
tracker.analytics.events.unsetProperties(names: string[]): void

// Clear all super properties
tracker.analytics.events.reset(): void

tracker.analytics.events.sendEvent("Button Clicked", {
  button_text: "Start",
  page: "home",
})

تنطبق هذه الخصائص على هذا الحدث فقط.

عند تعيين خصائص فائقة، تُضمَّن تلقائيًا في كل حدث ثم تُدمَج مع الخصائص الخاصة بكل حدث:

tracker.analytics.events.setProperty({
  app_version: "1.42.0",
  env: "prod",
})

tracker.analytics.events.sendEvent("Signup Started", {
	// per-event, can override a super property with the same key
  plan: "pro", 
})

ترتيب الدمج:

• تُضاف الخصائص الفائقة أولًا
• تُدمَج الخصائص الخاصة بكل حدث فوقها

لذا تتغلّب الخصائص الخاصة بكل حدث عند تعارض المفاتيح.

تُنشئ خصائص فائقة أو تستبدلها.

// object form
tracker.analytics.events.setProperty({
  app_version: "1.42.0",
  region: "eu",
})

// key/value form
tracker.analytics.events.setProperty("build_sha", "3f2c9a1")

• يتم تجاهل المفاتيح الافتراضية/الداخلية (التي تتعقّبها حزمة تطوير البرمجيات) ولن تُضاف كخصائص فائقة.
• تُحفَظ التغييرات محليًا فقط إذا تغيّر شيء ما فعليًا.

تُنشئ خصائص فائقة فقط إذا لم تكن موجودة بعد.

tracker.analytics.events.setPropertiesOnce({
  first_seen_at: Date.now(),
  signup_source: "docs",
})

// key/value form
tracker.analytics.events.setPropertiesOnce("initial_referrer", document.referrer)

• تُعيَّن الخصائص فقط إذا كان المفتاح مفقودًا.
• يتم تجاهل المفاتيح المحجوزة (properties وtoken وtimestamp).

تُزيل خاصية فائقة واحدة أو أكثر.

// single
tracker.analytics.events.unsetProperties("region")

// multiple
tracker.analytics.events.unsetProperties(["app_version", "build_sha"])

• لا يمكن إزالة المفاتيح المحجوزة.
• تُحفَظ عملية الإزالة بشكل دائم.

تمسح جميع الخصائص الفائقة.

tracker.analytics.events.reset()

افتراضيًا، تُوضَع الأحداث في قائمة انتظار/تُجمَّع على دفعات. يمكنك طلب إرسال فوري لحدث ما:

tracker.analytics.events.sendEvent(
  "Checkout Completed",
  { value: 199, currency: "EUR" },
  { send_immediately: true },
)

تدعم جميع الطرق طبقة توافق مُوفَّرة لتسهيل الانتقال والإلمام:

tracker.analytics.events.register       // setProperty
tracker.analytics.events.register_once  // setPropertiesOnce
tracker.analytics.events.unregister     // unsetProperties
tracker.analytics.events.track          // sendEvent

إذا واجهت أي مشكلات، تواصل معنا عبر Slack أو اطّلع على المنتدى الخاص بنا واحصل على المساعدة من مجتمعنا.