ردیابی سنجه‌های ابزاره

Android 16 شامل میاناهای برنامه‌سازی کاربردی سنجه‌های اضافی است که جزئی‌تر هستند. این سنجه‌ها کنش‌های تک‌ضرب زدن مثل کلیک کردن روی دکمه، پیمایش، ظهورها، و اندازه و موقعیت ابزاره را ردیابی می‌کنند.

میانای برنامه‌سازی کاربردی اصلی AppWidgetEvent است. از WorkManager برای ایجاد یک کارگر دوره‌ای استفاده کنید که تعامل با ابزاره را به‌صورت روزانه، هفتگی، یا هر زمان که برنامه‌تان باز می‌شود ثبت کند.

برای نمونه‌ای از ردیابی کلیک‌ها، پیمایش‌ها، و طول ظهور، قطعه کد زیر را ببینید.

@RequiresApi(Build.VERSION_CODES_FULL.BAKLAVA_1)
fun getWidgetEngagementMetrics(context: Context) {
    val manager = AppWidgetManager.getInstance(context)

    val endTime = System.currentTimeMillis()
    val startTime = endTime - (24 * 60 * 60 * 1000) // a day ago

    val events = manager.queryAppWidgetEvents(startTime, endTime)

    if (events.isEmpty()) {
        Log.d(TAG, "No events found for the given time range.")
    }

    val metrics = hashMapOf(
        "clicks" to 0L,
        "scrolls" to 0L,
        "totalImpressionLength" to 0L
    )

    for (event in events) {

        Log.d(TAG, "Event Start: ${event.start}")
        Log.d(TAG, "Event End: ${event.end}")

        val widgetId = event.appWidgetId

        // Tap actions
        val clickedIds = event.clickedIds
        if (clickedIds?.isNotEmpty() == true) {
            metrics["clicks"] = metrics.getValue("clicks") + clickedIds.size
            // Log or analyze which components were clicked.
            for (id in clickedIds) {
                Log.d(TAG, "Widget $widgetId: Tap event on component with ID $id")
            }
        }

        // Scroll events
        val scrolledIds = event.scrolledIds
        if (scrolledIds?.isNotEmpty() == true) {
            metrics["scrolls"] = metrics.getValue("scrolls") + scrolledIds.size
            // Log or analyze which lists were scrolled.
            for (id in scrolledIds) {
                Log.d(TAG, "Widget $widgetId: Scroll event in list with ID/tag $id")
            }
        }

        // Impressions
        metrics["totalImpressionLength"] = metrics.getValue("totalImpressionLength") + event.visibleDuration.toMillis()
        Log.d(
            TAG,
            "Widget $widgetId: Impression event with duration " + event.visibleDuration.toMillis() + "ms"
        )

        // Position
        val position = event.position
        if (position != null) {
            Log.d(
                TAG,
                "Widget $widgetId: left=${position.left}, right=${position.right}, top=${position.top}, bottom=${position.bottom}"
            )
        }
    }
    Log.d("WidgetMetrics", "Metrics: $metrics")
}

برای حفظ سلامت سیستم، رویدادها به‌طور پیش‌فرض یک بار در ساعت گزارش می‌شوند، هرچند سازندگان دستگاه ممکن است پنجره گزارش‌دهی را تغییر دهند. برای مثال، در دستگاه‌های Pixel، اگر کاربری در یک ساعت ۱۰ بار در همان فهرست در ابزاره شما پیمایش کند، فقط ۱ رویداد پیمایش برای آن ساعت شمرده می‌شود.

برای آزمایش، می‌توانید مشخصه زیر را روی زمان مشخصی تنظیم کنید و دستگاه آزمایشی‌تان را بازراه‌اندازی کنید. در مثال زیر، پنجره گزارش روی ۰ میلی‌ثانیه تنظیم شده است و رویدادها فوراً گزارش می‌شوند.

adb shell device_config override systemui widget_events_report_interval_ms 0

برای تنظیم برچسب سفارشی برای گزارش کردن کلیک‌ها و پیمایش‌ها، می‌توانید از RemoteViews.setAppWidgetEventTag در نمایی در چیدمان RemoteViews استفاده کنید. این برچسب عدد صحیح زمانی استفاده می‌شود که برای AppWidgetEvents که شامل کلیک‌ها یا پیمایش‌ها در این نما است پُرسمان می‌کنید.