Quickstart

2026-05-14 09:25

This topic introduces how to quickly set up the iOS IAPMiniProgram SDK and implement basic mini-program capabilities.

Before you begin

Before you get started, ensure you are familiar with the following things:

To run mini-programs, your device needs to be iOS 11 or later.
Xcode 14.0 or later is installed on your computer.
CocoaPods 1.10.0 or later is installed on your computer.

Get started

To get started with IAPMiniProgram SDK, perform the following actions:

Step 1: Download the configuration files

Log in to Mini Program Platform, go to the Apps page, and click Resource > iOS Resource to download the configuration file for the iOS SDK. The iapconnect_config_full file is downloaded to your computer.

For more information about how to download app resources, see Download app resources.

Step 2: Add the configuration file

Move the iapconnect_config_full file into the root of your Xcode project.

When a dialog box pops up, tick the checkboxes to add the file to all targets, such as MyCoolApp and MyCoolAppDev in the following screenshot.

Confirm that the configuration file is added to all intended targets.

Select the file in Xcode, and the Target Membership box on the right side shows the selected targets.

Step 3: Add dependencies

To add dependencies for the iOS IAPMiniProgram SDK, take the following steps:

Update the .netrc file

For security reasons, Mini Program Platform uses a private CocoaPods source to distribute the pods. To gain access to the private source, you need to update your .netrc file which holds the required credentials.

Copy the following configuration code to your .netrc file that locates in your $HOME directory. Create one if it does not exist. Reference: the .netrc file.
For more information about the user login name and password, contact our technical support.

copy
machine globaltech.alipay.com 
login YOUR_ACCOUNT 
password YOUR_PASSWORD

Add dependencies in Podfile

Add the private source and dependency to your Podfile with the following code:

copy
source 'https://globaltech.alipay.com/api/v1/file/common/2017062215370883/minisdk'

sdk_version = 'x.x.x' # Replace x.x.x with the target SDK version. See [iOS release notes](https://miniprogram.alipay.com/docs/miniprogram/sdk_release_notes/ios).

target 'YOUR_TARGET' do

  pod 'IAPMiniProgram', sdk_version

  # Optional components (must use the same version as the main SDK)
  # pod 'IAPMiniProgram/Video', sdk_version

  # Optional components (Required when initializing via IAPConnectClient)
  # pod 'IAPMiniProgram/Legacy', sdk_version

end

Note: The third-party library dependencies of the iOS IAPMiniProgram SDK might conflict with the version requirements of other SDKs or your app. It is recommended to thoroughly test your app's functionalities after integration. For more information, refer to Third-party library dependencies.

Step 4: Install the SDK

To install the SDK, run the pod install or pod install --repo-update command at the path of your Podfile.

If you encounter any problems when installing the SDK, refer to Troubleshooting CocoaPods CDN Source for troubleshooting.

Step 5: Initialize the SDK

Note:

SDK has some default environment related configurations (for example, user agent, gateway address, environment name, and so on). If the super app wants to customize these configurations, must call the GRVConfiguration method to configure specific properties per your demands before initializing the SDK.
To initialize the SDK, use the following code. The code is recommended to be inserted in application(_:didFinishLaunchingWithOptions:) and needs to be run on the main thread.

The SDK provides two initialization ways with architectural evolution. Choose either that fits your project scenario best.

1. Initialize SDK via `MiniProgramClient` (Recommended)

This way of SDK initialization is recommended.

copy
import UIKit
import GriverInit
import GRVAppContainer

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let config = MiniProgramInitConfig()
    MiniProgramClient.shared.initialize(with: config, success: {

    }, failure: { error in

    })
}

2. Initialize SDK via `IAPConnectClient`

Use this way if your project depends on modules that require IAPConnectClient, or if you maintain an existing integration.

Note: When using this initialization way, must add pod 'IAPMiniProgram/Legacy', sdk_version to your Podfile. See Step 3: Add dependencies.

copy
import UIKit
import IAPConnect
import GRVAppContainer

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let config = IAPConnectInitConfig()
    IAPConnectClient.sharedInstance()?.initWithContext(config, success: {

    }, failure: { (error, errorMessage) in

    })
}

Step 6: Implement SDK basic capabilities

1. Open a mini-program

To open a mini-program in your app, call either of the following APIs:

openAppWithApppId: Call this method to open a mini-program with its unique ID.
openAppWithUrl: Call this method to open a mini-program with its URL.

2. Obtain the mini-program list

To obtain the mini-program list in your app, call either of the following APIs:

fetchApps: Call this API to obtain the mini-program list with FetchAppRequestVO.
fetchAppInfosByIds: Call this API to obtain the mini-program list with mini-program IDs.

Next steps

The steps above focus on how to integrate the iOS IAPMiniProgram SDK and implement its basic capabilities.

In addition to that, developers can selectively refer to the following chapters to implement advanced capabilities/features of the iOS IAPMiniProgram SDK:

Integrate Native SPIs: Refer this guide to implement the following services/capabilities: obtaining user authorization, accessing user information, processing payments, scanning QR codes and barcodes.
Integrate SDK components: To implement capabilities related to map, multi-media, or Bluetooth, refer to this guide to integrate the corresponding pre-defined SDK components.
Integrate the operation module: To implement the mini program operation capabilities that mainly include data monitoring and release management, user interaction (such as message pushing, content delivery), and handling feedback and comments.
Listen for SDK events: To perform specified operations on a certain event, refer to this guide to implement specific protocols to listen for SDK events.
Customize extension capabilities: To customize certain SDK extension capacities, refer to this guide to implement specific interfaces.
Customize UI-related capacities: To customize certain user interfaces and related capacities, refer to this guide to implement specific protocols.
Customize web-view access to HTTP resources and URL schemes: To allow the web-view component to access HTTP resources and custom URL schemes (e.g., mailto), refer to this guide to implement the target protocol.
Customize JSAPIs: To extend SDK functionalities via JSAPIs, refer to this guide to create new JSAPIs and override the default implementation of built-in JSAPIs.
Open a mini program via a promotional QR code: To allow users to open mini programs and get benefits via promotional QR codes, refer to this guide to enable opening mini programs by scanning such codes.
Encrypt local data for enhanced security: To enhance security by storing data from local-storage JSAPIs (e.g., my.getStorage) in encrypted format rather than in plaintext, refer to this guide to implement the target protocol.
UIScene-based life cycle: Apple requires apps built with the iOS 27 SDK to adopt the scene-based life cycle (see TN3187).