SuperApp:How to use the Mini App JsApi white label

The SDK white label feature lets you replace the default WindVane namespace and WV class name prefix with your own identifiers. This ensures that mini app JSAPI calls use your branding instead of WindVane's defaults. To enable this feature, contact us.

Overview

By default, mini apps call JSAPIs using window.WindVane as the namespace and WV as the class name prefix:

const authorize = () =>{
  window.WindVane.call('WVAuthorize', 'authorize', {}, function(e) { ... }, function(e) { ... });
};
document.addEventListener('WV.Event.WVBluetooth.characteristicValueChanged', function(e) { ... }, false);

To replace these defaults with your own identifiers, configure the following three parameters in MiniAppInitConfig.Builder during SDK initialization:

1. setSuperAppNameSpace(String nameSpace) sets the window object name that mini apps use to call JSAPIs. The default value is "WindVane".

2. setJsApiClassNamePrefix(String classNamePrefix) sets a custom class name prefix for JSAPI calls. The default value is "WV".

3. setWindVaneBackwardCompatible(boolean bool) controls whether mini apps can still use the default WindVane namespace and WV prefix. When set to true (the default), old mini apps remain compatible. Set to false after all mini apps have migrated to the custom namespace.

Configure custom namespace and prefix

SDK initialization

Add the three parameters to your MiniAppInitConfig.Builder during SDK initialization:

public static void init() {
    MiniAppInitConfig config = new MiniAppInitConfig.Builder()
            .setUseWindVane(true)
            .setHost("your.host.name")
            .setAppCode("your app code")
            .setAccessKey("your access key")
            .setSecretKey("your secret key")
    
            ...
    
           
            // new config item
            .setWindVaneBackwardCompatible(true)
            .setSuperAppNameSpace("your NameSpace")
            .setJsApiClassNamePrefix("your ClassNamePrefix")
    
            ...
    
            .build();
    IMiniAppService miniAppService = new MiniAppService();
    miniAppService.initialize(application, config);

}

Use cases

The following example sets SuperAppNameSpace to "SuperApp" and JsApiClassNamePrefix to "SA".

public static void init() {
    MiniAppInitConfig config = new MiniAppInitConfig.Builder()
    .setUseWindVane(true)
    .setHost("your.host.name")
    .setAppCode("your app code")
    .setAccessKey("your access key")
    .setSecretKey("your secret key")

    ...

  
    // new config item
    .setWindVaneBackwardCompatible(true)
    .setSuperAppNameSpace("SuperApp")
    .setJsApiClassNamePrefix("SA")

    ...

    .build();
    IMiniAppService miniAppService = new MiniAppService();
    miniAppService.initialize(application, config);

After initialization, compare the JSAPI calls before and after customization. All examples use the window object and event listener pattern to invoke JSAPIs.

// Call jsapi before customization
const authorize = () =>{
  window.WindVane.call('WVAuthorize', 'authorize', {}, function(e) { ... }, function(e) { ... });
};
document.addEventListener('WV.Event.WVBluetooth.characteristicValueChanged', function(e) { ... }, false);

// Call jsapi after customization
const authorize = () =>{
    window.SuperApp.call('SAAuthorize', 'authorize', {}, function(e) { ... }, function(e) { ... });
};
document.addEventListener('SA.Event.SABluetooth.characteristicValueChanged', function(e) {
  ...
}, false);

With namespace set to "SuperApp" and class name prefix set to "SA", the JSAPI calling convention changes as follows: the namespace shifts from WindVane to SuperApp, and the class name prefix shifts from WV to SA.

Configuration scenarios

Choose a configuration based on whether your mini apps still rely on the default WindVane identifiers:

1. If all your mini apps use the default WindVane namespace and WV prefix, no additional configuration is required — the defaults apply.

2. If all your mini apps use a custom namespace and prefix, use the following configuration:

public static void init() {
    MiniAppInitConfig config = new MiniAppInitConfig.Builder()
            ...
    
           
            // new config item
            .setWindVaneBackwardCompatible(false)
            .setSuperAppNameSpace("your NameSpace")
            .setJsApiClassNamePrefix("your ClassNamePrefix")
    
            ...
    
            .build();
    IMiniAppService miniAppService = new MiniAppService();
    miniAppService.initialize(application, config);

}

1. If some mini apps still use the default WindVane namespace and WV prefix while newer mini apps use a custom namespace and prefix,

   use the following configuration:

public static void init() {
    MiniAppInitConfig config = new MiniAppInitConfig.Builder()
            ...
    
           
            // new config item
            .setWindVaneBackwardCompatible(true)
            .setSuperAppNameSpace("your NameSpace")
            .setJsApiClassNamePrefix("your ClassNamePrefix")
    
            ...
    
            .build();
    IMiniAppService miniAppService = new MiniAppService();
    miniAppService.initialize(application, config);

}