Integrate mPaaS into an existing project with CocoaPods

Prerequisites

• CocoaPods 1.0.0 or later is installed, and your project is a CocoaPods project.

• The cocoapods-mPaaS plugin is installed. To install it, run:

  sh <(curl -s http://mpaas-ios.oss-cn-hangzhou.aliyuncs.com/cocoapods/installmPaaSCocoaPodsPlugin.sh)

• An application is created in the console and the .config file is downloaded. Create an application in the console.

Procedure

1. Copy the .config configuration file to the root directory of your project, at the same level as the Podfile.

   Note

   The downloaded .config filename must end with iOS. Rename ios to iOS if needed.

2. Run pod mpaas init to add the plugin, source, and mPaaS_baseline configurations to your Podfile:

    plugin "cocoapods-mPaaS"
    source 'https://gitee.com/mpaas/podspecs.git'
    mPaaS_baseline 'x.x.x'

3. Configure the Podfile.

   1. Set the baseline version in mPaaS_baseline. For example: mPaaS_baseline '10.2.3', where 10.2.3 is the version. Check the release notes for version differences.

   2. Add component dependencies with mPaaS_pod. For example: mPaaS_pod "mPaaS_Nebula", where mPaaS_Nebula is a component name. Available components:

      Component configuration	Applicable baseline	Description
      mPaaS_pod "mPaaS_LocalLog"	10.1.32+	local log
      mPaaS_pod "mPaaS_Log"	10.1.32+	Mobile analysis: Analyzes behavioral, automated, crash, and performance logs.
      mPaaS_pod "mPaaS_Diagnosis"	10.1.32+	Diagnosis: Provides client-side diagnostics.
      mPaaS_pod "mPaaS_RPC"	10.1.32+	Mobile gateway: Provides downloads, uploads, and RPC calls.
      mPaaS_pod "mPaaS_Sync"	10.1.32+	Mobile synchronization: Provides a persistent connection service.
      mPaaS_pod "mPaaS_Push"	10.1.32+	Message push
      mPaaS_pod "mPaaS_Config"	10.1.32+	Remote configuration: Fetches values from the server by key to control client logic.
      mPaaS_pod "mPaaS_Upgrade"	10.1.32+	Application upgrade: Upgrade checks, phased rollouts, and version notifications.
      mPaaS_pod "mPaaS_Share"	10.1.32+	Share: Lets you share text and images to popular channels like Weibo, DingTalk, and Alipay.
      mPaaS_pod "mPaaS_Nebula"	10.1.32+	H5 container & offline package: Nebula container for front-end and native code interaction.
      mPaaS_pod "mPaaS_UTDID"	10.1.32+	Device ID: Retrieves a unique and secure device ID.
      mPaaS_pod "mPaaS_DataCenter"	10.1.32+	Unified storage: Secure, fast, and encryptable key-value (KV) storage with multiple persistence options including database DAO.
      mPaaS_pod "mPaaS_ScanCode"	10.1.32+	Code scanning: Recognizes QR codes and barcodes.
      mPaaS_pod "mPaaS_LBS"	10.1.32+	Mobile location: Provides location services for mobile clients.
      mPaaS_pod "mPaaS_CommonUI"	10.1.32+	Common UI: Provides a library of reusable UI components.
      mPaaS_pod "mPaaS_Multimedia"	10.1.32+	Multimedia: Manages image downloads, uploads, and caching.
      mPaaS_pod "mPaaS_MobileFramework"	10.1.32+	Mobile Framework: Manages sub-applications, tab-based applications, third-party navigation, view controller transitions, and exception handling.
      mPaaS_pod "mPaaS_OpenSSL"	10.1.32+	OpenSSL
      mPaaS_pod "mPaaS_TinyApp"	10.1.32+	Mini program: Lets you integrate and publish mini programs.
      mPaaS_pod "mPaaS_CDP"	10.1.32+	Content Delivery Platform: Delivers marketing ads and display formats to the client.
      mPaaS_pod "mPaaS_ARTVC"	10.1.68	Audio and video call: Supports one-on-one and multi-party video calls and online meetings.
      mPaaS_pod "mPaaS_BlueShield"	10.2.3+	Blue Shield Encryption Component: Generates a guard image when the absBase64Code parameter is added to the configuration file.
      mPaaS_pod "mPaaS_MDC"	10.2.3+	Mobile dispatch component: Fine-grained domain name policy dispatching.

      A complete Podfile example is shown below:

      

4. Run pod mpaas update x.x.x, where x.x.x is the baseline version you configured, such as 10.2.3.

5. Run pod install to complete the integration. Append --verbose for detailed logs.

   Note

   If pod install fails because a GitHub library is not found, add source 'https://github.com/CocoaPods/Specs.git' to the top of your Podfile.

6. For third-party library conflicts, follow Resolve iOS Conflicts.

Upgrade guide

You can upgrade individual components or the entire baseline (SDK version).

Upgrade components

1. Run pod mpaas update x.x.x, where x.x.x is your current baseline version, such as 10.2.3.

   

2. Run pod install to upgrade the components for that baseline.

Upgrade the baseline

1. In your Podfile, change the baseline version in the mPaaS_baseline entry. Standard and custom baselines are supported. For example, changing from 10.1.68 to 10.2.3 upgrades the entire baseline.

   

2. Run pod install to complete the baseline upgrade.

Switch the mPaaS podspec source

Background

The code.aliyun.com repository that previously hosted mPaaS podspecs was decommissioned. It stopped receiving updates on June 1, 2023, and the service was terminated on June 30, 2023.

Using the old repository causes the following issues:

1. Cannot pull the latest SDK versions for any baseline.

2. Pulling any baseline version fails after June 30, 2023.

All mPaaS versions are now available on gitee.com.

Solution

Upgrade the mPaaS pod plugin

Update the mPaaS pod plugin:

sh <(curl -s http://mpaas-ios.oss-cn-hangzhou.aliyuncs.com/cocoapods/installmPaaSCocoaPodsPlugin.sh)

After the command completes, run pod plugins installed to verify the cocoapods-mPaaS version is 0.9.6 or later.

Modify the Podfile source

Replace the original source "https://code.aliyun.com/mpaas-public/podspecs.git" in your Podfile with the following:

source "https://gitee.com/mpaas/podspecs.git".

API changes

Only the plugin changes. Commands remain the same.

Test and verify

After upgrading and configuring, run mPaaS pod plugin commands to verify you can pull the latest baseline and SDK.

Parameter list

Configure parameters to customize default plugin behaviors.

Usage:

Add parameters after plugin "cocoapods-mPaaS" in your Podfile. For example:

Parameter	Function	Applicable version
:guard_image_version => 6	Generates a V6 guard image.	≥ V0.9.6
:guard_image_version => 5	Generates a V5 guard image.	≥ V0.9.6
:only_frameworks => true	Skips adding mPaaS template directory files. Use for standalone framework projects.	≥ V0.9.5.0.0.2
:check_repo => false	Skips the default repository check and auto-add. Use with internal network proxies.	≥ V0.9.5.0.0.2

Command list

The cocoapods-mPaaS plugin provides the following commands.

Command	Function
pod mpaas init	Adds the plugin, source, and mPaaS_baseline configurations to the Podfile.
pod mpaas update <VERSION>	Updates the baseline to the specified <VERSION> (e.g., 10.2.3) and refreshes the podspec repository.
pod mpaas update --all	In the official plugin, upgrades the plugin by rerunning the installation script. In the beta plugin, also updates the local baseline.
pod mpaas info	Lists all baselines and their components.
pod mpaas info <NAME> <VERSION> (<VERSION> is optional)	Filters information for a specific module name.
pod mpaas info --only-mPaaS	Shows a default baseline configuration for copying into the Podfile.
pod mpaas open	Opens the .xcworkspace file directly from the command line.
pod mpaas version	Shows the baseline version used in the current project.
pod mpaas version --plugin	Shows the cocoapods-mPaaS plugin version.