التوثيق · 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`) →