Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit bb4b474f authored by Willie Koomson's avatar Willie Koomson
Browse files

Add constants for app widget usage events 

This change adds constants which define the data that is available
within app widget USER_INTERACTION events. It also defines a new
resource ID to be used to set metrics tags for RemoteViews layouts.
This change also adds helper functions for creating event bundles using
these constants.

Adds AppWidgetEventsTest in coretests.

Bug: 364655296
Test: atest FrameworksCoreTests:AppWidgetEventsTest
Flag: android.appwidget.flags.engagement_metrics
Ignore-AOSP-First: folder is new in this branch
Change-Id: Ib482600f55d99a8e817fd901cae715fadadb57d9
parent 6fd100a9

core/api/current.txt

+7 −0
Original line number Diff line number Diff line
@@ -2451,6 +2451,7 @@ package android { 
    field public static final int primary = 16908300; // 0x102000c

    field public static final int progress = 16908301; // 0x102000d

    field public static final int redo = 16908339; // 0x1020033

    field @FlaggedApi("android.appwidget.flags.engagement_metrics") public static final int remoteViewsMetricsId;

    field public static final int replaceText = 16908340; // 0x1020034

    field public static final int secondaryProgress = 16908303; // 0x102000f

    field public static final int selectAll = 16908319; // 0x102001f
@@ -9892,6 +9893,8 @@ package android.appwidget { 
    field public static final String ACTION_APPWIDGET_PICK = "android.appwidget.action.APPWIDGET_PICK";

    field public static final String ACTION_APPWIDGET_RESTORED = "android.appwidget.action.APPWIDGET_RESTORED";

    field public static final String ACTION_APPWIDGET_UPDATE = "android.appwidget.action.APPWIDGET_UPDATE";

    field @FlaggedApi("android.appwidget.flags.engagement_metrics") public static final String EVENT_CATEGORY_APPWIDGET = "android.appwidget";

    field @FlaggedApi("android.appwidget.flags.engagement_metrics") public static final String EVENT_TYPE_WIDGET_INTERACTION = "widget_interaction";

    field public static final String EXTRA_APPWIDGET_ID = "appWidgetId";

    field public static final String EXTRA_APPWIDGET_IDS = "appWidgetIds";

    field public static final String EXTRA_APPWIDGET_OLD_IDS = "appWidgetOldIds";
@@ -9901,6 +9904,10 @@ package android.appwidget { 
    field public static final String EXTRA_APPWIDGET_PROVIDER_PROFILE = "appWidgetProviderProfile";

    field public static final String EXTRA_CUSTOM_EXTRAS = "customExtras";

    field public static final String EXTRA_CUSTOM_INFO = "customInfo";

    field @FlaggedApi("android.appwidget.flags.engagement_metrics") public static final String EXTRA_EVENT_CLICKED_VIEWS = "android.appwidget.extra.EVENT_CLICKED_VIEWS";

    field @FlaggedApi("android.appwidget.flags.engagement_metrics") public static final String EXTRA_EVENT_DURATION_MS = "android.appwidget.extra.EVENT_DURATION_MS";

    field @FlaggedApi("android.appwidget.flags.engagement_metrics") public static final String EXTRA_EVENT_POSITION_RECT = "android.appwidget.extra.EVENT_POSITION_RECT";

    field @FlaggedApi("android.appwidget.flags.engagement_metrics") public static final String EXTRA_EVENT_SCROLLED_VIEWS = "android.appwidget.extra.EVENT_SCROLLED_VIEWS";

    field public static final String EXTRA_HOST_ID = "hostId";

    field public static final int INVALID_APPWIDGET_ID = 0; // 0x0

    field public static final String META_DATA_APPWIDGET_PROVIDER = "android.appwidget.provider";

core/java/android/appwidget/AppWidgetManager.java

+97 −0
Original line number Diff line number Diff line
@@ -31,6 +31,7 @@ import android.annotation.UiThread; 
import android.annotation.UserIdInt;

import android.app.IServiceConnection;

import android.app.PendingIntent;

import android.app.usage.UsageStatsManager;

import android.appwidget.flags.Flags;

import android.compat.annotation.UnsupportedAppUsage;

import android.content.ComponentName;
@@ -41,12 +42,14 @@ import android.content.ServiceConnection; 
import android.content.pm.PackageManager;

import android.content.pm.ParceledListSlice;

import android.content.pm.ShortcutInfo;

import android.graphics.Rect;

import android.os.Build;

import android.os.Bundle;

import android.os.Handler;

import android.os.HandlerExecutor;

import android.os.HandlerThread;

import android.os.Looper;

import android.os.PersistableBundle;

import android.os.Process;

import android.os.RemoteException;

import android.os.UserHandle;
@@ -485,6 +488,67 @@ public class AppWidgetManager { 
    public static final String ACTION_APPWIDGET_HOST_RESTORED

            = "android.appwidget.action.APPWIDGET_HOST_RESTORED";



    /**

     * This is the value of {@link UsageStatsManager.EXTRA_EVENT_ACTION} in the event bundle for

     * widget user interaction events.

     *

     * A single widget interaction event describes what user interactions happened during a single

     * impression of the widget.

     */

    @FlaggedApi(Flags.FLAG_ENGAGEMENT_METRICS)

    public static final String EVENT_TYPE_WIDGET_INTERACTION = "widget_interaction";



    /**

     * This is the value of {@link UsageStatsManager.EXTRA_EVENT_CATEGORY} in the event bundle for

     * widget user interaction events.

     */

    @FlaggedApi(Flags.FLAG_ENGAGEMENT_METRICS)

    public static final String EVENT_CATEGORY_APPWIDGET = "android.appwidget";



    /**

     * This bundle extra describes which views have been clicked during a single impression of the

     * widget. It is an integer array of view IDs of the clicked views.

     *

     * Widget providers may set a different ID for event purposes by setting the

     * {@link android.R.id.remoteViewsMetricsId} int tag on the view.

     *

     * @see android.views.RemoteViews.setIntTag

     */

    @FlaggedApi(Flags.FLAG_ENGAGEMENT_METRICS)

    public static final String EXTRA_EVENT_CLICKED_VIEWS =

            "android.appwidget.extra.EVENT_CLICKED_VIEWS";



    /**

     * This bundle extra describes which views have been scrolled during a single impression of the

     * widget. It is an integer array of view IDs of the scrolled views.

     *

     * Widget providers may set a different ID for event purposes by setting the

     * {@link android.R.id.remoteViewsMetricsId} int tag on the view.

     *

     * @see android.views.RemoteViews.setIntTag

     */

    @FlaggedApi(Flags.FLAG_ENGAGEMENT_METRICS)

    public static final String EXTRA_EVENT_SCROLLED_VIEWS =

            "android.appwidget.extra.EVENT_SCROLLED_VIEWS";



    /**

     * This bundle extra contains a long that represents the duration of time in milliseconds

     * during which the widget was visible.

     */

    @FlaggedApi(Flags.FLAG_ENGAGEMENT_METRICS)

    public static final String EXTRA_EVENT_DURATION_MS =

            "android.appwidget.extra.EVENT_DURATION_MS";



    /**

     * This bundle extra contains an integer array with 4 elements that describe the left, top,

     * right, and bottom coordinates of the widget at the end of the interaction event.

     *

     * This Rect indicates the current position and size of the widget.

     */

    @FlaggedApi(Flags.FLAG_ENGAGEMENT_METRICS)

    public static final String EXTRA_EVENT_POSITION_RECT =

            "android.appwidget.extra.EVENT_POSITION_RECT";



    private static final String TAG = "AppWidgetManager";



    private static Executor sUpdateExecutor;
@@ -1516,6 +1580,39 @@ public class AppWidgetManager { 
        }

    }



    /**

     * Create a {@link PersistableBundle} that represents a single widget interaction event.

     *

     * @param appWidgetId App Widget ID of the widget.

     * @param durationMs Duration of the impression in milliseconds

     * @param position Current position of the widget.

     * @param clickedIds IDs of views clicked during this event.

     * @param scrolledIds IDs of views scrolled during this event.

     *

     * @hide

     */

    @FlaggedApi(Flags.FLAG_ENGAGEMENT_METRICS)

    @NonNull

    public static PersistableBundle createWidgetInteractionEvent(int appWidgetId, long durationMs,

            @Nullable Rect position, @Nullable int[] clickedIds, @Nullable int[] scrolledIds) {

        PersistableBundle extras = new PersistableBundle();

        extras.putString(UsageStatsManager.EXTRA_EVENT_ACTION, EVENT_TYPE_WIDGET_INTERACTION);

        extras.putString(UsageStatsManager.EXTRA_EVENT_CATEGORY, EVENT_CATEGORY_APPWIDGET);

        extras.putInt(EXTRA_APPWIDGET_ID, appWidgetId);

        extras.putLong(EXTRA_EVENT_DURATION_MS, durationMs);

        if (position != null) {

            extras.putIntArray(EXTRA_EVENT_POSITION_RECT,

                    new int[]{position.left, position.top, position.right, position.bottom});

        }

        if (clickedIds != null && clickedIds.length > 0) {

            extras.putIntArray(EXTRA_EVENT_CLICKED_VIEWS, clickedIds);

        }

        if (scrolledIds != null && scrolledIds.length > 0) {

            extras.putIntArray(EXTRA_EVENT_SCROLLED_VIEWS, scrolledIds);

        }

        return extras;

    }





    @UiThread

    private static @NonNull Executor createUpdateExecutorIfNull() {

core/java/android/appwidget/flags.aconfig

+7 −0
Original line number Diff line number Diff line
@@ -102,3 +102,10 @@ flag { 
    purpose: PURPOSE_BUGFIX

  }

}



flag {

  name: "engagement_metrics"

  namespace: "app_widgets"

  description: "Enable collection of widget engagement metrics"

  bug: "364655296"

}

core/res/res/values/ids.xml

+3 −0
Original line number Diff line number Diff line
@@ -290,4 +290,7 @@ 


  <!-- View tag associating a view with its overridden id, to ensure valid recycling only. -->

  <item type="id" name="remote_views_override_id" />



  <!-- View tag associating a view with its id for widget metrics. -->

  <item type="id" name="remoteViewsMetricsId" />

</resources>

core/res/res/values/public-staging.xml

+2 −0
Original line number Diff line number Diff line
@@ -136,6 +136,8 @@ 
  </staging-public-group>



  <staging-public-group type="id" first-id="0x01b60000">

    <!-- @FlaggedApi(android.appwidget.flags.Flags.FLAG_ENGAGEMENT_METRICS) -->

    <public name="remoteViewsMetricsId"/>

  </staging-public-group>



  <staging-public-group type="style" first-id="0x01b50000">