Listen for favorite/unfavorite events
The super app can listen for the favorite and unfavorite events to trigger custom logic when a user adds or removes a mini program from their favorites. These events are tied to a favorite/unfavorite button, which can appear in the following locations:
- The title bar
- The more menu
For a visual reference, refer to the following images:
Button in the title bar | Button in the more menu |
|
|
To listen for these events and customize the handling logic, the super app must implement the CollectEventExtension interface. This guide covers the default user experience, implementation steps, and interface details.
Default user experience
By default, a toast message appears to confirm the user's action when they click a favorite/unfavorite button. Refer to the following table for UI examples:
Favorite a mini program | Unfavorite a mini program | Error |
|
|
|
Before you begin
To listen for the favorite and unfavorite events, ensure that the integrated Android IAPMiniProgram SDK is version 2.65.7 or later. For more information, see SDK release notes.
Procedure
To listen for favorite and unfavorite events, take the following two steps:
Step 1: Implement the CollectEventExtension interface
Define a class that implements the CollectEventExtension interface. Within the class, optionally implement its methods to customize event handling. Refer to the following code for a sample implementation. For more information about the interface and its defined methods, refer to CollectEventExtension.
class CustomCollectEventExtensionImpl : CollectEventExtension {
override fun onStatusChangeBefore(
menuType: String,
isCollected: Boolean,
callBack: ItemDispositionCallBack
) {
if (!isCollected) {
// Show dialog for unfavorite confirmation
} else {
// Show dialog for favorite confirmation
}
}
override fun onStatusChanged(menuType: String, isCollected: Boolean): StatusChangedHandleType {
if (isCollected) {
// Show success toast
return StatusChangedHandleType.SiteCustom
}
return StatusChangedHandleType.ContainerHandle
}
override fun onStatusChangedError(
menuType: String,
errorCode: Int,
errorMessage: String
): StatusChangedHandleType {
// Show error toast
return StatusChangedHandleType.SiteCustom
}
}Step 2: Register the implementation class
After initializing the SDK, call the registerExtension API to register the implementation class (for example, CustomCollectEventExtensionImpl in the sample) with the SDK. Refer to the following sample registration code:
IAPConnect.init(application, initConfig, object : InitCallback {
fun onSuccess() {
//···
Griver.registerExtension(
GriverExtensionManifest(
CollectEventExtension::class.java,
CustomCollectEventExtensionImpl()
)
)
}
})Structures
CollectEventExtension interface
The CollectEventExtension interface defines methods to handle favorite and unfavorite events in different UI contexts. It allows custom logic execution both before and after the action. Refer to the following code for the interface definition:
interface CollectEventExtension : GriverExtension {
@StringDef(
CollectEventExtension.MenuType.TYPE_TITLE_BAR,
CollectEventExtension.MenuType.TYPE_MORE_MENU
)
annotation class MenuType {
companion object {
const val TYPE_TITLE_BAR: String = "TitleBarCollect"
const val TYPE_MORE_MENU: String = "MoreMenuCollect"
}
}
enum class StatusChangedHandleType {
ContainerHandle,
SiteCustom,
}
fun onStatusChangeBefore(
@CollectEventExtension.MenuType menuType: String,
isCollected: Boolean,
callBack: ItemDispositionCallBack
) {
callBack.continueDisposition()
}
fun onStatusChanged(
@CollectEventExtension.MenuType menuType: String,
isCollected: Boolean
): StatusChangedHandleType {
return StatusChangedHandleType.ContainerHandle
}
fun onStatusChangedError(
@CollectEventExtension.MenuType menuType: String,
errorCode: Int,
errorMessage: String?
): StatusChangedHandleType {
return StatusChangedHandleType.ContainerHandle
}
}Based on the definition, this interface provides the following methods:
Method | Description |
onStatusChangeBefore | Called by the SDK when the user taps the favorite/unfavorite button. It allows you to conditionally allow or block the operation (e.g., ask for user confirmation before execution). For more information, refer to |
onStatusChanged | Called by the SDK after a successful favorite/unfavorite action. For more information, refer to |
onStatusChangedError | Called by the SDK when the favorite/unfavorite action fails. For more information, refer to |
onStatusChangeBefore method
Parameters
The method has the following input parameters:
Parameter | Data type | Required | Description |
menuType | String | Yes | The UI context where the event occurs. Valid values are:
|
isCollected | Boolean | Yes | The user's intended action. Valid values are:
|
callBack | ItemDispositionCallBack | Yes | A callback to execute the following methods to allow or block the user's intended action:
|
onStatusChanged method
Parameters
The method has the following input parameters:
Parameter | Data type | Required | Description |
menuType | String | Yes | The UI context where the event occurs. Valid values are:
|
isCollected | Boolean | Yes | The current favoriting status of the mini program. Valid values are:
|
Return value
Data type | Required | Description |
CollectEventExtension.StatusChangedHandleType | Yes | Indicates how the event is handled. Valid values are:
|
onStatusChangedError method
Parameters
The method has the following input parameters:
Parameter | Data type | Required | Description |
menuType | String | Yes | The UI context where the event occurs. Valid values are:
|
errorCode | Int | Yes | A numeric code that represents a specific error. For more information, refer to Error codes. |
errorMessage | String | Yes | The corresponding error message. For more information, refer to Error codes. |
Return value
Data type | Required | Description |
CollectEventExtension.StatusChangedHandleType | Yes | Indicates how the event is handled. Valid values are:
|
Error codes
Error code | Error message | Further action |
-1 | You've reached the max quantity of favorites | A possible solution is to prompt the user to remove existing favorited mini programs. |