OngoingActivity


public final class OngoingActivity


Main class to access the Ongoing Activities API. It's created with the Builder. After it's created (and before building and posting the Notification) apply apply needs to be called:

NotificationCompat.Builder builder = new NotificationCompat.Builder(context)
....
OngoingActivity ongoingActivity = new OngoingActivity.Builder(context, notificationId, builder);
....
ongoingActivity.apply(context);
notificationManager.notify(notificationId, builder.build());
Note that the notification passed to the Builder is also usen to take defaults if they are not explicitly set on it (see the Builder for details).

Note that if a Notification with that id was previously posted it will be replaced. If you need more than one Notification with the same ID you can use a String tag to differentiate them in both the Builder and notify

Afterward, update can be used to update the status.

If saving the OngoingActivity instance is not convenient, it can be recovered (after the notification is posted) with recoverOngoingActivity

It's worth mentioning that the information provided may be used/redered differently on different SysUIs, so we can only provide a general expectation.

Summary

Nested types

public final class OngoingActivity.Builder

Builder used to build an OngoingActivity

Public methods

void
apply(@NonNull Context context)

Notify the system that this activity should be shown as an Ongoing Activity.

@Nullable Icon

Get the animated icon that can be used on some surfaces to represent this OngoingActivity.

@Nullable String

Get the Category of this OngoingActivity if set, otherwise the category of the corresponding notification.

@Nullable String

Get the content description of this OngoingActivity if set.

@Nullable LocusIdCompat

Get the LocusId of this OngoingActivity, this can be used by the launcher to identify the corresponding launcher item and display it accordingly.

int

Get the notificationId of the notification associated with this OngoingActivity.

int

Get the id to this OngoingActivity.

@NonNull Icon

Get the static icon that can be used on some surfaces to represent this OngoingActivity.

@Nullable Status

Get the status of this ongoing activity, the status may be displayed on the UI to show progress of the Ongoing Activity.

@Nullable String

Get the tag of the notification associated with this OngoingActivity, or null if there is none.

long

Get the time (in elapsedRealtime time) the OngoingActivity was built.

@Nullable String

Get the title of this OngoingActivity if set.

@NonNull PendingIntent

Get the intent to be used to go back to the activity when the user interacts with the Ongoing Activity in other surfaces (for example, taps the Icon on the WatchFace).

static @Nullable OngoingActivity

Convenience method for clients that don’t want to / can’t store the OngoingActivity instance.

static @Nullable OngoingActivity

Convenience method for clients that don’t want to / can’t store the OngoingActivity instance.

static @Nullable OngoingActivity
recoverOngoingActivity(@NonNull Context context, int ongoingActivityId)

Convenience method for clients that don’t want to / can’t store the OngoingActivity instance.

void
@RequiresPermission(value = Manifest.permission.POST_NOTIFICATIONS)
update(@NonNull Context context, @NonNull Status status)

Update the status of this Ongoing Activity.

Public methods

apply

Added in 1.0.0
public void apply(@NonNull Context context)

Notify the system that this activity should be shown as an Ongoing Activity. This will modify the notification builder associated with this Ongoing Activity, so needs to be called before building and posting that notification.

Parameters
@NonNull Context context

May be used to access system services. A reference will not be kept after this call returns.

getAnimatedIcon

Added in 1.0.0
public @Nullable Icon getAnimatedIcon()

Get the animated icon that can be used on some surfaces to represent this OngoingActivity. For example, in the WatchFace.

getCategory

Added in 1.0.0
public @Nullable String getCategory()

Get the Category of this OngoingActivity if set, otherwise the category of the corresponding notification.

getContentDescription

Added in 1.1.0-alpha01
public @Nullable String getContentDescription()

Get the content description of this OngoingActivity if set.

getLocusId

Added in 1.0.0
public @Nullable LocusIdCompat getLocusId()

Get the LocusId of this OngoingActivity, this can be used by the launcher to identify the corresponding launcher item and display it accordingly. If not set, returns the one in the corresponding Notification.

getNotificationId

Added in 1.0.0
public int getNotificationId()

Get the notificationId of the notification associated with this OngoingActivity.

getOngoingActivityId

Added in 1.0.0
public int getOngoingActivityId()

Get the id to this OngoingActivity. This id is used to reference it in recoverOngoingActivity

getStaticIcon

Added in 1.0.0
public @NonNull Icon getStaticIcon()

Get the static icon that can be used on some surfaces to represent this OngoingActivity. For example in the WatchFace in ambient mode. If not set, returns the small icon of the corresponding Notification.

getStatus

Added in 1.0.0
public @Nullable Status getStatus()

Get the status of this ongoing activity, the status may be displayed on the UI to show progress of the Ongoing Activity. If not set, returns the content text of the corresponding Notification.

getTag

Added in 1.0.0
public @Nullable String getTag()

Get the tag of the notification associated with this OngoingActivity, or null if there is none.

getTimestamp

Added in 1.0.0
public long getTimestamp()

Get the time (in elapsedRealtime time) the OngoingActivity was built.

getTitle

Added in 1.0.0
public @Nullable String getTitle()

Get the title of this OngoingActivity if set.

getTouchIntent

Added in 1.0.0
public @NonNull PendingIntent getTouchIntent()

Get the intent to be used to go back to the activity when the user interacts with the Ongoing Activity in other surfaces (for example, taps the Icon on the WatchFace). If not set, returns the touch intent of the corresponding Notification.

recoverOngoingActivity

Added in 1.0.0
public static @Nullable OngoingActivity recoverOngoingActivity(@NonNull Context context)

Convenience method for clients that don’t want to / can’t store the OngoingActivity instance. Note that if there is more than one Ongoing Activity active you have not guarantee over which one you get, you need to use one of the other variations of this method.

Parameters
@NonNull Context context

May be used to access system services. A reference will not be kept after this call returns.

Returns
@Nullable OngoingActivity

the Ongoing Activity or null if not found

recoverOngoingActivity

Added in 1.0.0
public static @Nullable OngoingActivity recoverOngoingActivity(
    @NonNull Context context,
    @NonNull Predicate<OngoingActivity> filter
)

Convenience method for clients that don’t want to / can’t store the OngoingActivity instance.

Parameters
@NonNull Context context

May be used to access system services. A reference will not be kept after this call returns.

@NonNull Predicate<OngoingActivity> filter

used to find the required OngoingActivity.

Returns
@Nullable OngoingActivity

the Ongoing Activity or null if not found

recoverOngoingActivity

Added in 1.0.0
public static @Nullable OngoingActivity recoverOngoingActivity(@NonNull Context context, int ongoingActivityId)

Convenience method for clients that don’t want to / can’t store the OngoingActivity instance.

Parameters
@NonNull Context context

May be used to access system services. A reference will not be kept after this call returns.

int ongoingActivityId

the id of the Ongoing Activity to retrieve, set in setOngoingActivityId

Returns
@Nullable OngoingActivity

the Ongoing Activity or null if not found

update

Added in 1.0.0
@RequiresPermission(value = Manifest.permission.POST_NOTIFICATIONS)
public void update(@NonNull Context context, @NonNull Status status)

Update the status of this Ongoing Activity. Note that this may post the notification updated with the new information.

Parameters
@NonNull Context context

May be used to access system services. A reference will not be kept after this call returns.

@NonNull Status status

The new status of this Ongoing Activity.