Xiaomi Super Island push

Prerequisites

Before using the Xiaomi Super Island feature, complete the following prerequisites:

1. Integrate the SDK and the Xiaomi vendor channel by following the instructions in Android SDK Integration and Xiaomi Vendor Channel Integration.

2. Activate the Xiaomi Super Island service on the Mi Push portal by following the instructions in Activate Xiaomi Super Island Service.

3. Apply for permission to send Focus Notifications by email as described in the FAQ.

4. You have applied for a channel_id on the Mi Push portal to send pushes to Super Island, as described in Channel Application and Access Method.

5. Design the display template and prepare the image assets referenced in the template by following the Xiaomi Super Island Development Guide and the template library.

Key concepts

Xiaomi Super Island provides a persistent space to display important information about ongoing services, helping users quickly track progress and take action. Its technical architecture builds on the Focus Notification feature, extending its capabilities.

Display formats

Xiaomi Super Island switches between a summary state and an expanded state. It supports multiple display locations, including a large island, a small island, the lock screen, the notification shade, and the Always-On Display (AOD). Users can view or interact with ongoing service information through taps, swipes, pull-down windows, and drag-to-share gestures.

Version support

• Xiaomi HyperOS 2 supports Focus Notification, which is displayed in the status bar, notification center, lock screen, Always-On Display (AOD), and the outer screen of foldable devices.

• Xiaomi HyperOS 3 supports Xiaomi Super Island notifications, which include the island summary state, the island expanded state, and all Focus Notification display locations except for the status bar.

Ensure compatibility across different system versions by selecting a template or sending different data payloads based on the OS version. To determine the Xiaomi HyperOS system version, see the Development Guide.

Display examples

The following image shows an example of a Focus Notification:

The following image shows an example of a Super Island:

Use cases

Xiaomi Super Island is ideal for ongoing, user-focused services that have a clear start and end, a finite lifecycle, and high user engagement. Examples include ride-hailing, food pickup and delivery, package tracking, queuing, device charging, and navigation. It is not suitable for marketing, advertising, long-running persistent information, or purely informational content without clear progress updates.

Client configuration

Add the following meta-data configuration to your app's AndroidManifest.xml file:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
       
        <meta-data
            android:name="com.xiaomi.xms.APP_ID"
            android:value="your app id here" />
            
        <meta-data
            android:name="com.xiaomi.xms.BUILD_TYPE_DEBUG"
            android:value="true or false" />
   
    </application>
</manifest>

For more details, see Integration and Joint Testing.

Manage a Super Island locally

When your app process is active, you can create a Super Island notification just as you would a native Android notification. Write the island parameters to the notification'sextras by using themiui.focus.param key. Pass image resources by usingmiui.focus.pic_*, and set click actions by usingmiui.focus.action_*. For details on specific fields and templates, see the Xiaomi Development Guide.

// Get the NotificationManager object.
Context context = getApplicationContext();
String channelId = "test_channel";
int notificationId = 1;
NotificationManager notificationManager = (NotificationManager) context.getSystemService(NOTIFICATION_SERVICE);

// Create a notification channel. If one already exists, you can reuse it without creating a new one.
NotificationChannel channel = new NotificationChannel(channelId, "test_channel_name", NotificationManager.IMPORTANCE_HIGH);
notificationManager.createNotificationChannel(channel);

// Build the island notification parameters.
String islandParams = """
{ 
    // OS2/OS3
    "param_v2": {
        "protocol": 1,
        // Business scenario, for example, "taxi" for ride-hailing.
        "business":"taxi",
        "enableFloat": true,
        "updatable": true,
        // Status bar data.
        "ticker": "ticker",
        "tickerPic": "miui.focus.pic_ticker",
        // Always-On Display (AOD) data.
        "aodTitle": "aodTitle",
        "aodPic": "miui.focus.pic_aod",
        // Island data.
        "param_island": {
            "islandProperty": 1,
            // Big island data.
            "bigIslandArea": {
                // Big island Area A.
                "imageTextInfoLeft": {
                    "type": 1,
                    "picInfo": {
                        "type": 1,
                        "pic": "miui.focus.pic_imageText"
                    },
                    "miui.focus.paramtextInfo": {
                        "frontTitle": "Charging",
                        "title": "24%",
                        "content": "5 min left",
                        "useHighLight": false
                    }
                },
                // Big island Area B.
                "picInfo": {
                    "type": 1,
                    "pic": "miui.focus.pic_imageText"
                }
            },
            // Small island.
            "smallIslandArea": {
                "picInfo": {
                    "type": 1,
                    "pic": "miui.focus.pic_imageText"
                }
            },
            // Share data.
            "shareData": {
                "title": "share_title"
            }
        },
        // Focus Notification data.
        "baseInfo": {
            "title": "Ready for pickup",
            "content": "Cainiao Post, Shop 8, Zone 2, Anning Huating",
            "colorTitle": "#006EFF",
            "type": 2
        },
        "hintInfo": {
            "type": 1,
            "title": "2 packages",
            "actionInfo": {
                "action": "miui.focus.action_test"
            }
        },
        "extraInfo": {
            "carType": "YU7",
            "carColor": "White"
        }
    }
}
""";

// Create the notification.
Notification notification = new Notification.Builder(context, channelId)
    .setContentTitle(testTitle)
    .setContentText(testText)
    .setSmallIcon(smallIconResId)
    .build();

Bundle bundle = new Bundle();
// Add Action data.
Bundle actions = new Bundle();
Intent intent = new Intent(ACTION_FOCUS_NOTIFICATION);
PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent2, PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE)
Notification.Action action = new Notification.Action
        .Builder(Icon.createWithResource(this, R.drawable.xxxx), "xxx", pendingIntent)
        .build();
actions.putParcelable("miui.focus.action_test", action);

bundle.putBundle("miui.focus.actions", actions);

// Add image data.
Bundle pics = new Bundle();
pics.putParcelable("miui.focus.pic_imageText", Icon.createWithResource(this, R.drawable.xxx));
pics.putParcelable("miui.focus.pic_highlight", Icon.createWithResource(this, R.drawable.xxx));
bundle.putBundle("miui.focus.pics", pics);

builder.addExtras(bundle);
Notification notification = builder.build();
// Add island parameters.    
notification.extras.putString("miui.focus.param", islandParams);
// Send the notification.
notificationManager.notify(notificationId, notification);

To clear a Super Island notification created locally on the client, call the native Android APInotificationManager.cancel(notificationId).

Manage a Super Island remotely by using APIs

Use the Mobile Push Push or MassPush API to remotely create, update, and end Xiaomi Super Island notifications.

Parameter settings

When calling the API, note the following key parameters:

• PushType (Required): This must be set toNOTICE when pushing a Super Island notification.

• AndroidNotificationNotifyId (Required): A unique identifier for the notification. You must use the same NotifyId to create, update, and end a given Super Island notification.

• AndroidNotificationXiaomiChannel (Required): Thechannel_id that you applied for on the Mi Push portal.

• AndroidPopupActivity, AndroidPopupTitle, and AndroidPopupBody (Required): Used for the fallback display of regular notifications and to handle click-throughs. For AndroidPopupActivity, refer to Auxiliary Pop-up Integration to complete the integration.

• AndroidXiaomiFocusParam (Required): A JSON string that specifies the parameters for Xiaomi Super Island. This parameter corresponds to Xiaomi's miui.focus.param. To end the Xiaomi Super Island, set cancel to true. The maximum size of this parameter is 3072 bytes.

• AndroidXiaomiFocusPics (Optional): Specifies the image parameters for Xiaomi Super Island as a JSON string. The key ismiui.focus.pic_*, and the value is an HTTPS image URL. This parameter cannot exceed 1,024 bytes. If you specify this parameter, you must also specify AndroidXiaomiFocusParam.

The AndroidXiaomiFocusParam value is a JSON string whose root node is typically param_v2. The following table describes key parameters, using a path-based format to show the hierarchy. For example,param_v2 is a first-level parameter, andparam_v2.xxx is a second-level parameter under it. For the structure of other template components likebaseInfo andhintInfo, see the Xiaomi Super Island Notification Template Library.

The following is an example of the AndroidXiaomiFocusPics structure:

{
    "miui.focus.pic_ticker": "https://example.com/ticker.jpg",
    "miui.focus.pic_aod": "https://example.com/aod.jpg",
    "miui.focus.pic_imageText": "https://example.com/imageText.jpg"
}

Images must meet the following requirements:

• Data usage for downloading images is attributed to your app.

• Images cannot exceed 100 KB. Larger images will fail to download.

• The image download process times out after 180 seconds.

• Image URLs must use HTTPS. Downloads from non-HTTPS URLs will fail.

• The aspect ratio of the image must be between 1.78 (16:9) and 1 (1:1).

• A notification can contain up to 10 images. If you specify more, only the first 10 are downloaded.

Code examples

PushRequest pushRequest = new PushRequest();
// Basic parameters.
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("ANDROID");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);

// Set parameters to create the Super Island remotely.
pushRequest.setAndroidNotificationNotifyId(1);
pushRequest.setAndroidNotificationXiaomiChannel("130626");
pushRequest.setAndroidPopupTitle("Ready for pickup");
pushRequest.setAndroidPopupBody("Cainiao Post, Shop 8, Zone 2, Anning Huating");
// The activity to launch when the fallback notification is tapped. Requires auxiliary pop-up integration.
pushRequest.setAndroidPopupActivity("xx.YourAndroidPopupActivity");

String createFocusParam = """
{
    "param_v2": {
        "protocol": 1,
        "business": "taxi",
        "enableFloat": true,
        "updatable": true,
        "orderId": "A580202509130712",
        "sequence": 1,
        "ticker": "ticker",
        "tickerPic": "miui.focus.pic_ticker",
        "aodTitle": "aodTitle",
        "aodPic": "miui.focus.pic_aod",
        "param_island": {
            "islandProperty": 1,
            "bigIslandArea": {
                "imageTextInfoLeft": {
                    "type": 1,
                    "picInfo": {
                        "type": 1,
                        "pic": "miui.focus.pic_imageText"
                    },
                    "miui.focus.paramtextInfo": {
                        "frontTitle": "Charging",
                        "title": "24%",
                        "content": "5 min left",
                        "useHighLight": false
                    }
                },
                "picInfo": {
                    "type": 1,
                    "pic": "miui.focus.pic_imageText"
                }
            },
            "smallIslandArea": {
                "picInfo": {
                    "type": 1,
                    "pic": "miui.focus.pic_imageText"
                }
            },
            "shareData": {
                "title": "share_title"
            }
        },
        "baseInfo": {
            "title": "Ready for pickup",
            "content": "Cainiao Post, Shop 8, Zone 2, Anning Huating",
            "colorTitle": "#006EFF",
            "type": 2
        },
        "hintInfo": {
            "type": 1,
            "title": "2 packages",
            "actioninfo": {
                "actionIcon": "miui.focus.pic_hint",
                "actionTitle": "XX",
                "actionTitleColor": "#FF0000",
                "actionBColor": "#00FF00",
                "actionIntentType": 1,
                "actionIntent": "XXXX"
            }
        }
    }
}
""";
pushRequest.setAndroidXiaomiFocusParam(createFocusParam);

String focusPics = """
{
    "miui.focus.pic_ticker": "https://example.com/ticker.jpg",
    "miui.focus.pic_aod": "https://example.com/aod.jpg",
    "miui.focus.pic_imageText": "https://example.com/imageText.jpg",
    "miui.focus.pic_hint": "https://example.com/hint.jpg"
}
""";
pushRequest.setAndroidXiaomiFocusPics(focusPics);

PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n",
        pushResponse.getRequestId(), pushResponse.getMessageId());

PushRequest pushRequest = new PushRequest();
// Basic parameters.
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("ANDROID");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);

// Set parameters to update the Super Island remotely.
pushRequest.setAndroidNotificationNotifyId(1);
pushRequest.setAndroidNotificationXiaomiChannel("130626");
pushRequest.setAndroidPopupTitle("Picked up");
pushRequest.setAndroidPopupBody("Cainiao Post, Shop 8, Zone 2, Anning Huating");
// The activity to launch when the fallback notification is tapped. Requires auxiliary pop-up integration.
pushRequest.setAndroidPopupActivity("xx.YourAndroidPopupActivity");

String updateFocusParam = """
{
    "param_v2": {
        "protocol": 1,
        "business": "taxi",
        "enableFloat": true,
        "updatable": true,
        "orderId": "A580202509130712",
        "sequence": 2,
        "ticker": "ticker",
        "tickerPic": "miui.focus.pic_ticker",
        "aodTitle": "aodTitle",
        "aodPic": "miui.focus.pic_aod",
        "param_island": {
            "islandProperty": 1,
            "bigIslandArea": {
                "imageTextInfoLeft": {
                    "type": 1,
                    "picInfo": {
                        "type": 1,
                        "pic": "miui.focus.pic_imageText"
                    },
                    "miui.focus.paramtextInfo": {
                        "frontTitle": "Charging",
                        "title": "24%",
                        "content": "5 min left",
                        "useHighLight": false
                    }
                },
                "picInfo": {
                    "type": 1,
                    "pic": "miui.focus.pic_imageText"
                }
            },
            "smallIslandArea": {
                "picInfo": {
                    "type": 1,
                    "pic": "miui.focus.pic_imageText"
                }
            },
            "shareData": {
                "title": "share_title"
            }
        },
        "baseInfo": {
            "title": "Picked up",
            "content": "Cainiao Post, Shop 8, Zone 2, Anning Huating",
            "colorTitle": "#006EFF",
            "type": 2
        },
        "hintInfo": {
            "type": 1,
            "title": "2 packages",
            "actioninfo": {
                "actionIcon": "miui.focus.pic_hint",
                "actionTitle": "XX",
                "actionTitleColor": "#FF0000",
                "actionBColor": "#00FF00",
                "actionIntentType": 1,
                "actionIntent": "XXXX"
            }
        }
    }
}
""";
pushRequest.setAndroidXiaomiFocusParam(updateFocusParam);

String focusPics = """
{
    "miui.focus.pic_ticker": "https://example.com/ticker.jpg",
    "miui.focus.pic_aod": "https://example.com/aod.jpg",
    "miui.focus.pic_imageText": "https://example.com/imageText.jpg",
    "miui.focus.pic_hint": "https://example.com/hint.jpg"
}
""";
pushRequest.setAndroidXiaomiFocusPics(focusPics);

PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n",
        pushResponse.getRequestId(), pushResponse.getMessageId());

PushRequest pushRequest = new PushRequest();
// Basic parameters.
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("ANDROID");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);

// Set parameters to end the Super Island remotely.
pushRequest.setAndroidNotificationNotifyId(1);
pushRequest.setAndroidNotificationXiaomiChannel("130626");
pushRequest.setAndroidPopupTitle("Ended");
pushRequest.setAndroidPopupBody("This service is complete.");
// The activity to launch when the fallback notification is tapped. Requires auxiliary pop-up integration.
pushRequest.setAndroidPopupActivity("xx.YourAndroidPopupActivity");

String stopFocusParam = """
{
    "param_v2": {
        "business": "taxi",
        "cancel": true,
        "orderId": "A580202509130712",
        "sequence": 3
    }
}
""";
pushRequest.setAndroidXiaomiFocusParam(stopFocusParam);

PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n",
        pushResponse.getRequestId(), pushResponse.getMessageId());

PushV2 API parameter mapping

When using the PushV2 API, the corresponding fields are located underPushTask.Notification.Android.Options.Xiaomi:

• Channel: Corresponds to the AndroidNotificationXiaomiChannel parameter in the Push API.

• FocusParam: Corresponds to the AndroidXiaomiFocusParam parameter in the Push API.

• FocusPics: Corresponds to the AndroidXiaomiFocusPics parameter in the Push API.

When sending a Super Island notification by using the PushV2 API, you must also specifyPushTask.Notification.Android.NotifyId,PushTask.Notification.Android.VendorChannelActivity,PushTask.Notification.Title, andPushTask.Notification.Body.

Limitations

1. Super Island display priority is based on trigger time, with newer notifications taking precedence over older ones.

2. By default, the island's expanded state collapses after 5 seconds.

3. If no dismissal logic is set, a fallback logic is triggered: the island disappears after 1 hour, and the notification card disappears after 12 hours.

4. The notification shade can display an unlimited number of Focus Notification cards, which are shown in a flat, uncollapsed list.

5. Adaptation for foldable devices or phones with a rear screen is not required because it is handled by Xiaomi.

6. Drag-to-share is supported for WeChat, QQ, SMS, and browsers. The recommended shared content is "text + link," for example, "I'm using XX ride hailing + URL".

For other limitations, see the FAQ.

Troubleshooting

Failed to create a Super Island

1. Verify that you have activated the Xiaomi Super Island service on the Mi Push portal as described in Activate Xiaomi Super Island Service.

2. Check whether you have applied for Focus Notification permission by email as described in the FAQ.

3. Use hasFocusPermission to check whether Focus Notification permission is enabled for your app.

4. Use the message ID and device ID to trace the Super Island push delivery path on the Troubleshoot Message page of the troubleshooting tool in the Mobile Push console.

Failed to update a Super Island

1. Check whether theAndroidNotificationNotifyId parameter used for the update is the same as the one used for creation.

2. Use the message ID and device ID to trace the Super Island push delivery path on the Troubleshoot Message page of the troubleshooting tool in the Mobile Push console.

Failed to end a Super Island

1. Check whether theAndroidNotificationNotifyId parameter used to end the island is the same as the one used for creation.

2. Check whether thecancel parameter is set totrue.

3. Use the message ID and device ID to trace the Super Island push delivery path on the Troubleshoot Message page of the troubleshooting tool in the Mobile Push console.