Advanced push configuration

In this section, we will see what kind of advanced configurations you can make for your Push Notifications.

But beforehand, please keep in mind that for Android Oreo or Pie, some advanced configurations (like Custom Sound) aren't available because of the Android restrictions. You should use a Custom Notification Channel or change some settings from an existing one.

Notification Channels

With Android 8.0, a new feature called Notification Channels has appeared. An application targeting API Level 26 or higher needs to add support to notifications channels or notifications will not be displayed. The Accengage SDK supports this feature since versions 3.5.4 and 3.6.1.

Our SDK includes 6 presets of channels to use our notifications without any efforts. For more informations, please follow our User Documentation. Our presets of channels are created only when receiving a corresponding notification. If you do not want to display our presets of channels, create your own channel and do not use ours.

Add a new Notification Channel

Just follow the Android documentation. You will need to use the correct channel identifier when configuring messages in Accengage User Interface.

Edit an existing preset

You can edit existing presets of channels by overriding correct strings in resource file. For each channel you can edit following options:

Use the following prefix for corresponding channels:

For exemple, our configuration of the General Information channel:

strings.xml

<!-- Channel : acc_general -->
<string name="acc_channel_general_name">General Information</string>
<string name="acc_channel_general_desc"></string>
<!-- MIN(1), LOW(2), DEFAULT(3), HIGH(4) -->
<string name="acc_channel_general_importance">3</string>
<string name="acc_channel_general_led">true</string>
<string name="acc_channel_general_led_color">#ffffff</string>
<string name="acc_channel_general_vibration">true</string>
<!-- VISIBILITY_SECRET(-1), VISIBILITY_PRIVATE(0), VISIBILITY_PUBLIC(1) -->
<string name="acc_channel_general_lockscreen_visibility">1</string>
<!-- default, none, resource name -->
<string name="acc_channel_general_sound">default</string>
<string name="acc_channel_general_bypass_dnd">false</string>
<string name="acc_channel_general_badge">true</string>

Rich Push

The Rich Push for Android is a push notification on which a click opens the SDK activity with a webview to display a content of the Rich push URL.

It is possible to customise some widgets of the Rich Push Activity. Below you can find its default template:

• for layout
• for layout-land-v21

You can customise each element but you need to keep the type of the widget (Button, ToggleButton, etc...) and the same id. You can also remove widgets from the layout but the WebView widget is mandatory.Below you can find it's default template

For more details, check out the use case Removing the control panel for Rich Push <span class="confluence-embedded-file-wrapper" style="display: float-l";>

Notification Sound

If you want to add a custom sound for your notifications, please add your mp3 file in the res/raw folder of your application. Then, provide the file name (without the extension) in the Accengage User Interface.

Push Actions

Push actions are actions the SDK executes after clicking on the notification. They must be chosen via Accengage dashboard on the page editing push notifications. Push actions can be classified by three categories:

• By click zone
• By action type
• By opening way

This classification is needed to better understand how the SDK handles This method prevent the displayactions of push notifications.

With the action you can also pass custom parameters. Please check out the section Retrieving Message Parameters to get to know how to obtain your custom parameters in the application.

By click zone

Depending on the click area (content or buttons) of notification, push actions can be divided into two types:

Content Action

Button Action

By action type

There are 7 different action types available for push notifications:

• Webview
• Browser
• URL-scheme (deep linking)
• Click-to-mail
• Click-to-phone
• Click-to-Play store
• Click-to-SMS

All of these 7 types you can use as a Button Action and only the first 3 as a Content Action.

By opening way

An activity handling corresponding action type (webview activity, browser activity, deep linking activity, etc) can be launched by two different ways:

• attached to the application
• detached from the application

"Attached" means that after clicking on the Back button from the goal activity you will be returned to your application even if it was in background or not started. For "Detached" action you will be returned to the previous place (activity) which you had before at the moment by clicking on the push notification. In this case the SDK doesn't resume the app activities from background or launch the main activity if the app wasn't started.

Attached Actions

The SDK before handling an "attached" action resumes the last activity or the main one if the app is not launched. If for some reasons after resuming the activity you don't want to display immediately an another one executing your attached action, you may use the SDK method:

A4S.get(mContext).setPushNotificationLocked(true);

This method prevents the display of activities executing the attached actions. To enable the processing of the attached actions you need to call:

A4S.get(mContext).setPushNotificationLocked(false);

Check out our advanced use case - "Display rich push after splash screen" for more details.

Notifications Templates

Default templates

The SDK provides 3 default templates which you can use for your notifications.

Big text

Use this template when you have short or long text to display without an image. You can also use buttons for it.

Android 4.1+

Collapsed

Expanded

Android 5+

Collapsed

Expanded

Android 7+

Collapsed

Expanded

BigText uses default Android notification templates. They could be found on android.googlesource.com. For instance, collapsed and expanded templates for Android 7.1.1_r9 are presented on the table below:

Big picture

Use this template when the notification contains a short text and a picture. Sizes for Big Picture are minimum - 512x256, balanced - 1024x512 and maximum - 2048x1024. You can also use buttons for it.

Android 4.1+

Collapsed

Expanded

Android 5+

Collapsed

Expanded

Android 7+

Collapsed

Expanded

BigPicture uses default Android notification templates. They could be found on android.googlesource.com. For instance, collapsed and expanded templates for Android 7.1.1_r9 are presented on the table below:

Big text Big picture

With the last default template you can use a long text and a picture at the same time. Buttons are disabled for this template.

Android 4.1+

Collapsed

Expanded

Android 5+

Collapsed

Expanded

Android 7+

Collapsed

Expanded

BigTextBigPicture uses default Android templates for a collapsed view and the custom SDK template for an expanded view.

Custom templates

Among the default templates you can also create your own ones to use them for Accengage push notifications. For this you need:

1. Create collapsed and expanded templates in Android Studio for your project
2. Add names of created templates on the Settings page of Accengage dashboard
3. Select corresponding templates on the page editing your push notification

1) Creating collapsed and expanded templates

To display notification content (title, messages, pictures, etc) your custom collapsed/expanded templates should contain such views:

Below there are custom collapsed and expanded layouts extracted from Android Open Sources demonstrating where normally should be located these views.

Android 4.1+

Collapsed layout

• acc_notification_template_material_base

Android 5+

Collapsed layout

• acc_notification_template_material_base

  • acc_notification_template_icon_group
  • acc_notification_template_part_line1
  • acc_notification_template_part_line2
  • acc_notification_template_part_line3

Android 7+

Collapsed layout

• acc_notification_template_material_base

  • acc_notification_template_header
  • acc_notification_template_part_line1
  • acc_notification_template_text

Expanded layout

• acc_notification_template_material_big_picture

  • acc_notification_template_material_base
  • acc_notification_action_list

Expanded layout

• acc_notification_template_material_big_picture

  • acc_notification_template_material_base
  • acc_notification_template_icon_group
  • acc_notification_template_part_line1
  • acc_notification_template_part_line2
  • acc_notification_template_part_line3
  • acc_notification_material_action_list

Expanded layout

• acc_notification_template_material_big_picture

  • acc_notification_template_header
  • acc_notification_template_right_icon
  • acc_notification_template_part_line1
  • acc_notification_template_text
  • acc_notification_material_action_list

These layouts are already presented in the SDK. To test them you just need to add layout names ( acc_notification_template_material_base and acc_notification_template_material_big_picture ) on the Settings page of Accengage dashboard. If you want to modify certain elements (for instance, background color or position), copy these templates to the project and change their names, then you can customize layouts views according to your needs.

2) Add names of created templates on the Settings page of Accengage dashboard

Once your custom templates have been added into your project. It's necessary to add names of expanded and collapsed templates on the Settings page.

3) Select corresponding templates on the page editing your push notification

Now you can use the custom collapsed and expanded templates added previously on the Settings page for your push notification.

Collapsed template

Expanded template

Interactive Buttons

Since the SDK 3.3.0 and Android 4.1 (API 16), you can add interactive buttons for notifications with BigText and BigPicture templates.

Predefined button icons

The list of predefined icons which you can use in Accengage dashboard without integrating them into your app is presented below:

Icon name	Icon 16+ (Holo)	Icon 21+ (Material Design)
com_ad4screen_sdk_notification_icon_call
com_ad4screen_sdk_notification_icon_later
com_ad4screen_sdk_notification_icon_less
com_ad4screen_sdk_notification_icon_man
com_ad4screen_sdk_notification_icon_more
com_ad4screen_sdk_notification_icon_no
com_ad4screen_sdk_notification_icon_rate
com_ad4screen_sdk_notification_icon_share
com_ad4screen_sdk_notification_icon_thumb_down
com_ad4screen_sdk_notification_icon_thumb_up
com_ad4screen_sdk_notification_icon_women
com_ad4screen_sdk_notification_icon_yes

Add your own icons

For other icons you would like to use please add them in drawable folders of the app for each density (mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi).

• For Android 16+, the icon needs to be white and should be placed in drawable-density-16 folders (where density can be mdpi, hdpi, xhdpi, ...)
• For Android 21+, the icon needs to be grey and should be placed in drawable-density-21 folders (where density can be mdpi, hdpi, xhdpi, ...)

To find more icons, click on the following link: http://icons4android.com/

Notifications Icons

By default, we are using your launcher icon as a logo for your notifications. Since Android 4.4, Google guidelines require  a  white and transparent flat icon . If you don't follow the guide lines your notification icon may look like on the images below (Android 4.4+ and Android 7+).

Android <4.4

Android 4.4+

Android 7+

Android 4.4+

To fix this you need to add a notification icon compliant with Google guidelines in your drawable resources and specify it in your strings.xml file:

strings.xml

<resources>
    // ...
    <string name="acc_notification_icon">your_icon_name</string>
</resources>

Please note that "youriconname" is the name of the icon without extension and/or path. For instance, if you want to use drawable/icactionsearch.png, please replace "youriconname" by "icactionsearch".

Try notification icon generator to create your Material Design Notification icons.

Example of white and transparent notification icon

Android 4.4+

Android 5+

From the version Android 5 (Lollipop) you may:

• change an accent color in a circle behind your icon image
• use a large notification icon

Accent Color

There are two ways to set an accent color:

Android 5+

Android 7+

1. Statically, in the strings.xml file:

   strings.xml

   <resources>
       // ...
       <string name="acc_notification_accent_color">#0000ff</string>
   </resources>

2. Dynamically, via Accengage dashboard in custom parameters of push notification

   

Your accent color can be set in ARGB/RGB format, or in a color name format, for instance bleu.

Large Notification Icon

If you want to use a large notification icon as shown on the images below, you need:

• either add a thumbnail via Accengage dashboard

  

• or set programmatically by overriding getLargeIcon or getLargeIconUrl methods of NotificationClientCreator class.

Android <5

Android 5+

Android 7+

Note that the small icon is added automatically and the image source is:

• either your launcher icon
• or the icon specified in the strings.xml file in the accnotificationicon parameter.

Back Stack

This part shows how activities of your application can be organised on the task's back stack while handling notifications (pushes and alarms) by the SDK. The position of your activities on the task's back stack depends on the launchMode, flags, and other parameters described here and as a result it also depends on the pushs, the way they are going to be opened: attached or detached to/from the app.

Attached push actions

Attached push actions are handled by using application activities (inheriting A4SActivity or integrating directly A4S API methods). The actions are normally handled in an existing task of the application but if it is not existed (the application is not started or closed) a new task will be created, where the main activity is launched on the top of it to handle notification action.

Ex.1 Back stack and webview

In this example the back stack contains a task with 3 activities before clicking on a notification. After clicking on a notification with a rich push URL the SDK starts the internal webview activity in the same task.

Ex.2 Back stack and deeplink (case 1)

This example shows how the SDK launches an activity (Activity B) using a deeplink.

Ex.3 Back stack and deeplink (case 2)

This is the same example as the previous one but the activity we are going to launch using a deeplink is the last activity in the task. If the launchMode for this activity in your manifest file is "standard", a new instance of the activity will be created.

Ex.4 Back stack and deeplink (case 3)

This is the same example as the previous one but the launchMode for deep linking activity is "singleTop".

Ex.5 Empty back stack and webview or deeplink

The procedures of handling notifications with rich push URL or deeplinks demonstrated above are the same for the empty back stack. There is only one difference: the SDK launches the main activity (launcher activity) instead of resuming the last activity in the task.

Detached push actions

Detached push actions are handled in a new task (see FLAG_ACTIVITY_MULTIPLE_TASK) by internal activity provided by the SDK. Since an action is handled in a new task, application's activities (if they are existed) won't be resumed. It allows to return quickly to the place where the notification was opened without popping recent activities of the application from the back stack.

Ex.1 Back stack and Browser or deeplink (case1)

Ex.2 Back stack and deeplink (case 2)

In case if a notification starts an activity with a launchMode 'singleTask' or 'singleInstance' using a deeplink and there is no such activity in the back stack, the activity will be started in a new task.

Ex.3 Back stack and deeplink (case 3)

In case if a notification starts an activity with a launchMode 'singleTask' or 'singleInstance' using a deeplink and the activity is already existed in the back stack, this activity will be resumed by calling onNewIntent.

Customizing the back stack

Since the version 3.5.1 of the SDK you can also customize the back stack at runtime. There are two additional callbacks in NotificationClientCreator: getTaskStackBuilder and getTaskStackBuilderForButton. Using these two methods you can specify activities you would like to have in the back stack after opening a notification.

Customising notifications at Runtime

Starting with the Accengage SDK 3.5.0, you can customise notifications at runtime.

For this, create a class that implements com.ad4screen.sdk.service.modules.push.NotificationClientCreator:

import com.ad4screen.sdk.service.modules.push.NotificationClientCreator;

public class MyNotificationClientCreator implements NotificationClientCreator {

    /**
    * Gets an instance of TaskStackBuilder representing the back stack which will be used after clicking on the notification.
    * If null is returned {@link #getMainIntent(Context context, Bundle customParams)} will be called.
    * @param context Context of the Accengage process
    * @param customParams Customs params of the notification (include all data of the notification like title, content, etc...)
    * @return TaskStackBuilder to retrieve intents of activities arranged in the back stack.
    */
    @Override
    public TaskStackBuilder getTaskStackBuilder(Context context, Bundle customParams) {
    Log.info("MyNotificationClientCreator|getTaskStackBuilder called, bundle = " + customParams.toString());
        return null;
    }

    /**
    * Gets an instance of TaskStackBuilder representing the back stack which will be used after clicking on the notification
    * button. If null is returned {@link #getIntentForButton(Context context, int indexButton, Bundle customParams)} will be called.
    * @param context Context of the Accengage process
    * @param indexButton ID of the notification button
    * @param customParams Customs params of the notification (include all data of the notification like title, content, etc...)
    * @return TaskStackBuilder to retrieve intents of activities arranged in the back stack.
    */
    @Override
    public TaskStackBuilder getTaskStackBuilderForButton(Context context, int indexButton, Bundle customParams) {
        Log.info("MyNotificationClientCreator|getTaskStackBuilderForButton called with index " + indexButton +
            ", bundle = " + customParams.toString());
        return null;
    }

    /**
     * Intent used when notification is clicked. Extras will be added to manage tracking and Rich Push display.
     * Your Intent need to target an Activity with the SDK integrated or the tracking and Rich Push display will be lost.
     *
     * @param context      Context of the Accengage process
     * @param customParams Customs params of the notification (include all data of the notification like title, content, etc...)
     * @return The Intent to use or null (in this case, the default Intent will be used)
     */
    @Override
    public Intent getMainIntent(Context context, Bundle customParams) {
        Log.info("MyNotificationClientCreator|getMainIntent called");
        return null;
    }

    /**
     * Intent used when notification button is clicked. Extras will be added to manage tracking and Rich Push display.
     * Your Intent need to target an Activity with the SDK integrated or the tracking and Rich Push display will be lost.
     *
     * @param context      Context of the Accengage process
     * @param customParams Customs params of the notification button
     * @return The Intent to use or null (in this case, the default Intent will be used)
     */
    @Override
    public Intent getIntentForButton(Context context, int indexButton, Bundle customParams) {
        Log.info("MyNotificationClientCreator|getIntentForButton with index " + indexButton + " called");
        return null;
    }

    /**
     * Image used as logo of the notification. You can provid an URL with {@link #getLargeIconUrl(Context, Bundle)}.
     * Note: If this method return something different of null, {@link #getLargeIconUrl(Context, Bundle)} will not be used.
     *
     * @param context      Context of the Accengage process
     * @param customParams Customs params of the notification (include all data of the notification like title, content, etc...)
     * @return Bitmap of the logo or null
     */
    @Override
    public Bitmap getLargeIcon(Context context, Bundle customParams) {
        Log.info("MyNotificationClientCreator|getLargeIcon called");
        return null;
    }

    /**
     * Url that will be used to download the logo of the notification.
     * Note: This method is called only if {@link #getLargeIcon(Context, Bundle)} returns null.
     *
     * @param context      Context of the Accengage process
     * @param customParams Customs params of the notification (include all data of the notification like title, content, etc...)
     * @return Url of the logo or null if you want use default SDK logic
     */
    @Override
    public String getLargeIconUrl(Context context, Bundle customParams) {
        Log.info("MyNotificationClientCreator|getLargeIconUrl called");
        return null;
    }

    /**
     * Notification.Builder that will be displayed.
     *
     * @param context      Context of the Accengage process
     * @param notificationBuilder Generated notification builder by the Accengage SDK
     * @param customParams Customs params of the notification (include all data of the notification like title, content, etc...)
     * @return Notification.Builder that will be displayed. Null to use the default Notification.Builder generated by the SDK
     */
    @Override
    public NotificationCompat.Builder getNotificationBuilder(Context context, NotificationCompat.Builder notificationBuilder, Bundle customParams) {
        Log.info("MyNotificationClientCreator|getNotificationBuilder called");
        return null;
    }

    /**
     * Notification that will be displayed. Please be careful when editing this notification
     *
     * @param context      Context of the Accengage process
     * @param notification Generated notification by the Accengage SDK
     * @param customParams Customs params of the notification (include all data of the notification like title, content, etc...)
     * @return Notification that will be displayed. Null to use the default Notification generated by the SDK
     */
    @Override
    public Notification getNotification(Context context, Notification notification, Bundle customParams) {
        Log.info("MyNotificationClientCreator|getNotification called");
        return null;
    }
}

Implement methods like you want. If you want to keep the default values used by the SDK, just return null.

When your class is implemented, add in your Application's onCreate the following line:

A4S.get(this).setNotificationClientCreator(MyNotificationClientCreator.class);