Alipay+ DocsAlipay+ Docs

iOS integration guide

The following sections introduce how to integrate the Alipay+ client SDK in your project for iOS devices.

1. Requirements

The following requirements must be met:

  • Install the following tools:
  • Xcode 12.* or later
  • CocoaPods 1.9.* or later
  • Ensure that the minimum deployment target is set to iOS 11 or later.
  • Set up a physical iOS device or use the iOS simulator to run your app.

2. Getting started

This section introduces how to import and initialize the Alipay+ client SDK.

Step 1: Add SDK to your app by using the CocoaPods CDN source

Add the CDN source to the top of your Podfile:

copy
source 'YOUR_COCOAPODS_CDN_SOURCE_URL'

YOUR_COCOAPODS_CDN_SOURCE_URL is your CDN source URL that is assigned by Alipay+. To obtain your CDN source URL, refer to the Podfile from the demo project. If you do not have the demo project file, contact your Solution Architect.

Add the required dependencies to your Podfile. For example, to install all Alipay+ products, you need to add the IAPConnect and IAPConnectResourceAppStore dependencies as below:

copy
  pod 'IAPConnect', '1.0.0'
  pod 'IAPConnectResourceAppStore', '1.0.0'

The IAPConnectResourceAppStore dependency includes resources that are used by all Alipay+ products. It is required regardless of the products that you use.

The IAPConnect dependency specifies that all Alipay+ products are to be installed.

Starting from version 2.27.0 of the Alipay+ iOS client SDK, multiple dependencies are fine-grained from the IAPConnect dependency for different Alipay+ products. You can add these dependencies based on the Alipay+ products that you want to use. For example, if you want to install only all Alipay+ payment products, you can add the IAPConnect/Payment dependency; or if you want to install only the Auto Debit payment product, you can add the IAPConnect/PaymentAutoDebit dependency.

The following table shows the dependencies that you can add for different Alipay+ payment products.

Pod dependency

IAPConnect

IAPConnect/Payment

Others

IAPConnect/PaymentCScanB

IAPConnect/PaymentBScanC

IAPConnect/PaymentAutoDebit

Only Alipay+ payment

✅

Only Merchant-presented Mode or Cashier Payment

✅

Only User-presented Mode

✅

Only Auto Debit

✅

Note:

  • For more information about the dependencies that the Alipay+ client SDK provides and how to choose the dependencies as you require, see Dependencies.
  • Existing users can continue using the IAPConnect dependency.

To protect your CDN from being used by others, you need to add an authorization header to all HTTP requests sent by CocoaPods to your CDN. To do this, simply add the following configuration to your .netrc file. The .netrc file is located in your $HOME directory. Create this file if it does not exist.

copy
machine globaltech.alipay.com
login LOGIN_ACCOUNT
password PASSWORD

The LOGIN_ACCOUNT and PASSWORD are used to log into https://globaltech.alipay.com. Contact your Solution Architect if you do not have the login credentials.

Now, try running 'pod install'.

Note: If you encounter any errors when running 'pod install', see Troubleshoot the CocoaPods CDN Source.

Step 2. Register services

The following services are available for choice. Select and register the services according to your business requirements during the application setup.

  • Register OAuthService

OAuthService is a service implemented by the Mobile Payment Provider (MPP) to provide authCode to Alipay+ client SDK. Alipay+ client SDK uses the authCode to perform OAuth.

copy
// register the api manager to wallet context
IAPWalletContextManager.instance.serviceManager = IAPWalletAPIManager()    
     
// This meta info can be loaded in a invisible swift file to load the real data   
let IAPWalletOAuthServiceMetaInfo = IAPWalletBaseServiceProvider(
        type: IAPWalletServiceType(category: .acl, type: "oauth"),
        name: NSStringFromClass(OAuthService.self))
         
IAPWalletContextManager.instance.serviceManager?.registerServices(metaInfos: [
        IAPWalletOAuthServiceMetaInfo
     ])

See getAuthCode for a sample implementation.

  • Register PaymentService (for Cashier Payment and Merchant-presented Mode Payment only)

PaymentService is implemented by the MPP to open the cashier page for payment.

copy
// register the api manager to wallet context
IAPWalletContextManager.instance.serviceManager = IAPWalletAPIManager()    
     
// This meta info can be loaded in a invisible swift file to load the real data
let IAPWalletPaymentServiceMetaInfo = IAPWalletBaseServiceProvider(
        type: IAPWalletServiceType(category: .acl, type: "payment"),
        name: NSStringFromClass(PaymentService.self))
        
IAPWalletContextManager.instance.serviceManager?.registerServices(metaInfos: [
        IAPWalletPaymentServiceMetaInfo
    ])

See pay for a sample implementation.

Step 3: Initialize SDK in your app

  1. Import the Alipay+ module to your app. It is recommended that you import the Alipay+ module at the start of the application, such as didFinishLaunchingWithOptions.
copy
#import <IAPConnect/IAPConnect.h>
  1. Initialize the Alipay+ client SDK.

Objective-C:

copy
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    IAPConnectInitConfig *config = [IAPConnectInitConfig new];
    config.envType = @"PROD";
    
	// Please refer to the demo project for [self createGriverConfiguration]
    config.riverConfiguration = [self createGriverConfiguration];
    
    [IAPConnectClient.sharedInstance initWithContext:config completion:^(NSString * _Nonnull errorCode, NSString * _Nonnull errorMessage, BOOL success) {
        if (success) {
            // to open ac service center
            // IAPConnect.openACCenter();
        }else{
            //error Logic: toast error Message;
        }
    }];
    return YES;
}

Swift:

copy
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    let config = IAPConnectInitConfig()
    config.envType = "PROD"

    // Please refer to the demo project for self.createGriverConfiguration() 
    config.riverConfiguration = self.createGriverConfiguration() 

    IAPConnectClient.sharedInstance()?.initWithContext(config, success: {
        
    }, failure: { (error, errorMessage) in
        
    })
    return true
}
  1. Configure Griver

When [-initWithContext:completion:] is called to initialize the Alipay+ client SDK, Griver is initialized as well. You do not need to initialize Griver separately.

The riverConfiguration and riverExtensionDelegate properties of IAPConnectInitConfig are used to configure or customize Griver. For more information about how to configure these properties, see the demo project.

3. Using SPIs (SDK -> Mobile Payment Provider App)

With the following services, you can use SPIs to interact with Mobile Payment Provider app.

OAuthService

OAuthService is used in the client SDK for all products.

The following SPIs can be used:

PaymentService

PaymentService is used only in Cashier Payment and Merchant-presented Mode Payment.

Currently, only pay interface in this service is used. After the Mobile Payment Provider returns the payment URL to Alipay+, Alipay+ client SDK opens the payment URL by calling the pay interface of the PaymentService. Mobile Payment Provider renders the cashier page and the user confirms the payment.

For sample implementation, see pay.

DeepLinkService

DeepLinkService is used only in Alipay+ Rewards.

Use of the following SPIs can be used, according to different scenario:

  • open(scheme: URL, in context: IAPWalletAPI.IAPWalletAPIContext? = nil)

This SPI is required to be implemented. See open scheme for sample implementation.

  • open(bizSceneCode: String,

              with params: [String:String],

              in context: IAPWalletAPIContext? = nil,

              callback: @escaping (IAPWalletBaseServiceResult) -> Void)

For scenarios where the open scheme SPI is not supported, this SPI is required to be implemented. See open sceneCode for sample implementation.

4. Using APIs (Mobile Payment Provider App -> SDK)

The interfaces to be integrated vary depending on different payment products. See the following sections for details:

signContract

signContract interface is only required for Auto Debit Payment.

Before Alipay+ SDK request the authCode form Mobile Payment Provider, the user must first sign the agreement to allow Alipay+ services. The Mobile Payment Provider must then call signContract interface to request for the required contract contents.

Before Mobile Payment Provider call this interface, Mobile Payment Provider must register an iOS Universal links in merchant app, and provide the iOS Universal links to Alipay+. When the Merchant requests to sign contract with the Mobile Payment Provider, Alipay+ can provide the iOS Universal links to the merchant with which merchant can jump to the Mobile Payment Provider app.

For sample usage, see signContract.

decode

decode interface is required for Cashier Payment and Merchant-presented Mode Payment.

Use this interface to decode the code, which might be an order code or a collection code, by Alipay+.

When Mobile Payment Provider receives a deep link which contains alipayconnectcode, parse the query parameter in the link and obtain the code value. For example, a deep link is iaps://alipayconnect/alipayconnectcode?codeValue=https://qr.alipay.com/bax122344556789075, in which the code value is https://qr.alipay.com/bax122344556789075. Call the decode interface with the code value.

For sample usage, see decode.

clear

clear interface is required for Cashier Payment , Merchant-presented Mode Payment, and User-presented Mode Payment.

Using the functions of Alipay+ client SDK requires the user authorization. After the user's authorization, the SDK is bound to a specific user. When a user logs out, Mobile Payment Provider must call the clear interface to clear the code information that is bound with the user and cached by the SDK.

For sample usage, see clear.

getPaymentCode

getPaymentCode interface is only required for User-presented Mode Payment.

Mobile Payment Provider uses the getPaymentCode interface to obtain the payment code from Alipay+. The payment code is returned by IPaymentCodeListener.

The following list describes when Mobile Payment Provider calls this interface:

  • Call this interface when Mobile Payment Provider generates or refreshes a payment code each time. The payment code might be expired after 1 minute, so refresh the payment code within 1 minute. It's recommended to refresh the code every 30 seconds.
  • Call this API to refresh the payment code when the value of region changes.

For sample usage, see getPaymentCode.

inquireQuote

inquireQuote interface is only required for User-presented Mode Payment.

Use the inquireQuote interface to query the foreign exchange rate between a pair of currency. The exchange rate returned by Alipay+ is only for reference.

For sample usage, see inquireQuote.

openACCenter

openACCenter interface is only used for openning the Alipay+ Rewards mini-program.

Use the openACCenter interface to create a UIViewController instance which contains the Alipay+ Rewards mini-program. After the viewController instance is successfully created, developer can present it by pushing it into the current ViewController stack.

for sample usage, see openACCenter.

5. Troubleshooting

The following section provides guides on how to troubleshoot issues that you may encounter during the integration process.

Troubleshoot the CocoaPods CDN source

To integrate IAPConnect with the CocoaPods CDN source, you need to set up your .netrc file correctly. Otherwise, you may encounter 401, 403, or other errors when you run 'pod install'.

Follow these steps to resolve these errors:

Step 1: Remove CocoaPods cache

  • Go to ~/.cocoapods/repo and remove the folder prefixed with alipay-api-v1-file-common-. This folder contains metadata and podspec file for the CDN source. This forces CocoaPods to reinitialize the CDN source next time you run 'pod install'.
  • Run the following commands to remove caches for IAPConnect SDKs:
copy
pod cache clean IAPConnect --all; 
pod cache clean IAPConnectResourceAppStore --all;
pod cache clean ACGriverCore --all;
pod cache clean ACConnectCore --all;

Step 2: Update your CocoaPods

The required version for CocoaPods is 1.9.* or higher. Run the following command to check your CocoaPods version. Update your CocoaPods if it is earlier than the required version.

copy
pod --version

Step 3. Check your account validity

The LOGIN_ACCOUNT and PASSWORD are required to log into https://globaltech.alipay.com.

To check whether your account has access to the CDN source, try opening the following URL in your browser:

copy
http://globaltech.alipay.com/api/v1/file/common/2017062215370883/${APP_NAME}/CocoaPods-version.yml

To find out your APP_NAME, refer to the Podfile from the demo project.

In the window that appears, enter your account and password. Your account can access the CDN source if your browser begins to download 'CocoaPods-version.yml'.

Step 4. Set up the .netrc file

The .netrc file is located in your $HOME directory. Run the following command to check whether the .netrc file exists:

copy
cd ~; ls .netrc

The .netrc file contains your account information.

copy
machine globaltech.alipay.com
login LOGIN_ACCOUNT
password PASSWORD

To check whether your .netrc file works correctly, try downloading the 'CocoaPods-version.yml' in your CLI:

copy
curl http://globaltech.alipay.com/api/v1/file/common/2017062215370883/${APP_NAME}/CocoaPods-version.yml

The following response appears if your .netrc is set up correctly. The 301 HTTP response is expected.

image.png

After this, try 'pod install' again.

Step 5. Use Charles to check your requests

If the 'pod install' command does not run successfully after you go through the preceding steps, you can use Charles to record the actual network requests for 'pod install' for further analysis.

Open your Charles. Assume that the monitoring port of Charles is set to the default port 8888.

Try the following command:

copy
ALL_PROXY=http://localhost:8888 pod install

With the command above, Charles records the network requests of your CLI. Export these records and send them to your Solution Architect, we'll take over from here.

Appendix: iOS libraries

The following sample shows all libraries included in the SDK:

copy
// API Interface library
IAPConnect.framework
// The related libraries
IAPConnectManager.framework
ACCommonLibraryLite.framework
IAPDeviceId.framework
IAPJSONKit.framework
IAPRPCServiceLite.framework
IAPConfiguration.framework
IAPLogLite.framework
SecurityGuardSDK.framework
SGMain.framework
ACContainerCommonAdapter.framework
ACMinContainerAdapter.framework // or ACIAPAppContainerAdapter.framework
IAPMinContainer.framework
//Griver about frameworks
AriverApi.framework
AriverDeviceCore.framework 
AriverRuntime.framework                
GriverDebug.framework
AriverApp.framework                   
AriverFileManager.framework            
AriverSecurity.framework               
GriverMap.framework
AriverConfig.framework                
AriverKernel.framework                 
AriverWebSocket.framework              
GriverSecureStorage.framework
AriverDebug.framework                  
AriverLogger.framework                
GRVAppContainer.framework              
GriverSecureStorageSGAdapter.framework
AriverDevice.framework                 
AriverResource.framework              
Griver.framework

Resource introduction

The functions provided by Alipay+ depend on three resource files:

  • iapconnect_config.json, which is used for configuration.
  • yw_1222_0a6a_prod.jpg, which is used for secure signature.
  • IAPMinContainer.bundle, which is web container related.

The contents of the three resource files are bound to the app. When your app integrates Alipay+ client SDK, contact Alipay+ to download the relevant resource files by providing bundleId of your app.

Dependencies

See the following list for mandatory dependencies:

  • IAPConnect.framework: provide interfaces that are related with Alipay+ business specifically.
  • IAPConnectManager.framework: used to configure the initialization of all libraries.
  • ACCommonLibraryLite.framework: common interface for all basic functions.
  • IAPDeviceId.framework: used to provide mobile device information.
  • IAPRPCServiceLite.framework: used for network implementation.
  • IAPConfiguration.framework: provide configurations from server side.
  • IAPLogLite.framework: provide capabilities that are related with logs.
  • ACContainerCommonAdapter.framework: used to open H5 page when user scans the merchant QR code.
  • IAPJSONKit.framework: provide serialization and deserialization capabilities. If this library is already integrated, the duplicate integration is not required.

See the following list for optional dependencies:

  • ACIAPAppContainerAdapter.framework: interface layer, which provides the ability for web rendering to interact with native code.
  • If ACIAPAppContainerAdapter is already integrated, the duplicate integration is not required.
  • If ACIAPAppContainerAdapter is not integrated but IAPAppContainer is integrated, integrate this library.
  • ACMinContainerAdapter.framework: interface layer, which provides the ability for web rendering to interact with native code.
  • If ACIAPAppContainerAdapter is already integrated, do not integrate this library.
  • If ACIAPAppContainerAdapter is not integrated, integrate this library.
  • IAPMinContainer.framework: implementation layer, which provides the ability for web rendering to interact with native code. If ACMinContainerAdapter is already integrated, do not integrate this library.
  • SecurityGuardSDK.framework: used to encrypt, decrypt and generate the signature for HTTP. If this library is not integrated, integrate the library.
  • SGMain.framework: used to encrypt, decrypt and generate the signature for HTTP. If this library is not integrated, integrate the library.
  • Griver Frameworks: frameworks related to Griver, which are the framework designs of Griver itself. Contact Alipay+ for more details.

Note:

x.y.z is the placeholder and represents the library's version.

Learn more about

Home
Get Support
Need more help?