iOS integration guide
The following sections introduce how to integrate the Alipay+ ACQP iOS SDK in your project for iOS devices.
Note: The payment sheet mentioned in the following sections is also known as the Alipay+ checkout page.
1. Requirements
The following requirements must be met:
- Install the following tools:
- Xcode 12.* or later
- Ensure that the minimum deployment target is set to iOS 9 or later.
2. Getting started
Step 1. Add SDK to your project
- Log on to Alipay+ Developer Center to download the SDK binaries as a package. You can also obtain the source code if you need to review or customize the SDK source code.
- Ensure that the Alipay+ SDK and your own SDK (if exists) are linked together to your project.
- If you previously used CocoaPods to publish your SDK or you can use CocoaPods to publish your SDK to other integrators, add the following line to your podspec file:
s.vendored_frameworks = ['YOUR_PATH/AlipayPlusClient.framework']
s.resources = ["YOUR_PATH/AlipayPlusClient.framework/AlipayPlusResource.bundle"]
- If you do not use CocoaPods, you can guide other integrators to manually add the SDK as follows:
- Add AlipayPlusClient.framework to your project. Make sure to select Copy items if needed.
- Add AlipayPlusClient.framework/AlipayPlusResource.bundle to your project. Make sure to select Copy items if needed.
- Make sure to add -ObjC to Build Settings > Linking > Other Linker Flags to use class category.
Note: If your project is created using swift and the "Undefined symbol: ___llvm_profile_runtime" error is triggered during build, try add -fprofile-instr-generate to Build Settings > Linking > Other Linker Flags to resolve the error.
Step 2. Set up the SDK before using other APIs
- Import the SDK header file to your project.
import <AlipayPlusClient/AlipayPlusClient.h>
- Set up the SDK with required configurations.
IAPConfiguration *configuration = IAPConfiguration.new;
configuration.envType = @"PROD";
configuration.acquirerId = @"xxx";
configuration.merchantId = @"yyy";
configuration.language= @"zzz";
[AlipayPlusClient.shared setConfiguration:configuration];
3. Using SDK APIs (ACQP -> SDK)
The following section introduces the APIs that are provided by the SDK.
3.1 inquirePaymentOption
The inquirePaymentOption API is used to inquire whether the Alipay+ payment method is available and if so, related data about the Alipay+ payment method, such as the Alipay+ logo, brand name, and promotion information.
You can directly render the payment method page based on the data about the Alipay+ payment method. Alternatively, you can process the data about the Alipay+ payment method and append the processing result to the data about your existing payment methods, and then render the payment method page accordingly.
Note the following things:
- If the value of the enabled parameter is
false
in the response, you can check the disableReason parameter to understand the reason for failure. Generally, you do not need to display the reason to the user. - If the value of the enabled parameter is
true
in the response, the SDK returns the logo based on the following rules:
- If no aggregated logo is preconfigured, the SDK returns the default Alipay+ logo.
- If aggregated logos are preconfigured, the SDK returns one or more aggregated logos based on the currency. If no aggregated logo matches the currency, the default aggregated logo is returned. You can use the logoPattern parameter to specify the logo that you want to use.
- To improve loading performance and reduce data transfer costs, it is recommended that you cache the image of the Alipay+ logo by its CDN URL.
- The array of the promotion information currently contains only one element. The priority of the language that is used to display the promotion information is as follows: the language that you specified in the setConfiguration API > English.
For more information about this API, see inquirePaymentOption.
3.2 showPaymentSheet
The showPaymentSheet API is used to show the payment sheet for the user to complete the payment after the user places an order with Alipay+. You can display the recommended Mobile Payment Providers (MPPs) that are supported by Alipay+ on the payment sheet. After the user selects an MPP and clicks Pay Now, the user is redirected to the MPP client to complete the payment. In the preceding process, you can receive callbacks about key events, such as when the user clicks Close or when the user clicks Pay Now.
How to handle the key events:
- When you receive the event that the user has selected an MPP and clicked Pay Now, the SDK closes the payment sheet and redirects the user to the MPP client to complete the payment. The payment status will not be updated through callbacks. Therefore, you may need to call your server to query the payment status.
- When the user clicks Close, the SDK closes the payment sheet. You can define custom logic to process the event.
- If the value of the paymentData parameter is illegal, the payment sheet is not displayed and the corresponding callback is invoked to notify the caller.
About the payment sheet:
- The payment sheet will be rendered in the key window and cover the interface of the active app, including the navigation bar and status bar.
- The payment sheet is closed only when the user clicks Close or clicks Pay Now after selecting an MPP.
For more information about this API, see showPaymentSheet.
4. Using SDK SPIs (SDK -> ACQP)
The SDK provides the following services.
4.1 LogService
The LogService supports the following SPIs:
log
The log SPI is used to obtain the details of key events that occur during the interaction between the user and the SDK. The detailed information can be used for debugging or logging.
Note that the log SPI is optional.
For more information about this SPI, see log.