Use mPaaS Xcode Extension

This topic describes how to use the mPaaS Xcode Extension. It covers the following aspects:

• Start mPaaS Xcode Extension

• Create a new project

• Edit a project

• Basic tools

• FAQ

• Preferences settings

• Ratings and reviews

Start mPaaS Xcode Extension

In the Applications folder on your macOS, find the standalone mPaaS application, mPaaSPlugin, and click it to run.

Create a new project

Follow these steps to create a new project based on the mPaaS framework.

1. Click mPaaS > Create Project.

2. Configure the new mPaaS project. Enter a Project Name, import the downloaded .config configuration file, and then click Next.

3. Select a Template type for the application, and then click Next.

4. Select the Baseline type and version for the project, and then click Next.

   Baseline type descriptions:

   • Standard baseline: A public, standard mPaaS software development kit (SDK) version. You can select a version from the drop-down list.

   • Custom baseline: This option is available only to Apsara Stack users. Enter the corresponding baseline ID in the input box for automatic validation. If the validation fails, an error message appears. After a successful validation, you can use the baseline.

5. Select the modules to add to the project, and then click Next.

   Note

   You can also skip adding modules at this step. After the project is created, you can add the required modules using the Edit Project feature. For more information, see the integration document for each component.

   

6. Select a directory to save the project, and then click Create.

7. The project creation process begins. After the project is created, the new Xcode project opens automatically.

Edit a project

Open a project

If you already have an Xcode project, you can open it directly with the plugin. You can drag the project file into the plugin or click the plugin and locate the project file.

Project panel overview

Click mPaaS > Edit Project to open the project editing page. The page is divided into several areas as shown in the following figure.

• 1. Menu bar: Displays all project operation menus.

• 2. Toolbar: Displays common tools and information about the current target.

• 3. Status bar: Displays the path of the project being edited.

• 4. Project structure bar: Displays the project structure, including the workspace, project, and target structure.

• 5. Workspace: The main operation area. The content displayed varies based on the selected editing menu.

• 6. Hide button: Expands or hides the project structure sidebar.

• 7. Switch Project: Opens another project for editing.

• 8. Show: Shows the current project in Finder.

• 9. Close: Closes the project that is being edited.

Import cloud metadata

Click the Import Cloud Metadata menu. Click Select Configuration File and select the downloaded cloud data configuration file. The page displays a preview of the basic information from the configuration file. Click Start Import to import the configuration into the current project.

Project overview

Click the Project Overview menu. The workspace parses the project configuration and displays detailed project information. This includes basic project information, mPaaS baseline information, project status, and application information. The related operations include the following:

• View modules: Click Expand to display a dialog box that shows all the integrated modules.

• Project status:

  • Unknown: Indicates that mPaaS is not integrated or that parsing the information has failed.

  • Not Installed: Indicates that the mPaaS library files are missing and the project cannot run properly. Click Install to complete the installation.

  • Installed: Indicates that the mPaaS library files are installed correctly and the project can run directly.

Edit modules

Click the Edit Modules menu. The workspace displays different pages based on the project properties.

Projects with mPaaS integrated

1. When you edit a project that has mPaaS integrated, the workspace displays a list of modules that are already integrated into the project.

2. Click Modify Modules to open the Module List editing page.

   • In the list, click a module card to add or remove the module.

   • Click Details on the right side of each module to view its specific information. This includes the description, release notes, and details of the included framework files.

   • Click the X in the upper-left corner to close the module list and return to the main page. Your selections will not take effect.

   • Click Save in the upper-right corner to save your edits and return to the main page. The module list in the workspace shows the results of your edits.

3. After you return to the main page, click Start Editing to add the modified modules to or remove them from the current project.

   Note

   The changes take effect only after you click Start Editing.

Native system projects

1. When you edit a native system project, the workspace displays a page indicating that mPaaS is not integrated.

2. Click Add Modules to open the Module List editing page.

   1. The page prompts you to select the Baseline type and version for integration. After you select a baseline and click Confirm, the baseline selection menu collapses. The module list for the corresponding baseline is then displayed.

   2. After you enter the module list, you can click the Select Baseline drop-down menu in the upper-right corner to reselect a baseline version. If you switch baselines, any previously added modules are lost.

   • In the list, click a module card to add the module.

   • Click Details on the right side of each module to view its specific information. This includes the description, release notes, and details of the included framework files.

   • Click the X in the upper-left corner to close the module list and return to the main page. Your selections will not take effect.

   • Click Save in the upper-right corner to save your edits and return to the main page. The module list in the workspace shows the results of your edits.

3. After you return to the main page, click Start Editing to add the modified modules to or remove them from the current project.

   Note

   The changes take effect only after you click Start Editing.

Operations and descriptions for editing modules

• Select Baseline:

  • Standard baseline: A public, standard mPaaS SDK version. You can select a version from the drop-down list.

  • Custom baseline: This option is available only to Apsara Stack users. Enter the corresponding baseline ID in the input box for automatic validation. If the validation fails, an error message appears. After a successful validation, you can use the baseline.

• Modify Modules: Opens the module list to add or delete modules.

• COPY: We recommend that you enable this option. When this option is selected, the dependent SDK files are automatically copied to the project directory.

• Version: The workspace displays the version information of the mPaaS SDK integrated into the current project.

• Start Editing: Executes the module editing operation.

Update the product set

Select Update Product Set and click Start Update to perform the upgrade. The integrated mPaaS SDK product set is updated to the latest version.

The workspace displays information about the current project's product set and the latest product set for the baseline. Click View Module Update Details to open the module list page, where you can view the update status of each module.

Click Details on the right side of each module to view its specific information. This includes the description, release notes, and details of the included framework files.

If the current project has not integrated mPaaS, a prompt page is displayed. We recommend that you first perform the integration in the Edit Modules section.

The operations and explanations for updating the product set are as follows:

• Current Product Set Version: If a product set is integrated, this shows the current product set version. If the project has not integrated a product set, the current baseline version is displayed in the upper-right corner.

• Latest Product Set Version: Displays the version number of the latest product set. The version number structure is "Baseline Version + Product Set Version", such as 10.1.60-beta (20).

• Module Update Count: Indicates the number of modules integrated in the current project that have updates in the latest product set.

• View Module Update Details: Opens the module list page, where you can view the update status of each module.

• View Release Note: Opens the SDK Release Notes document.

• Product Set Update Time: Displays the release time of the latest product set.

• Start Upgrade: Executes the upgrade operation.

Upgrade the baseline

Click the Upgrade Baseline menu, and then click Confirm Upgrade to proceed with the upgrade.

In the baseline selection box, select the baseline type and version. A preview box for the corresponding baseline appears. In the preview, click View Included Module Details to open the module list page. This page shows the module list for the selected baseline and the installation status of the modules.

Click Details on the right side of each module to view its specific information. This includes the description, release notes, and details of the included framework files.

If the current project has not integrated mPaaS, a prompt page is displayed. We recommend that you first perform the integration in the Edit Modules section.

The operations and explanations for upgrading the baseline are as follows:

• Select Baseline:

  • Custom baseline: This option is available only to Apsara Stack users. Enter the corresponding baseline ID in the input box for automatic validation. If the validation fails, an error message appears. After a successful validation, you can use the baseline.

  • Standard baseline: A public, standard mPaaS SDK version. You can select a version from the drop-down list.

• Preview: Displays the baseline type and version. Click View Included Module Details to see the corresponding module list information.

• Confirm Upgrade: Executes the baseline upgrade operation.

After you upgrade the baseline, all mPaaS information in the project is updated. When you upgrade from a version earlier than 10.1.32 to version 10.1.32 or later, the structure of the MPaaS directory and the content in Info.plist change. The details are as follows.

Directory structure changes

Before the upgrade, the MPaaS directory in the project contained component category directories and files. After the upgrade, only APMobileFramework and mPaas are retained. Other directories, such as MPHotpatchSDK and APRemoteLogging, are automatically removed. If you have stored custom files in these directories, you must back them up in advance. For more information about the directory structure, see mPaaS directory structure.

Info.plist changes

Before the upgrade, the mPaaS-related fields inserted in the project's Info.plist file are shown in the following figure.

Because versions 10.1.32 and later require only the Product Version and no longer need the Product ID, mPaaS, or mPaaSInternal fields, the plugin automatically removes these fields after the baseline upgrade. If you find that they are not removed, you must delete them manually. The content after the upgrade is shown in the following figure:

Security Guard

Click the Security Guard menu. On the page, enter information such as the AppSecret, and then click Generate Image to generate the yw_1222.jpg image that is required for RPC signature verification and offline package decryption.The operations and explanations for Security Guard are as follows:

• Default Path: This path shows the default storage location for the Security Guard image in the project.

• App Secret: The private key for Security Guard signature verification. Public cloud users can find this key in the mPaaS console. Apsara Stack users should consult their server-side developers. You can click the help button on the right for more information.

• Type: The type of the Security Guard image, yw_1222.jpg.

  • Standard: Generates a standard Security Guard image. This is the default type.

  • Account Link: Generates a special image for the miniapp Account Link feature.

    Note: After you use this type of Security Guard image, you must perform regression testing on the Account Link and gateway-related features.

• JPG Version: The version number of the Security Guard image yw_1222.jpg. This version depends on the version number of the client's SecurityGuardSDK.framework:

  • If the version number is earlier than 5.3.85, the yw_1222.jpg version number is V4.

  • If the version number is 5.3.85 or later, the yw_1222.jpg version number is V5.

• Generate Image: Click this button to be prompted to select a path to save the image. The default path opens automatically. After you select a path, the operation to generate the Security Guard image is executed.

  Note

  • For public cloud users, the imported meta.config file already contains this image. You generally do not need to regenerate it unless you have special requirements.

  • For Apsara Stack users, use this method to generate the yw_1222.jpg image and add it to your project.

  

Customize keyboard shortcuts

The mPaaS Xcode Extension lets you add custom keyboard shortcuts for mPaaS menus for convenience and personalization. To set them, open Xcode preferences, select Key Binding, and filter by mPaaS, as shown in the following figure.

Basic tools

Click mPaaS > Basic Tools to open the basic tools page, as shown in the following figure. mPaaS provides basic tools for developers, including self-service, hotpatching tools, and packaging and building tools.

Self-service - Log diagnosis tool

You can use the log diagnosis tool to easily troubleshoot problems when you use the mPaaS SDK. Input the problem log, and the tool automatically scans for matching problem causes and provides solutions.

Click the Log Diagnosis Tool icon to open the diagnosis tool page. Enter the problem log in the input box and click Submit to automatically analyze the log.

After the analysis is complete, a diagnostic report page appears. You can view the details of the matched problems.

Operations and descriptions for the log diagnosis tool

• Log input box: Enter the raw log to be scanned. This currently supports client runtime logs.

• Reset: After you submit a task, you can click Reset to query again and resubmit the log in the input box.

• View Full Diagnostic Report: Opens the diagnostic report window, which displays the scan results for the current log.

Hotpatching - Generate a resource package

When you use the hotpatching feature, for security reasons, the .js script file that has passed local testing must be packaged and encrypted before it can be submitted to the publishing platform.

Click the Generate Resource Package icon to open the page for generating a hotpatching resource package. Select the locally tested .js script and the RSA key file, enter the application's App Secret, and click OK to generate the encrypted hotpatching resource package file.

The operations and explanations for generating a resource package are as follows:

• Script File: The .js script that has passed local testing and validation.

• App Secret: The App Secret that corresponds to the application. You can click the help button on the right for more information.

• Private Key File: The existing RSA private key file, which is obtained through OpenSSL. This is the private key file that pairs with the public key file that is added to the project.

• Generate New RSA Key: If you do not have a key file or want to use a new one, you can select this option. The plugin automatically generates a new RSA key pair for you and saves it in the output directory.

• View Output Description: Click this to expand detailed information, as shown in the figure.

Hotpatching - Extract a public key signature

The signature verification and encryption/decryption process for a hotpatching script involves a pair of RSA asymmetric keys and one AES symmetric encryption key. Each application must use its own keys to ensure the security of script delivery. The RSA key verification process requires you to verify the signature of the public key itself in main.m to ensure that the public key file has not been replaced.

Click the Extract Public Key Signature icon to open the page for extracting a hotpatching public key signature. Select the public and private key files that are used to generate the hotpatching package, and click OK to see the extracted signature array on the page. Copy the printed signature array into the main.m method.

The operations and explanations for extracting a public key signature are as follows:

• Public Key File: The RSA public key file used to generate the hotpatching resource package.

• Private Key File: The RSA private key file used to generate the hotpatching resource package.

• Signature Array: Displays the extracted public key signature.

Package an application

The mPaaS plugin provides a one-click packaging feature. You can enter information such as the bundle ID, bundle version, and signing parameters to generate a .ipa installation package. You can use mPaaS release management to upgrade the app and remind users to install the new version.

Click the Package Application icon to open the application packaging page. Fill in all the information on the page and click Start Build to begin the packaging.

The operations and explanations for application packaging are as follows:

• Project Path: Select the directory of the project to be packaged. This is the directory where the project file (.xcodeproj or .xcworkspace) is located.

• Scheme: The name of the target to build.

• Bundle Identifier: The Bundle Identifier of the current project. If the mobile gateway service is added, this must be consistent with the bundleId field in the cloud metadata. Otherwise, mobile gateway signature verification will fail.

• Build Version: The version number of the current project. This should generally be consistent with the Bundle Version in the project's info.plist file.

• CodeSign Identity: The name of the signing certificate. You can import the certificate for signing the current project into Keychain and find its common name.

• Provisioning Profile: The provisioning profile that matches the Bundle Identifier and the signing certificate.

• Configuration: The packaging configuration, either Debug or Release.

• Build For App Store: Specifies whether this is an App Store installation package. If this is checked, the generated .ipa is a package for uploading to the App Store. If this is not checked, the generated .ipa is a development package.

• Start Build: Click this button to be prompted to select a directory for the build output. After you make a selection, the packaging and building process begins. Upon success, the output directory opens automatically.

Resign an application

The mPaaS plugin provides a feature to resign an existing .ipa installation package. This generates a resigned .ipa package that can be installed on more devices for testing and validation.

Click the Resign icon to open the resigning page. Fill in all the information on the page and click OK to start the resigning operation.

The operations and explanations for resigning are as follows:

• IPA Installation Package: An existing .ipa installation package file.

• Certificate Name: The name of the new certificate. You can view it using security find-identity -p codesigning -v ~/Library/Keychains/login.keychain.

• Certificate ID: The ID of the new certificate. You can view the user ID of the corresponding certificate in Keychain.

• Provision File: The provisioning profile that matches the updated certificate.

• OK: Click this button to be prompted to select a directory to save the resigned file. After you make a selection, the resigning operation begins. Upon success, the output directory opens automatically.

FAQ

On the FAQ page, click Start Browsing to open the details page. You can view related frequently asked questions based on the specific component that you are querying.

Preferences settings

After you open the mPaaS Xcode Extension, click the menu mPaaSPlugin > Preferences, or use the keyboard shortcut "⌘ + ," to open the settings window.

General

Configure the diagnostic log retention path: When you use the diagnosis feature, this is the path where the generated log reports are saved. You can select Custom from the drop-down menu to specify a custom log storage directory.

Network

Configure a SOCKS proxy: Check Enable SOCKS Proxy to enable the proxy. Then, enter the address and port of the proxy server in the input boxes.

Ratings and reviews

After you open the mPaaS Xcode Extension, click the badge icon in the lower-left corner of the home page to open the Ratings and Reviews window.

If you started the mPaaS Xcode Extension directly from the Applications folder, you can also open the Ratings and Reviews window through the menu Help > Write a Review.

Submit a rating and review

In the dialog box, click the stars to give a rating, fill in the review title and content, and click Submit to submit your rating and review.

View all reviews

In the dialog box, click View All Reviews to open a new window that displays review data from all users.