عن المشروع

# TelemetryDeck Kotlin SDK مكتبة Kotlin لإرسال إشارات التحليلات من تطبيقات Android إلى [TelemetryDeck](https://telemetrydeck.com)، وهي منصة تحليلات تركز على الخصوصية. يعمل SDK على Android API 23+ مع Kotlin 2.3.x. ## القدرات الأساسية **إرسال الإشارات** — استدعِ `TelemetryDeck.send("eventName")` لإطلاق إشارة تحليلات فورًا، أو استخدم `TelemetryDeck.signal("eventName")` لوضعها في قائمة الانتظار لإرسالها لاحقًا. **تتبع الجلسات** — يكتشف تلقائيًا التثبيتات الجديدة، ويقيس مدة الجلسة، ويحسب مقاييس الاحتفاظ (متوسط ثواني الجلسة، الأيام المميزة المستخدمة، إجمالي عدد الجلسات). تُخزَّن حالة الجلسة محليًا على الجهاز وتُمسح عند إلغاء التثبيت. **هوية المستخدم** — ينشئ معرّفًا مجهولًا مرتبطًا بالجهاز افتراضيًا. يدعم معرّفات المستخدم المخصصة عبر `defaultUser` (يتم تجزئتها قبل الإرسال) أو تنفيذ مخصص لـ `TelemetryDeckIdentityProvider`. **معلمات البيئة** — يثري كل إشارة تلقائيًا ببيانات الجهاز (الطراز، نظام التشغيل، دقة الشاشة، الاتجاه، البنية، العلامة التجارية، المنطقة الزمنية)، وبيانات التطبيق (الإصدار، رقم البناء)، وبيانات SDK. كما يلتقط إعدادات إمكانية الوصول (مقياس الخط المعيّن إلى فئات حجم iOS، النص العريض، عكس الألوان، تقليل الحركة، المخطط الداكن/الفاتح). **إشارات التنقل** — تتبع تدفق المستخدم بين الشاشات باستخدام `TelemetryDeck.navigate(source, destination)` أو استدعِها عند كل تغيير مسار لتتبع المسار تلقائيًا. **تتبع المدة** — ابدأ وأوقف إشارات المدة المسماة (`startDurationSignal` / `stopAndSendDurationSignal`) لقياس الوقت المستغرق في أحداث محددة مثل خطوات المعالج. **مساعدات الاكتساب** — طرق ملائمة لكل من `acquiredUser(channel)` و `leadStarted(leadId)` و `leadConverted(leadId)`. **معلمات التقويم** — تضيف يوم الأسبوع، ويوم الشهر، وأسبوع السنة، والربع، وساعة اليوم، وعلامة عطلة نهاية الأسبوع، والمزيد إلى كل إشارة صادرة. **تتبع عمليات الشراء** — `purchaseCompleted()` يسجل عمليات الشراء داخل التطبيق مع رمز بلد السوق ومعرف المنتج. **وضع الذاكرة فقط** — استدعِ `inMemoryOnly(true)` على البناء لتشغيل دون الكتابة على القرص، وهو مناسب للعمليات المعزولة. يتم إعادة إنشاء هوية المستخدم عند كل تشغيل؛ ويكون اكتشاف التثبيت الجديد ومقاييس الاحتفاظ غير متاحين في هذا الوضع. ## التثبيت أضف إلى `build.gradle`: ```groovy implementation 'com.telemetrydeck:kotlin-sdk:7.2.0' ``` أضف إذن الإنترنت إلى `AndroidManifest.xml`: ```xml <uses-permission android:name="android.permission.INTERNET" /> ``` قم بالإعداد عبر بيانات البيان الوصفي أو عبر البناء البرمجي: ```kotlin val builder = TelemetryDeck.Builder() .appID("YOUR-APP-ID") .showDebugLogs(true) .defaultUser("anonymous-user") TelemetryDeck.start(applicationContext, builder) ``` ## المزوّدون والتخصيص يستخدم SDK نظام إضافات مزوّد. تشمل المزوّدين المدمجين `EnvironmentParameterProvider` و `PlatformContextProvider` و `AccessibilityProvider` و `SessionTrackingSignalProvider` و `CalendarParameterProvider`. يمكن إضافة إثراء مخصص عبر `DefaultParameterProvider` أو `DefaultPrefixProvider` أو بتنفيذ `TelemetryDeckIdentityProvider` و `TelemetryDeckSessionManagerProvider` و `TelemetryDeckStorage` للأنظمة الخلفية المخصصة.