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