am c60f010e: am 8b20cdb2: Merge "Add API to track usage time of apps." into mnc-dev

* commit 'c60f010edcb197451d087207b0c9527d74cff245':
  Add API to track usage time of apps.

core/java/android/app/ActivityOptions.java

@@ -25,6 +25,7 @@ import android.os.IRemoteCallback;
 import android.os.RemoteException;
 import android.os.ResultReceiver;
 import android.util.Pair;
+import android.util.Slog;
 import android.view.View;
 import android.view.Window;
 
@@ -38,6 +39,19 @@ import java.util.ArrayList;
 public class ActivityOptions {
     private static final String TAG = "ActivityOptions";
 
+    /**
+     * A long in the extras delivered by {@link #requestUsageTimeReport} that contains
+     * the total time (in ms) the user spent in the app.
+     */
+    public static final String EXTRA_USAGE_REPORT_TIME = "android.time";
+
+    /**
+     * A Bundle in the extras delivered by {@link #requestUsageTimeReport} that contains
+     * detailed information about the time spent in each package associated with the app;
+     * each key is a package name, whose value is a long containing the time (in ms).
+     */
+    public static final String EXTRA_USAGE_REPORT_PACKAGES = "android.package";
+
     /**
      * The package name that created the options.
      * @hide
@@ -118,6 +132,8 @@ public class ActivityOptions {
     private static final String KEY_RESULT_CODE = "android:resultCode";
     private static final String KEY_EXIT_COORDINATOR_INDEX = "android:exitCoordinatorIndex";
 
+    private static final String KEY_USAGE_TIME_REPORT = "android:usageTimeReport";
+
     /** @hide */
     public static final int ANIM_NONE = 0;
     /** @hide */
@@ -160,6 +176,7 @@ public class ActivityOptions {
     private Intent mResultData;
     private int mResultCode;
     private int mExitCoordinatorIndex;
+    private PendingIntent mUsageTimeReport;
 
     /**
      * Create an ActivityOptions specifying a custom animation to run when
@@ -586,6 +603,15 @@ public class ActivityOptions {
         return opts;
     }
 
+    /**
+     * Create a basic ActivityOptions that has no special animation associated with it.
+     * Other options can still be set.
+     */
+    public static ActivityOptions makeBasic() {
+        final ActivityOptions opts = new ActivityOptions();
+        return opts;
+    }
+
     /** @hide */
     public boolean getLaunchTaskBehind() {
         return mAnimationType == ANIM_LAUNCH_TASK_BEHIND;
@@ -597,6 +623,11 @@ public class ActivityOptions {
     /** @hide */
     public ActivityOptions(Bundle opts) {
         mPackageName = opts.getString(KEY_PACKAGE_NAME);
+        try {
+            mUsageTimeReport = opts.getParcelable(KEY_USAGE_TIME_REPORT);
+        } catch (RuntimeException e) {
+            Slog.w(TAG, e);
+        }
         mAnimationType = opts.getInt(KEY_ANIM_TYPE);
         switch (mAnimationType) {
             case ANIM_CUSTOM:
@@ -729,6 +760,11 @@ public class ActivityOptions {
     /** @hide */
     public Intent getResultData() { return mResultData; }
 
+    /** @hide */
+    public PendingIntent getUsageTimeReport() {
+        return mUsageTimeReport;
+    }
+
     /** @hide */
     public static void abort(Bundle options) {
         if (options != null) {
@@ -745,6 +781,7 @@ public class ActivityOptions {
         if (otherOptions.mPackageName != null) {
             mPackageName = otherOptions.mPackageName;
         }
+        mUsageTimeReport = otherOptions.mUsageTimeReport;
         mTransitionReceiver = null;
         mSharedElementNames = null;
         mIsReturning = false;
@@ -828,6 +865,9 @@ public class ActivityOptions {
             b.putString(KEY_PACKAGE_NAME, mPackageName);
         }
         b.putInt(KEY_ANIM_TYPE, mAnimationType);
+        if (mUsageTimeReport != null) {
+            b.putParcelable(KEY_USAGE_TIME_REPORT, mUsageTimeReport);
+        }
         switch (mAnimationType) {
             case ANIM_CUSTOM:
                 b.putInt(KEY_ANIM_ENTER_RES_ID, mCustomEnterResId);
@@ -872,6 +912,34 @@ public class ActivityOptions {
         return b;
     }
 
+    /**
+     * Ask the the system track that time the user spends in the app being launched, and
+     * report it back once done.  The report will be sent to the given receiver, with
+     * the extras {@link #EXTRA_USAGE_REPORT_TIME} and {@link #EXTRA_USAGE_REPORT_PACKAGES}
+     * filled in.
+     *
+     * <p>The time interval tracked is from launching this activity until the user leaves
+     * that activity's flow.  They are considered to stay in the flow as long as
+     * new activities are being launched or returned to from the original flow,
+     * even if this crosses package or task boundaries.  For example, if the originator
+     * starts an activity to view an image, and while there the user selects to share,
+     * which launches their email app in a new task, and they complete the share, the
+     * time during that entire operation will be included until they finally hit back from
+     * the original image viewer activity.</p>
+     *
+     * <p>The user is considered to complete a flow once they switch to another
+     * activity that is not part of the tracked flow.  This may happen, for example, by
+     * using the notification shade, launcher, or recents to launch or switch to another
+     * app.  Simply going in to these navigation elements does not break the flow (although
+     * the launcher and recents stops time tracking of the session); it is the act of
+     * going somewhere else that completes the tracking.</p>
+     *
+     * @param receiver A broadcast receiver that willl receive the report.
+     */
+    public void requestUsageTimeReport(PendingIntent receiver) {
+        mUsageTimeReport = receiver;
+    }
+
     /**
      * Return the filtered options only meant to be seen by the target activity itself
      * @hide