Advanced push configuration
Allowing a content to be displayed in your splashcreen can affect the push behaviour.
For this reason, a method exists to prevent the display of any Accengage content once the splashcreen is loading. Please check the SplashScreen section for more information.
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:
Option | Resource name suffix | Description |
---|---|---|
Name |
*_name | Name of the channel, string |
Description | *_desc | Description of the channel, string |
Importance | *_importance | Importance of the channel, integer Min: 1 / Low: 2 / Default: 3 / High: 4 |
Enable Led | *_led | Enable or disable Led display, boolean true or false |
Led Color | *_led_color | Color of the Led Format #RRGGBB |
Enable Vibration | *_vibration | Enable or disable vibration, boolean true or false |
Lockscreen Visibility | *_lockscreen_visibility | Visibility of the lockscreen, integer Secret: -1 / Private: 0 / Public: 1 |
Sound | *_sound | Sound when notification is displayed none, default or resource name in raw folder |
Bypass Do Not Disturb | *_bypass_dnd | Bypass the Do Not Disturb option, boolean true or false |
Enable Badge | *_badge | Enable or disable badge for this channel, boolean true or false |
Use the following prefix for corresponding channels:
Channel name | Resource name prefix |
---|---|
General Information | acc_channel_general |
Service Messages | acc_channel_service |
News Messages | acc_channel_news |
Urgent Messages | acc_channel_high |
Low priority Messages | acc_channel_low |
Minimum priority Messages | acc_channel_min |
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.
- Content actions are all "attached".
- Button actions are all "detached" except the action type Webview.
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:
View | Template |
---|---|
Collapsed | notification_template_material_base.xml |
Expanded | notification_template_material_big_text.xml |
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:
View | Template |
---|---|
Collapsed | notification_template_material_base.xml |
Expanded | notification_template_material_big_picture.xml |
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.
View | Template |
---|---|
Collapsed | default Android templates for collapsed view |
Expanded |
for API less than API16 default Android templates for Big Text will be used |
Custom templates
Among the default templates you can also create your own ones to use them for Accengage push notifications. For this you need:
- Create collapsed and expanded templates in Android Studio for your project
- Add names of created templates on the Settings page of Accengage dashboard
- 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:
View ID | Type | View | Description | Customized by (Accengage Dashboard controls) |
---|---|---|---|---|
icon | ImageView | Collapsed/Expanded | Large Icon before Android7, Small Icon after Android7 | Thumbnail (<Android7) |
app_name_text | TextView | Collapsed/Expanded | Name of the app (Android7+) | Custom parameters: a4sappname |
header_text | TextView | Collapsed/Expanded | Header (Android7+) | Custom parameters: a4sheadertext |
time | DateTimeView | Collapsed/Expanded | Time of the reception | |
title | TextView | Collapsed/Expanded | Notification title | Title |
text_line_1 | TextView | Collapsed/Expanded | Additional text located on the right side of the title (Android7+) | Custom parameters: a4scontentinfo |
info | TextView | Collapsed/Expanded | Additional Information (before Android7) | Custom parameters: a4scontentinfo |
text | TextView | Collapsed/Expanded | Notification text | Short/Expanded message |
right_icon | ImageView | Collapsed/Expanded | Right Icon (Small Icon before Android7, Large Icon after Android7) | Thumbnail (Android7+) |
big_picture | ImageView | Expanded | Big picture | Picture |
big_picture_2 | ImageView | Expanded | Second big picture (twitter style) | Custom parameters: a4sbigpicture2 |
actions | Layout | Expanded | Action area | Buttons |
action0 | Button | Expanded | Interactive button | currently not supported by the dashboard |
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
Android 5+
Collapsed layout
Android 7+
Collapsed layout
Expanded layout
Expanded layout
Expanded layout
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+
-
Statically, in the strings.xml file:
strings.xml
<resources> // ... <string name="acc_notification_accent_color">#0000ff</string> </resources>
-
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);