Customize settings view

The super app can customize the appearance of the settings view of mini programs to ensure a consistent user experience. The settings view appears when a mini program invokes the my.openSetting JSAPI, allowing users to view and manage permissions that have been granted to the mini program, even if those permissions have been revoked later.

Default user interface

By default, the settings view is full-screen and displays permissions along with toggle switches for managing them. The following figure shows an example of the default UI:

image

Before you begin

To customize the user interface for the settings view, ensure that the integrated iOS IAPMiniProgram SDK is version 2.67.0 or later. For more information, see SDK release notes.

Procedure

To customize the settings view, take the following two steps:

Step 1: Implement GRVAppSettingsDelegate

Define a class that implements the GRVAppSettingsDelegate protocol. Within the class, implement the openAppSettings method to customize a settings view. Refer to the following code for a sample implementation. For more information about the protocol and its defined method, refer to GRVAppSettingsDelegate.

copy
class DemoAppSettingsImpl: NSObject, GRVAppSettingsDelegate {

    func openAppSettings(with param: GRVAppSettingsParam, proxy: any GRVAppSettingsProxy) {
        // Implement the logic to build a custom settings view
    }
}

Step 2: Configure appSettingsDelegate

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

copy
let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.uiProvider.appSettingsDelegate = DemoAppSettingsImpl()

Protocol

GRVAppSettingsDelegate

The GRVAppSettingsDelegate protocol defines a method for the super app to customize the settings view, which the SDK then calls to render the custom view. Refer to the following code for the protocol definition:

copy
@protocol GRVAppSettingsDelegate <NSObject>

- (void)openAppSettingsWithParam:(GRVAppSettingsParam *)param
                           proxy:(id<GRVAppSettingsProxy>)proxy;

@end

The following table lists the details of the defined method:

Method

Required

Description

openAppSettingsWithParam:proxy:

Yes

Called by the SDK to render a custom settings view. For more information, refer to openAppSettingsWithParam:proxy:.

openAppSettingsWithParam:proxy:

The openAppSettingsWithParam:proxy: method has the following input parameters whose values are passed by the SDK:

Parameter

Data type

Required

Description

param

GRVAppSettingsParam object

Yes

An object that contains the configuration for a custom settings view.

proxy

id<GRVAppSettingsProxy>

Yes

A proxy that handles a permission change, returning the details of the updated permission. For more information about the return value, refer to GRVAppSettingsProxy.

GRVAppSettingsParam

The GRVAppSettingsParam object is defined as follows:

copy
@class GRVAppSettingsItem;
@interface GRVAppSettingsParam : NSObject

@property (nonatomic, weak) UIViewController *currentViewController;
@property (nonatomic, copy) NSString *appId;
@property (nonatomic, copy) NSString *appName;
@property (nonatomic, copy) NSArray<GRVAppSettingsItem *> *items;

@end

#pragma mark - GRVAppSettingsItem

@interface GRVAppSettingsItem : NSObject
@property (nonatomic, assign) GRVAuthItemType authType;
@property (nonatomic, copy) NSString *permissionName;
@property (nonatomic, assign, getter=isEnabled) BOOL enabled;

@end

The following table lists the parameter details of this object:

Parameter

Data type

Required

Description

currentViewController

UIViewController

No

A weak reference to the view controller that displays and manages the date picker. The SDK typically passes this controller, but it might become deallocated.

appId

NSString

Yes

The unique ID of the mini program.

appName

NSString

Yes

The mini program name.

items

NSArray<GRVAppSettingsItem *>

Yes

A list of permissions ever granted to the mini program, along with their current statuses.

GRVAppSettingsItem

Parameter

Data type

Required

Description

authType

GRVAuthItemType

Yes

The internal permission name that is defined in the code.

permissionName

NSString

Yes

The permission name that is displayed to users.

enabled

BOOL

Yes

Indicates whether the mini program has access to the specified permission. Valid values are:

  • YES: The mini program has access.
  • NO: The mini program has no access.
GRVAppSettingsProxy

The GRVAppSettingsProxy protocol is defined as follows:

copy
@protocol GRVAppSettingsProxy <NSObject>

- (void)updateAuthItemForType:(GRVAuthItemType)authType
                    isEnabled:(BOOL)isEnabled
                        appId:(NSString *)appId;

@end

The following table lists the parameter details of this protocol:

Parameter

Data type

Required

Description

authType

GRVAuthItemType

Yes

The internal permission name that is defined in the code.

isEnabled

BOOL

Yes

Indicates whether the user grants the specified mini program access to the specified permission. Valid values are:

  • YES: The user grants access.
  • NO: The user cancels access.

appId

NSString

Yes

The unique ID of the mini program.