SuperApp:Manage miniapps in Superapp

Overview

This topic describes the best practices for managing miniapps in Superapp in the following scenarios:

• Search for miniapps.

• Display miniapps in recommended booths.

• Add miniapps to favorites.

• Obtain recently used miniapps.

Scenarios

• Search for specific miniapps or fetch all miniapps on a client

  • Introduction

    This section describes how to quickly search for specific miniapps or fetch all miniapps on a client.

  • Solution details

    Application Open Platform provides ready-to-use API operations that used to search for miniapps on clients, and offers container API operations for miniapps. If you want to fetch all miniapps, you can directly call a specific API operation without the need to specify a keyword.

    

  • API reference

    • You can call an API operation to search for specific miniapps. For more information, see "Search for specific miniapps" in the SDK Open APIs section of this topic.

    • You can call an API operation to fetch the data of all miniapps. For more information, see "Fetch all miniapps" in the SDK Open APIs section of this topic.

• Display miniapps in recommended booths

  • Introduction

    This section describes how to use the fixed recommended booths for miniapps in Superapp to facilitate the inbound marketing of specific miniapps.

  • Solution details

    In Superapp, the logic used to display the recommended booths for miniapps is automatically implemented. You can use the booth management service of Superapp to integrate the Application Open Platform API to find online apps.

    

  • API reference

    You can call API operations in the booth management service to display miniapps in recommended booths. For more information, see "Query the miniapps on a client" and "Query the metadata of published miniapps" in the SuperApp Channel Management Open APIs section of this topic.

• Add miniapps to favorites

  • Introduction

    This section describes how to add miniapps to your favorites. This way, you can quickly start the miniapps.

  • Solution details

    When you integrate containers, implement the service provider interfaces (SPIs) that are used to add miniapps to favorites.

    

  • API reference

    • You can call an API operation on a client to add a miniapp to favorites. For more information, see "Add a miniapp to favorites" in the SDK Open APIs section of this topic.

    • You can call an API operation on a server to query the metadata of miniapps. For more information, see "Query the metadata of published miniapps" in the SuperApp Channel Management Open APIs section of this topic.

• Obtain recently used miniapps

  • Introduction

    This section describes how to obtain the list of recently used miniapps.

  • Solution details

    Integrate container miniapps to enable event SPIs.

    

  • API reference

    • You can call an API operation on a client to save a miniapp to recents. For more information, see "Save a miniapp to recents" in the SDK Open APIs section of this topic.

    • You can call an API operation on a server to query the metadata of miniapps. For more information, see "Query the metadata of published miniapps" in the SuperApp Channel Management Open APIs section of this topic.

Open APIs

• SuperApp Channel Management Open APIs

  The SuperApp Channel Management Open APIs are Channel-level backend service interfaces provided by the Application Open Platform, using the target APP's AccessKey and SecretKey for signing and verification.

• Request Header Construction

Request header params

The request header contains the following fields

Signature generation method

1. First, obtain the app's accessKey and secretKey from the SuperApp Open Platform.Specify the following properties that are used to construct the content to be signed:

   • HTTP_URI : e.g. /openapi/v1/channel/miniapp/search

   • X-Access-Key: 46b1cac78ed94ca4b99ad6de550a****

   • X-Request-Timestamp: 1676904384074

   • HTTP_BODY : The following code provides an example of an HTTP request body:

     {
       "after": "0", # The first page starts from "0", and the starting position of the next page refers to the "after" field in the returned result.
       "limit": 10, # The number of miniapps that you want to query.
       "keyWord": "demo" # The keyword for the query.
     }

2. Construct the content to be signed in the following format based on the preceding information: <HTTP_METHOD> <HTTP_URI>\n<HTTP_BODY>.<Request-Time>.<Access-Key>

   POST /openapi/v1/channel/miniapp/search
   {
     "after": "0",
     "limit": 10,
     "keyWord": "demo"
   }.1676904384074.46b1cac78ed94ca4b99ad6de550a****
   

3. Use the HmacSHA1 algorithm to generate a signature.

   The following code provides an example on how to add a signature to a request:

   import org.apache.commons.lang3.StringUtils;
   import javax.crypto.Mac;
   import javax.crypto.spec.SecretKeySpec;
   import java.nio.charset.StandardCharsets;
   import java.security.InvalidKeyException;
   import java.security.NoSuchAlgorithmException;
   import java.util.Base64;
   
   public class SignDemo {
   
       private static final char[] HEX = new char[] {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd',
           'e', 'f'};
   
       public static String sign(String requestURI, String accessKey, String secretKey, Long requestTime,
                                 String requestBody) {
           String content = String.format("POST %s\n%s.%s.%s", requestURI, requestBody, requestTime, accessKey);
           String signed = generateSign(content, secretKey, "HmacSHA1");
           return Base64.getEncoder().encodeToString(signed.getBytes(StandardCharsets.UTF_8));
       }
   
       public static String generateSign(String content, String key, String algorithm) {
           if (!StringUtils.isEmpty(algorithm) && !StringUtils.isEmpty(content) && null != key) {
               try {
                   SecretKeySpec signinKey = new SecretKeySpec(key.getBytes(), algorithm);
                   Mac mac = Mac.getInstance(algorithm);
                   mac.init(signinKey);
                   byte[] rawHmac = mac.doFinal(content.getBytes());
                   return convertToHex(rawHmac);
               } catch (InvalidKeyException | NoSuchAlgorithmException var6) {
                   return "";
               }
           } else {
               return "";
           }
       }
   
       public static String convertToHex(byte[] bytes) {
           int len = bytes.length;
           StringBuilder buf = new StringBuilder(len * 2);
   
           for (int j = 0; j < len; ++j) {
               buf.append(HEX[bytes[j] >> 4 & 15]);
               buf.append(HEX[bytes[j] & 15]);
           }
           return buf.toString();
       }
   }

4. Send the request

Add X-Access-Key,X-Request-Timestamp and X-Request-Sign to the request header to construct the following request:

curl -X POST \
  https://example.com/openapi/v1/channel/miniapp/search \
  -H 'Content-Type: application/json' \
  -H 'X-Access-Key: 46b1cac78ed94ca4b99ad6de550afb68' \
  -H 'X-Request-Timestamp: 1676904384074' \
  -H 'X-Request-Sign: KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx' \
  -d '{
  "after": "0",
  "limit": 10,
  "keyWord": "demo"
}'

• SuperApp Space Management Open APIs

  The SuperApp Space Management Open APIs are Space-level backend service interfaces provided by the Application Open Platform, based on the Space administrator account's AccessKey and SecretKey for signing and verification. In most cases, these Open-APIs are used to synchronize relevant data in Application Open Platform space.

• Request Header Construction

SuperApp space management openapi signature uses the accessKey and secretKey of first party's space administrator account. Please contact the SuperApp Open Platform operation team to obtain the corresponding values. The request header params and signature generation method is the same as the "SuperApp Channel Management Open APIs"

• SDK Open APIs

  • Add a miniapp to favorites

    • Android

      ServiceManager.getInstance().registerService(IMiniAppFavoriteService.class.getName(), new IMiniAppFavoriteService() {
          @Override
          public void addToFavorites(String appId, ServiceCallback callback) {
              // Add a miniapp to favorites. The result is returned from a callback.
          }
      
          @Override
          public void removeFromFavorites(String appId, ServiceCallback callback) {
              // Remove a miniapp from favorites. The result is returned from a callback.
          }
      
          @Override
          public boolean isFavorite(String appId) {
              // Check whether a miniapp is added to favorites.
              return false;
          }
      });

    • iOS

      [[EMASServiceManager sharedInstance] registerServiceProtocol:@"EMASMiniAppFavoriteService" IMPClass:@"EMASMiniAppFavoriteServiceImpl" target:nil];
      
      
      @implementation EMASMiniAppFavoriteServiceImpl
      
      - (void)addToFavorites:(NSString*)subAppCode completion:(nonnull EMASFavoriteCompletionBlock)completionBlock{
      	 // Add a miniapp to favorites. The result is returned from a block.
      }
      
      - (void)removeFromFavorites:(NSString*)subAppCode completion:(nonnull EMASFavoriteCompletionBlock)completionBlock{
       	 // Remove a miniapp from favorites. The result is returned from a block.
      }
      
      - (BOOL)isFavorite:(NSString*)subAppCode {
         // Check whether a miniapp is added to favorites.
         return NO;
      }
      
      @end

  • Save a miniapp to recents

    • Android

      IMiniAppService miniAppService = ServiceManager.getInstance().getService(IMiniAppService.class.getName());
      if (miniAppService != null) {
          miniAppService.openMiniApp(mItemView.getContext(), ((MiniAppInfo) data).getAppId(), null, new OnOpenMiniAppListener() {
              @Override
              public void onOpenMiniApp() {
                  
              }
      
              @Override
              public void onOpenSuccess(String appId) {
                  // Save a miniapp to recents when the miniapp is started.
              }
      
              @Override
              public void onOpenFailed(String appId, int errorCode) {
                  
              }
          });
      }

    • iOS

      id<EMASMiniAppService> miniAppService = [[EMASServiceManager sharedInstance] serviceForProtocol:@"EMASMiniAppService"];
      
      if (miniAppService) {
        [miniAppService openMiniApp:appId openConfiguration:nil completionBlock:^(int resultCode, NSDictionary * _Nonnull resultDict) {
           // If the value of resultCode is 200, the miniapp is started.
           // Save the miniapp to recents.
        }];
      
      }
      

  • Query the metadata of miniapps

    Note

    If you want to obtain the real-time metadata of a miniapp from a client, you can call the container API operation.

    • Android

      IMiniAppService miniAppService = ServiceManager.getInstance().getService(IMiniAppService.class.getName());
      if (miniAppService != null) {
          // The appIds parameter specifies the IDs of miniapps whose metadata you want to query.
          miniAppService.getMiniAppInfos(this, appIds, new OnGetMiniAppsListener() {
              @Override
              public void onSuccess(List<MiniAppInfo> miniAppInfos) {
                  // The metadata of the miniapps is returned.
              }
      
              @Override
              public void onFailed(int errorCode) {
      
              }
          });
      }

    • iOS

      id<EMASMiniAppService> miniAppService = [[EMASServiceManager sharedInstance] serviceForProtocol:@"EMASMiniAppService"];
      
      if (miniAppService) {
         // The appIds parameter specifies the IDs of miniapps whose metadata you want to query.
        [miniAppService getMiniAppInfo:appIds completionBlock:^(int resultCode, NSArray * _Nonnull miniApps) {
           // If the value of resultCode is 200, miniapp metadata is queried.
           // The metadata of the miniapps is returned.
        }];
      }

  • Search for specific miniapps

    • Android

      IMiniAppService miniAppService = ServiceManager.getInstance().getService(IMiniAppService.class.getName());
      if (miniAppService != null) {
          // The keyword for the query.
          miniAppService.queryMiniApps(this, keyword, new OnQueryMiniAppsListener() {
              @Override
              public void onSuccess(List<MiniAppInfo> miniAppInfos, String anchor) {
                  // The search results are returned. By default, a maximum of 10 miniapps can be obtained. The anchor parameter is used to obtain more miniapps.
              }
      
              @Override
              public void onFailed(int errorCode) {
      
              }
          });
      }

    • iOS

      id<EMASMiniAppService> miniAppService = [[EMASServiceManager sharedInstance] serviceForProtocol:@"EMASMiniAppService"];
      
      if (miniAppService) {
         // The keyword parameter specifies the search keyword. The default value of anchor is 0.
        [miniAppService queryMiniApps:keyword anchor:anchor completionBlock:^(int resultCode, NSArray * _Nonnull miniApps, NSString *anchor) {
       		// If the value of resultCode is 200, the search succeeds.	
          // The search results are returned. By default, a maximum of 10 miniapps can be obtained. The anchor parameter is used to obtain more miniapps.
        }];
      }

  • Fetch all miniapps

    • Android

      IMiniAppService miniAppService = ServiceManager.getInstance().getService(IMiniAppService.class.getName());
       if (miniAppService != null) {
          // Leave keyword empty.
          miniAppService.getMiniAppList(this, new OnGetMiniAppsListener() {
              @Override
              public void onSuccess(List<MiniAppInfo> miniAppInfos, String anchor) {
                  // A list of miniapps is returned. By default, a maximum of 10 miniapps can be obtained. The anchor parameter is used to obtain more miniapps.
              }
      
              @Override
              public void onFailed(int errorCode) {
      
              }
          });
       }

    • iOS

      id<EMASMiniAppService> miniAppService = [[EMASServiceManager sharedInstance] serviceForProtocol:@"EMASMiniAppService"];
      
      if (miniAppService) {
         // The default value of the anchor parameter is 0.
        [miniAppService getMiniAppList:anchor completionBlock:^(int resultCode, NSArray * _Nonnull miniApps, NSString *anchor) {
        	 // If the value of resultCode is 200, all miniapps are fetched.
           // A list of miniapps is returned. By default, a maximum of 10 miniapps can be obtained. The anchor parameter is used to obtain more miniapps.
        }];
      }

Terms