Best practices for icon settings

Introduction

This topic provides a comprehensive guide to the best practices for icon settings. It helps developers correctly configure notification icons on different platforms.

Prerequisites

• Make sure that you have created a project and an application in the EMAS console. For more information, see Quick Start.

• You have integrated the required software development kit (SDK). For more information, see Android SDK integration, iOS SDK integration, and HarmonyOS SDK integration.

Android

Image example

Supported versions

The Alibaba Cloud proprietary channel supports this feature starting with SDK version 3.6.0. Vendor channel icons are supported starting with SDK version 3.7.0.

Channel support

Channel	Dynamic small icons	Right-side icon	Large image
Alibaba Cloud proprietary channel	Supported (depends on the mobile operating system)	Supported (depends on the mobile operating system)	Supported (depends on the mobile operating system)
Xiaomi	Not supported	Not supported	Not supported
Huawei	Not supported	Support	Not supported
Honor	Not supported	Supported	Not supported
OPPO	Not supported	Not supported	Not supported
FCM	Not supported	Not supported	Not supported
Meizu	Not supported	Not supported	Not supported
vivo	Not supported	Not supported	Not supported

Technical implementation

Small icon

Client-side

Default behavior

1. Priority mechanism

   The SDK first attempts to use the resource file named R.drawable.alicloud_notification_smallicon in the project as the small icon for the notification.

2. Fallback mechanism

   If the specified resource file is not found, the SDK automatically uses the application's launcher icon as the small notification icon. The launcher icon is the icon configured in AndroidManifest.xml.

Custom configuration

To use a custom small icon, you can call the setNotificationSmallIcon method. The following code provides an example:

CloudPushService cloudPushService = PushServiceFactory.getCloudPushService();
cloudPushService.setNotificationSmallIcon(R.drawable.custom_notification_icon);

Right-side icon/Large image

Server-side

You can set specific parameters on the server-side to display the right-side icon and the large image.

Parameter	Type	Required	Meaning	Description
AndroidImageUrl	string	No	URL of the right-side icon	Currently supported: Huawei EMUI (only in long text mode and Inbox mode). Honor Magic UI (only in long text mode). Proprietary channel: Android SDK 3.5.0 and later. Example: https://example.com/large_icon.png
AndroidBigPictureUrl	string	No	URL of the large image	The image URL in large image mode. Currently supported: Proprietary channel: Android SDK 3.6.0 and later. Example: https://example.com/large_icon.png

The following code provides an example:

PushRequest pushRequest = new PushRequest();
pushRequest.setAndroidImageUrl("https://example.com/large_icon.png");
pushRequest.setAndroidBigPictureUrl("https://example.com/large_icon.png");

iOS

Image examples

Small icon

In your Xcode project, go to the `Images.xcassets-AppIcon` folder. Find the icon slot for iPhone Notification and configure it.

Right-side icon/Large image

Supported versions

This feature is supported on iOS 10 and later with iOS SDK 1.9.5 and later.

Client-side

1. Integrate the Notification Service Extension

• In Xcode, select File > New > Target > Notification Service Extension.

• Name the extension and click Finish to create it.

• After the extension is created, Xcode automatically generates a NotificationService template in the folder.

2. Implement the core logic

In the didReceiveNotificationRequest callback method, you can implement the logic to process the notification before it is displayed. The following code provides an example:

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    
    // Modify the notification content here...
    
    // Modify the notification title to check the display effect.
    self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]", self.bestAttemptContent.title];
    
    // Get the custom key-value field from the notification. Here, get the value for the key 'attachment', which is the URL of the Alibaba Cloud logo image.
    // When pushing from the console or OpenAPI, you must set iOSExtParameters, which carries the 'attachment' key-value pair.
    NSString *picUrlString = self.bestAttemptContent.userInfo[@"attachment"];
    if (picUrlString) {
        NSString *picPath = [[NSHomeDirectory() stringByAppendingPathComponent:@"Documents"] stringByAppendingPathComponent:@"notice_media.png"];
        // Download the image to the local device.
        NSURLSession *session = [NSURLSession sharedSession];
        NSURLSessionDownloadTask *downloadTask = [session downloadTaskWithURL:[NSURL URLWithString:picUrlString] completionHandler:^(NSURL * _Nullable location, NSURLResponse * _Nullable response, NSError * _Nullable error) {
            if (error) {
                self.bestAttemptContent.body = [error description];
            } else {
                NSFileManager *fm = [NSFileManager defaultManager];
                // Save the image to the specified picPath.
                [fm moveItemAtPath:location.path toPath:picPath error:nil];
                // Create a notification attachment.
                UNNotificationAttachment *attachment = [UNNotificationAttachment attachmentWithIdentifier:@"pic" URL:[NSURL URLWithString:[@"file://" stringByAppendingString:picPath]] options:nil error:&error];
                if (error) {
                    self.bestAttemptContent.body = [error description];
                } else if (attachment) {
                    // Add the notification attachment to the notification.
                    self.bestAttemptContent.attachments = @[attachment];
                }
                // Display the modified notification.
                self.contentHandler(self.bestAttemptContent);
            }
        }];
        [downloadTask resume];
    } else {
        // If no resource URL is specified, get the resource from the local device and add it to the notification.
        NSString *picLocalPath = [[NSBundle mainBundle] pathForResource:@"aliyun-logo-local" ofType:@"png"];
        if (picLocalPath) {
            NSError *error;
            UNNotificationAttachment *attachment = [UNNotificationAttachment attachmentWithIdentifier:@"pic" URL:[NSURL URLWithString:[@"file://" stringByAppendingString:picLocalPath]] options:nil error:&error];
            if (error) {
                self.bestAttemptContent.body = [error description];
            } else if (attachment) {
                // Add the attachment to the notification.
                self.bestAttemptContent.attachments = @[attachment];
            }
        }
        // Display the modified notification.
        self.contentHandler(self.bestAttemptContent);
    }
}

Server-side

To display an image, you must configure specific parameters when sending the push notification from the server-side.

Parameter	Type	Required	Meaning	Description
iOSMutableContent	boolean	No	A flag for the iOS notification processing extension (iOS 10+).	If set to true, the APNs push notification is processed by the extension before it is displayed. This must be set to true for silent notifications.
iOSExtParameters	string	No	Extended properties for iOS notifications.	For iOS 10 and later, you can specify the resource URL for a rich push notification here: {"attachment": "https://xxxx.xxx/notification_pic.png"} . This parameter must be passed in JSON map format, otherwise a parsing error will occur.

The following code provides an example:

PushRequest pushRequest = new PushRequest();
pushRequest.setIOSMutableContent(true);
pushRequest.setIOSExtParameters("{\"attachment\": \"https://xxxx.xxx/notification_pic.png\"} "); 

HarmonyOS

Image example

Supported versions

Vendor channel icons are supported starting with SDK version v3.8.2.

Channel support

Channel	Dynamic small icons	Right-side icon	Large image
HarmonyOS	Not supported	Supported	Not supported

Right-side icon

Server-side

You can set specific parameters on the server-side to display the right-side icon.

Parameter	Type	Required	Meaning	Description
HarmonyImageUrl	string	No	The URL for the large icon on the right of the notification. The URL must use the HTTPS protocol. For more information, see the official HarmonyOS documentation for Notification.image.	Supported image formats are PNG, JPG, JPEG, HEIF, GIF, and BMP. The image size (length × width) must be less than 25,000 pixels.

The following code provides an example:

PushRequest pushRequest = new PushRequest();
pushRequest.setHarmonyImageUrl("https://example.com/xxx.png");