Customize user authorization views

2023-10-29 01: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 three steps to customize your authorization views:

Step 1: Implement LocalPermissionDialog

Create a class that implements the LocalPermissionDialog interface to define your custom view. Refer to the following sample code for the implementation:

copy
public class DemoLocalPermissionNoticeDialog implements LocalPermissionDialog {
    private Context context;
    private String content;
    private String name;
    private String iconUrl;
    private List<String> scopes;
    private final Map<String, String> authContentMap = new HashMap<>();
    private PermissionPermitListener listener;

    public DemoLocalPermissionNoticeDialog(Context context) {
        this.context = context;
        authContentMap.put("scope.camera", GriverEnv.getResources().getString(R.string.griver_access_your_camera));
        authContentMap.put("scope.album", GriverEnv.getResources().getString(R.string.griver_access_your_album));
        authContentMap.put("scope.location",GriverEnv.getResources().getString(R.string.griver_access_your_current_location));
    }


    @Override
    public void setDialogContent(String content, String name, String iconUrl) {
        this.content = content;
        this.name = name;
        this.iconUrl = iconUrl;
    }

    @Override
    public void setDialogExtraData(Map<String, String> map) {
        String scope = map.get("scopes");
        if (!TextUtils.isEmpty(scope)) {
            List<String> authScopes = JSON.parseArray(scope, String.class);
            if (authScopes != null) {
                scopes.addAll(authScopes);
            }
        }
    }

    @Override
    public void setPermissionPermitListener(PermissionPermitListener permissionPermitListener) {
        this.listener = permissionPermitListener;
    }

    @Override
    public void show() {
        CreateDialogParam createDialogParam = new CreateDialogParam(name, content,
                context.getString(R.string.griver_core_allow),
                context.getString(R.string.griver_core_deny), null);
        createDialogParam.cancelable = false;
        createDialogParam.positiveListener = new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialogInterface, int i) {
                listener.onSuccess();
            }
        };
        createDialogParam.negativeListener = new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialogInterface, int i) {
                listener.onFailed(-1, context.getString(R.string.griver_core_user_unauthorized), true);
            }
        };
        RVProxy.get(GriverDialogExtension.class).createDialog(GriverEnv.getTopActivity().get(),
                createDialogParam).show();
    }
}

For more information about this interface, refer to LocalPermissionDialog.

Step 2: Implement GriverLocalAuthDialogExtension

Create a class that implements the GriverLocalAuthDialogExtension interface to create a view that is defined in the previous step. Refer to the following sample code for the implementation:

copy
public class GriverLocalAuthDialogExtensionImpl implements GriverLocalAuthDialogExtension {
    @Override
    public LocalPermissionDialog createDialog(Context context) {
        return new DemoLocalPermissionNoticeDialog(context);
    }
}

For more information about this interface, refer to GriverLocalAuthDialogExtension.

Step 3: Register GriverLocalAuthDialogExtension

After the SDK initialization logic, call the registerExtension API to register the implemented GriverLocalAuthDialogExtension interface to the SDK with the following sample code:

copy
Griver.registerExtension(new GriverExtensionManifest(GriverLocalAuthDialogExtension.class, new GriverLocalAuthDialogExtensionImpl()));

For how to call the registerExtension API, refer to registerExtension.

Interfaces

LocalPermissionDialog

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

copy
public interface LocalPermissionDialog {
    void setDialogContent(String content, String name, String iconUrl);
    void setDialogExtraData(Map<String, String> params);
    void setPermissionPermitListener(PermissionPermitListener listener);
    void show(Page page);
}

As we can see from the definition, this interface provides the following four methods:

Method	Description	Required
setDialogContent	The super app uses this method to get the information on a default view and customize the display of a user authorization view. For more information, refer to `setDialogContent`.	M
setDialogExtraData	The super app uses this method to get the information that might be necessary for a user authorization view. For more information, refer to `setDialogExtraData`.	O
setPermissionPermitListener	The super app uses this method to set a listener to handle the user's response on whether they approve or deny the authorization. For more information, refer to `setPermissionPermitListener`.	M
show	The SDK calls this method to show the custom view on the current page when the JSAPI is triggered. For how to specify its parameter, refer to `show`.	M

setDialogContent

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

Field	Data type	Description	Required
content	String	The scope description on the default view. For a visual illustration, refer to User authorization view illustration.	M
name	String	The permission prompt on the default view. For a visual illustration, refer to User authorization view illustration.	M
iconUrl	String	The URL of the icon on the default view. For a visual illustration, refer to User authorization view illustration.	M

setDialogExtraData

The setDialogExtraData method has the following input parameter whose value is passed by the SDK:

Field

Data type

Description

Required

params

Map<String, String>

The additional information of the authorization view. This parameter is specified in key-value pairs with the following valid key:

scopes:RequiredThe scopes that require user authorization when a specific JSAPI is called by mini programs. This key is an array of strings with following valid values:

scope.album: The JSAPI requires access to the user's album.
scope.camera: The JSAPI requires access to the user's camera.
scope.location: The JSAPI requires access to the user's location.

For how the values are assigned, refer to How the scopes parameter is specified.

setPermissionPermitListener

The setPermissionPermitListener method has the following input parameter whose value is passed by the SDK:

Field	Data type	Description	Required
listener	PermissionPermitListener	A listener that captures the user's response on whether they either agree to or cancel the authorization. For more information, refer to PermissionPermitListener.	M

PermissionPermitListener

Method	Description
onSuccess	The super app needs to call this method to notify the SDK when the user approves the authorization.
onFailed	The super app needs to call this method to notify the SDK when the user denies the authorization.

show

The super app needs to specify the following input parameter properly for the show method:

Field	Data type	Description	Required
page	Page	An instance of the current page.	M

GriverLocalAuthDialogExtension

The GriverLocalAuthDialogExtension interface is used to create a user authorization view that is defined by the LocalPermissionDialog interface. The following code shows the definition of this interface:

copy
public interface GriverLocalAuthDialogExtension extends GriverExtension {
    LocalPermissionDialog createDialog(Context context);
}

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

Method	Description	Required
createDialog	The SDK calls this method to create a user authorization view that is defined by the `LocalPermissionDialog` interface. For more information, refer to `createDialog`.	M

createDialog

The createDialog method has the following input parameter whose value is passed by the SDK:

Field	Data type	Description	Required
context	Context	Interface to global information about an application environment.	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: