This topic introduces how to quickly set up the IAPMiniProgram SDK in Flutter projects and implement basic SDK capabilities.

Before you begin

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

General

Install the following SDKs on your computer:

• Flutter 3.0.0 or later, but earlier than 4.0.0
• Dart 2.17.0 or later

For the Android SDK

• Operating systems:

• To run HTML5 mini programs, your device needs to be Android 4.1 (API level 16) or later.
• To run mini programs based on DSL (Domain Specific Language), your device needs to be Android 4.2 (API level 17) or later. However, to ensure proper function, it is recommended to use devices with Android 6.0 (API level 23) or later, which requires you to set minSdkVersion in the build.gradle file to 23 or later.

• Android Studio is installed on your computer.
• The Gradle plugin version needs to be 4.1 or later.

For the iOS SDK

• 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 the IAPMiniProgram SDK, perform the following actions:

Step 1: Download the configuration files

Log in to Mini Program Platform, go to Apps, click the app associated with your Flutter project, then click Resource to download the configuration files for the Android and iOS SDK respectively. You will have two iapconnect_config_full files on your computer.

For more information, see Download app resources.

Step 2: Integrate native SDKs

To integrate the platform-specific IAPMiniProgram SDKs, follow the instructions in these sections:

• Integrate the Android IAPMiniProgram
• Integrate the iOS IAPMiniProgram

Integrate the Android IAPMiniProgram

1. Add the configuration file

Add the Android iapconnect_config_full file that you obtain in Step 1 to the Android's assets directory of your Flutter project. See the following image for details:

2. Add the Maven repository

Add the Maven repository to the build.gradle file with the following code:

repositories {
    maven {
        url 'https://globaltech.alipay.com/api/v1/file/repository/minisdk/'
        credentials {
            username = USERNAME
            password = PASSWORD
        }
    }
}

3. Add dependencies

To add dependencies for the Android IAPMiniProgram SDK, follow these steps:

1. Add the dependencies in the app-level build.gradle file with the following code sample:

// in app build.gradle
// if there are some conflicts with existing sdk, please exclude them
dependencies {
    implementation "com.alipay.plus.android:iapminiprogram:${iapminiprogram_version}"
}

2. Externalize the version number in the build.gradle file to manage upgrades with the following code sample:

ext {
    iapminiprogram_version = 'IAPMINPROGRAM_VERSION'
}

Replace the value of IAPMINPROGRAM_VERSION with the latest version number that is provided in the Android IAPMiniProgram SDK release notes.

Note: The third-party library dependencies of the Android 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.

Integrate the iOS IAPMiniProgram

1. Add the configuration file

Move the iOS iapconnect_config_full file that you obtain in Step 1 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 Runner and RunnerTests as shown in the following screenshot.

To 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.

2. Add dependencies

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

1. 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. For more information about .netrc file, see The .netrc file.

To update your .netrc file, copy the following configuration to your .netrc file. The .netrc file locates in your $HOME directory. Create one if it doesn't exist.

machine globaltech.alipay.com 
login YOUR_ACCOUNT 
password YOUR_PASSWORD

2. Add dependencies in Podfile

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

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

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 3: Integrate the IAPMiniProgram Flutter plugin

To integrate the IAPMiniProgram Flutter plugin, take the following two steps:

Add dependencies

To add dependencies for the Flutter plugin, choose either of the following methods:

• Integrate a Git repository
• Integrate a local library

Note: Each version of the Flutter plugin corresponds to specific versions of the IAPMiniProgram SDKs for Android and iOS, as stated in the Flutter plugin release notes. These SDK versions are for compilation only. The SDK versions that function at runtime are determined by your declared dependencies during the integration of native SDKs.

Integrate a Git repository

1. To access the Git repository that hosts the Flutter plugin, provide your public IP to technical support for allowlisting.
2. In the pubspec.yaml file, specify the following keys:

• url: The URL of the Git repository that hosts the Flutter plugin. The value contains credentials and is desensitized.
• ref: The specific version of the Flutter plugin you need to install. You can obtain the version number from the IAPMiniProgram Flutter plugin release notes.

See the following code sample for details:

iap_mini_program:
  git:
    url: 'xxx.git'
    ref: IAPMINPROGRAM_PLUGIN_VERSION

Integrate a local library

1. Contact technical support to obtain the zip package of the Flutter plugin and extract the iapminiprogram-flutter folder to your computer.
2. In the pubspec.yaml file, add a path reference to the local library (the iapminiprogram-flutter folder). The path varies depending on whether the library is located within the project directory.

• If the library is located outside the project directory, use an absolute path. See the following code samples for details:

Example for Windows

  iap_mini_program:
     path: 'C:\example\path\to\iapminiprogram-flutter' #Replace the example with the actual path

Example for macOS

  iap_mini_program:
     path: '/Users/example/path/to/iapminiprogram-flutter' #Replace the example with the actual path

• If the library is within the project directory, it is recommended to use a relative path for portability and adaptability. See the following code sample for details:

  iap_mini_program:
    path: './iapminiprogram-flutter' #Assuming the directory is at the same level as pubspec.yaml

Initialize the Flutter project and native SDKs

1. (Optional) Initialize the Flutter project

If you need to open a Flutter page (represented by a Widget) based on the incoming parameters after opening a mini program, initialize your Flutter project with a custom entry point. You can achieve this by adding the iapMiniProgramMain method in the main.dart file. See the following code sample for details:

import 'dart:ui';

@pragma('vm:entry-point')
void iapMiniProgramMain(args) {
  runApp(_widgetForRoute(args));
}

//Open different flutter pages based on the incoming parameters
Widget _widgetForRoute(List<String> args) {
  String route = "";
  if (args.isNotEmpty) {
    route = args[0];
  }
  final url = Uri.parse(route);
  final path = url.path;
  String params = "";
  if (args.length > 1) {
    params = args[1];
  }
  return MaterialApp(
    home: Builder(
      builder: (context) {
        switch (path) {
          case '/auth':
            return AuthPage(
              data: params,
            );
          case '/pay':
            return PayPage(
              data: params,
            );
          case '/code':
            return CodePage(
              data: params,
            );
          default:
            return const MyApp();
        }
      },
    ),
    debugShowCheckedModeBanner: false,
  );
}

2. Initialize the native SDKs

Based on business requirements, choose an appropriate location to initialize the IAPMiniProgram SDK with the following code sample:

void initSDK() async {
 bool initResult = await IAPMiniProgram.instance.init();
  }

The SDK initialization result is returned as a boolean value:

• true: The SDK initialization succeeds.
• false: The SDK initialization fails.

Step 4: Implement basic capabilities

After the integration, you can open a mini program in your app by calling either of the following APIs:

• openApp: Call this API to open a mini program with its unique ID.
• openUrl: Call this API to open a mini program with its URL.

Next steps

The steps above focus on how to integrate the Android and iOS IAPMiniProgram SDKs and implement basic SDK capabilities. Besides, you can enhance the SDK capabilities by integrating Native SPIs to obtain user authorization, access user information, process payments, and scan QR codes and barcodes.

For more information, refer to Integrate Native SPIs.