Customize user authorization views

2023-10-27 11:40

For privacy concerns, IAPMiniProgram SDK shows user authorization views when mini programs call JSAPIs that require access to users' sensitive information. The super app can customize these views to create a user interface that matches your branding and meets the regional regulatory requirements. This topic guides you through how to customize the user authorization view.

Default user experience

If you choose not to provide custom user authorization views, the SDK displays the views in the form of a bottom popup on the screen. You can refer to the following image for an example default view:

Procedures

Take the following two steps to customize your authorization views:

Step 1: Implement GRVAuthDelegate

Create a class that implements the GRVAuthDelegate protocol to define and create a custom user authorization view. Refer to the following sample code for the implementation:

copy
@interface DemoAuthDelegateImpl : NSObject<GRVAuthDelegate>

@end

@implementation DemoAuthDelegateImpl
    
- (void)showAuthWithParam:(GRVAuthParam *)param
currentViewController:(UIViewController*)currentViewController
      positiveAction:(GRVAuthActionBlock _Nullable)positiveAction
        cancelAction:(GRVAuthActionBlock _Nullable)cancelAction 
{
    DemoAuthViewController *authViewController = [[DemoAuthViewController alloc] init];
    authViewController.param = param;
    authViewController.positiveAction = positiveAction;
    authViewController.cancelAction = cancelAction;
    [currentViewController presentViewController:authViewController animated:YES completion:nil];        
}
@end

For more information about this protocol, refer to GRVAuthDelegate.

Step 2: Configure GRVExtensionDelegate

Before the SDK initialization logic, configure GRVExtensionDelegate and register the implemented GRVAuthDelegate protocol to the SDK with the following sample code:

copy
let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.uiProvider.authDelegate = DemoAuthDelegateImpl();

Protocol

GRVAuthDelegate

The GRVAuthDelegate protocol is used to customize the user authorization view that is associated with a specific JSAPI. The following code shows the definition of this protocol:

copy
@protocol GRVAuthDelegate <NSObject>
@required
- (void)showAuthWithParam:(GRVAuthParam *)param
currentViewController:(UIViewController *)currentViewController
      positiveAction:(GRVAuthActionBlock _Nullable)positiveAction
        cancelAction:(GRVAuthActionBlock _Nullable)cancelAction;
@end

As we can see from the above definition, this protocol provides the following method:

Method	Description	Required
showAuthWithParam:currentViewController:positiveAction:cancelAction:	The SDK calls this method to show the custom user authorization view. For more information, refer to `showAuthWithParam:currentViewController:positiveAction:cancelAction:`.	M

showAuthWithParam:currentViewController:positiveAction:cancelAction:

The showAuthWithParam:currentViewController:positiveAction:cancelAction: method has the following parameters:

Field	Data type	Description	Required
param	GRVAuthParam *	The information of a user authorization view. For more information, refer to `GRVAuthParam`.	M
currentViewController	UIViewController *	The current view controller that displays the user authorization view.	M
positiveAction	GRVAuthActionBlock	The callback that is executed when the user approves the authorization.	O
cancelAction	GRVAuthActionBlock	The callback that is executed when the user denies the authorization.	O

GRVAuthParam

The following code shows the definition of the GRVAuthParam interface:

copy
@interface GRVAuthParam : NSObject
@property(nonatomic, copy)NSArray<NSString *> *scopes;
@property(nonatomic, copy)NSString *content;
@property(nonatomic, copy)NSString *title;
@property(nonatomic, strong)UIImage *authIcon;
@property(nonatomic, strong)UIImage *miniProgramLogo;
@property(nonatomic, copy)NSString *miniProgramName;
@end

As we can see from the above code, this interface has the following parameters:

Field	Data type	Description	Required
scopes	NSArray<NSString >	The scopes that require user authorization when calling a specific JSAPI. Valid values are: `Album`: The JSAPI requires access to the user's album. `Camera`: The JSAPI requires access to the user's camera. `Location`: The JSAPI requires access to the user's location. For how the values are assigned, refer to How the scopes parameter is specified.	M
content	NSString *	The scope description on the default view. For a visual illustration, refer to User authorization view illustration.	M
title	NSString *	The permission prompt on the default view. For a visual illustration, refer to User authorization view illustration.	M
authIcon	UIImage *	The URL of the icon on the default view. For a visual illustration, refer to User authorization view illustration.	M
miniProgramLogo	UIImage *	The logo of the mini program that calls the JSAPI and requires access to the specified scopes.	M
miniProgramName	NSString *	The name of the mini program that calls the JSAPI and requires access to the specified scopes.	M

Appendices

How the scopes parameter is specified

IAPMiniProgram SDK specifies the scopes parameter according to the JSAPI's required scopes. However, if a certain scope is authorized by the user for one JSAPI, it does not need repeat authorization for another JSAPI. Therefore, we do not pass the corresponding values for authorized scopes. Refer to the following table for the JSAPIs and their required scopes respectively:

JSAPIs	Required scopes
Location JSAPIs (e.g., my.getLocation)	scope.location
Image JSAPIs (e.g., my.chooseImage)	scope.album, scope.camera
Video JSAPIs (e.g., my.chooseVideo)	scope.album, scope.camera

User authorization view illustration

The following image illustrates the various elements and their positions on a default user authorization view: