Decorator Plugin Development

Overview

Decorator plug-in is responsible for tweaking the notification to provider better experience, such as design polishing, additional functionality and even Android Wear/Auto support.

Decorators from different developers may work in a pipeline to processing the notification one by one, ordered by "priority" attribute, which provide the hint for final ordering. (User will be allowed to re-order the decorators in settings in a future version)

Work Flow

Decorator is implemented by extending NevoDecoratorService class. It has two basic methods:

• apply() receives notification to be processed and applies modifications via various APIs on the "StatusBarNotificationEvo" class.

• onNotificationRemoved() receives the event of notification removal. Nothing can be applied to the notification here. It's commonly used to keep internal state synchronized with notification visibility state.

Limitations

• Notification sound and vibration may be interrupted if not short enough if evolved. We are currently working on a solution.

• Evolved notifications are not automatically removed by the originating app (e.g. when app is opened). This is an API limitation in Android system, we have no proper solution for this at present. It is planned be solved with root privilege in a future version.

• Before Android 6.0, due to platform limitation, the status-bar icon of the original notification can not be reproduced if any part of the notification is altered. We are still working on a proper solution. At present, if the icon is very important for your decorator, please file a feature request with the app name and icon file (preferable vector image xml, or PNG in xxhdpi, extracted from that target app) on the issue tracker. We'll ship the icon with Nevolution app, so your decorator could reproduce the necessary status bar icon in the altered notification.

• If the original notification has delete intent, it is triggered when the notification is decorated (due to removal before re-posting). This may have side effect on the notification behaviors of the originating app. Please test it carefully in decorator development.

• Notification can only be altered, but not removed by 3rd-party decorators at present. It's a design choice to prevent notification loss caused by bugs or mis-configured settings in decorators. If you have different opinion on this decision, please feel free to discuss with us in the community.

Settings UI for Your Decorator (Optional)

For advanced decorator, settings UI provides essential flexibility. Nevolution will show a setting button on the decorator configuration UI, if your decorator declares its own setting activity like this: (code snippet from Bundle decorator)

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.EDIT" />
        <category android:name="android.intent.category.PREFERENCE" />
        <data android:scheme="decorator"
              android:ssp="com.oasisfeng.nevo.decorators.bundle.BundleDecorator" tools:ignore="UnusedAttribute"
              android:host="com.oasisfeng.nevo.decorators.bundle.BundleDecorator" />
    </intent-filter>
</activity>

The action, category and data scheme must be exact the same, while ssp/host should point to your decorator class. Since android:ssp was added in Android 4.4, if your decorator supports Android 4.3, android:host must be provided as an extra alternative for backward compatibility. Settings activity can also be shared by multiple decorators, just declare multiple ssp/host for all the corresponding decorators.

After user changed the settings, you must call Activity.setResult(RESULT_OK) to notify Nevolution to re-process the affected notifications with your decorator.

Additional Action in Nevolution (Optional)

In advanced scenarios, your decorator could provide some special actions for user to invoke on selected notification. These actions are shown as action buttons on the toolbar in Nevolution, only for notifications from the apps your decorated is activated for. (same scope as your decorator itself)

Use the following intent-filter protocol to define the actions within the activity to be started when the action is triggered by user.

<activity ...>
    <intent-filter android:icon="@android:drawable/ic_menu_edit" android:label="@string/decorator_bundle_action">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
        <data android:scheme="decorator"
            android:ssp="com.oasisfeng.nevo.decorators.bundle.BundleDecorator" tools:ignore="UnusedAttribute"
            android:host="com.oasisfeng.nevo.decorators.bundle.BundleDecorator" />
    </intent-filter>
</activity>

The action, category and data are just like the setting activity, except you need to provide an icon and label for the action. The icon should be pure white with alpha transparent background (thus tintable). Currently only activity is supported for action target, if you believe the broadcast or service better suits your decorator, please let us know in the community.

Write an Effective Decorator

TODO