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 image:

To listen for these events and customize the handling logic, the super app must implement the GRVCollectEventDelegate protocol. This guide covers the default user experience, implementation steps, and protocol details.

Before you begin

To listen for the favorite and unfavorite events, ensure that the integrated iOS IAPMiniProgram SDK is version 2.65.3 or later. For more information, see SDK release notes.

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:

Procedure

To listen for favorite and unfavorite events, take the following two steps:

Step 1: Implement the GRVCollectEventDelegate protocol

Define a class that implements the GRVCollectEventDelegate protocol. Within the class, optionally implement its defined methods to customize event handling. Refer to the following code for a sample implementation. For more information about the protocol and the methods, refer to GRVCollectEventDelegate.

class DemoCollectEventDelegate: NSObject, GRVCollectEventDelegate {
    func statusWillChange(_ scene: GRVCollectScene, isCollected: Bool, continueCallback: @escaping GRVCollectEventDispositionBlock, cancelCallback: @escaping GRVCollectEventDispositionBlock) {
        // Customize logic to approve or block the favorite/unfavorite action
        // Call continueCallback() to proceed or cancelCallback() to block
    }
    
    func statusDidChanged(_ scene: GRVCollectScene, isCollected: Bool) {
        // Customize logic to handle successful favorite/unfavorite actions
        // Example: Show a custom confirmation message
    }
    
    func statusChangedError(_ scene: GRVCollectScene, error: any Error) {
        // Customize logic to handle errors
        // Example: Display an error alert
    }
}

Step 2: Configure the collectEventDelegate property

After initializing the SDK, create an instance of GRVExtensionDelegate and assign the implementation (for example, DemoCollectEventDelegate in the sample) to the delegate's collectEventDelegate property. Refer to the following sample configuration code:

let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.collectEventDelegate = DemoCollectEventDelegate();

Structures

GRVCollectEventDelegate protocol

The GRVCollectEventDelegate protocol 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 protocol definition:

typedef NS_ENUM(NSUInteger, GRVCollectScene) {
    GRVCollectSceneTitleBar,
    GRVCollectSceneMoreMenu,
};

typedef NS_ENUM(NSUInteger, GRVCollectErrorCode) {
    GRVErrorCodeCollectReachedLimit = -1
};

FOUNDATION_EXPORT NSErrorDomain const NSErrorDomainCollectReachedLimit;
typedef void(^GRVCollectEventDispositionBlock)(void);

@protocol GRVCollectEventDelegate<NSObject>

@optional
- (void)statusWillChange:(GRVCollectScene)scene
             isCollected:(bool)isCollected
        continueCallback:(GRVCollectEventDispositionBlock)continueCallback
          cancelCallback:(GRVCollectEventDispositionBlock)cancelCallback;
- (void)statusDidChanged:(GRVCollectScene)scene isCollected:(bool)isCollected;
- (void)statusChangedError:(GRVCollectScene)scene error:(NSError *)error;

@end

The following table lists the details of the defined methods:

statusWillChange:isCollected:continueCallback:cancelCallback: method

Parameters

This method has the following input parameters:

statusDidChanged:isCollected: method

Parameters

This method has the following input parameters:

statusChangedError:error: method

Parameters

This method has the following input parameters:

Error codes