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

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

متاحة عبر:

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")

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

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

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 الخاص بنا أو اطّلع على المنتدى واحصل على المساعدة من مجتمعنا.