التوثيق · AppsKitSDK (AKS) — دليل التكامل مع Android

7. أحداث AKS والسجلات

7.1 أحداث الشاشة التلقائية

إذا كانت Activity لديك تعيد تعريف setScreenNameAndId() (وتُرجع Pair<screenId, screenName>)، فإن Activity الأساسية تُطلق حدث SCREEN تلقائيًا في onCreate() — ولا تحتاج إلى استدعاء أي شيء بنفسك لهذا الغرض.

7.2 إرسال الأحداث يدويًا من داخل Activity

من داخل أي Activity ترث من AppsKitSDKBaseActivity / AppsKitSDKBaseComponentActivity:

kotlin

sendAKSEvent(AppsKitSDKEventType.BUTTON, "SaveClicked")

يُنشئ هذا الاستدعاء حدثًا باسم e_{screenId}_{prefix}_{name} ويسجّله في Firebase Analytics (وفي سجل تصحيح الأخطاء أيضًا)، باستخدام معرّف الشاشة من setScreenNameAndId().

الدالة sendAKSEvent ليست سوى دالة تغليف لتسهيل الاستخدام — فهي تنفّذ الأسطر التالية، التي يمكنك استدعاؤها مباشرةً من أي موضع لا تتوفر فيه هذه الدالة (مثل Fragment أو ViewModel أو Composable أو Activity عادية لا ترث من إحدى فئات Activity الأساسية في AKS):

kotlin

AKSLogManager.log(
    PlatformContext(this),
    AKSEventCreator.createEvent(screenId, eventType, name)
)

القيمة screenId هنا هي ببساطة قيمة Int التي تحصل عليها عادةً من setScreenNameAndId().first — احتفظ بها ومرّرها بنفسك إذا لم تكن داخل Activity أساسية من AKS.

ثوابت AppsKitSDKEventType وبادئة اسم الحدث المقابلة لها في Firebase:

ثابت التعداد	البادئة
`SCREEN`	`SCR`
`BUTTON`	`BTN`
`STATUS`	`STS`
`ITEM`	`ITM`
`LIST`	`LST`
`ICON`	`ICO`
`DIALOG_BTN`	`DLG_BTN`
`ACTION`	`ACT`
`TAB`	`TAB`
`DIALOG`	`DLG`

يحدّد Firebase Analytics طول أسماء الأحداث بحد أقصى 40 حرفًا، لذا اجعل name قصيرًا — خصوصًا لأحداث ITEM/LIST التي تُلحق فهرسًا/عنوانًا بالاسم.

7.3 التسجيل والأحداث للأغراض العامة

للأحداث التي تقع خارج نطاق شاشة Activity (مثل الخدمات وViewModels والمستودعات وغيرها)، استخدم فئة التغليف AppsKitSDKLogManager التي تتعامل مع Context عادي:

kotlin

// Free-form debug log (tagged PTB_LOG in Logcat)
AppsKitSDKLogManager.log(AppsKitSDKLogType.INFO, "Sync finished")

// Fire a named Firebase event with parameters, from anywhere
AppsKitSDKLogManager.sendEvent("custom_event_name", mapOf("key" to "value"))

// Purchase / subscription events
AppsKitSDKLogManager.sendPurchaseEvent(
    context = this,
    purchaseType = PurchaseType.SUBSCRIPTION, // or PurchaseType.IN_APP
    productId = "premium_monthly",
    price = 4.99,
    currency = "USD",
    receiptId = receipt,
    uniqueTransactionId = transactionId,
    startDate = startDateIso,
    endDate = endDateIso
)

// SDK build/version banner in Logcat
AppsKitSDKLogManager.logAarVersion()

AppsKitSDKLogType: INFO, ERROR, VERBOSE, WARNING, DESCRIPTION.

7.4 وسوم سجل تصحيح الأخطاء

صفِّ مخرجات Logcat حسب الوسوم التالية:

PTB_LOG — سجلات SDK العامة
PTB_LOG_ADS — دورة حياة تحميل الإعلانات وعرضها
PTB_LOG_ANALYTICS — الأحداث المُرسلة إلى Firebase/منصات قياس أداء التسويق على الأجهزة المحمولة (MMPs)

← 6. استدعاء تنسيقات الإعلانات 8. التفضيلات المحلية (`PreferencesManager`) →