Mobile SDK integration guide

2022-07-04 05:45

To secure your digital wallet from unauthenticated transactions, DWS provides a mobile security SDK that generates the device fingerprint (DFP) for each client device. This document illustrates the general procedure of how to integrate the security SDK into your Android/iOS application.

Before you start

Before you start with the integration guide, make sure you complete the following steps:

Read through the DWS introduction and understand the overall integration process.
Get familiar with the basic concepts used in this documentation.

Terminology / Concept	Description
APDID	Ant product device ID
appName	The identifier of your application, check with Alipay before integration
bizToken	Business token, provided by Alipay
Device Fingerprint (DFP)	A core identity that associates devices with risk control data
envMode	Current environment mode
Gateway	RPC server gateway address
tid	An optional value, its value is an empty string in most cases.
userId	An optional value, its value is an empty string in most cases.
workspaceId	An optional value, its value is an empty string in most cases.

Make sure you have obtained the following information/libraries from Alipay:

Gateway address, bizToken, and appName that are specific to your application
Security SDK libraries for Android/iOS based on your mobile app type

Note:
In the following code samples, expressions that are wrapped with "<>" are to be replaced with the actual values.

General procedure for Android

Preparation

1. Add dependency for SDK

After you have received the security SDK libraries, add the .AAR files to your app/libs folder and add the corresponding dependencies in the app/build.gradle file as shown below:

copy

dependencies {
    ...
    implementation(name: 'apsecurity-oversea-sdk', ext: 'aar')
    implementation(name: 'apsecuritysdk-adapter-oversea-sdk', ext: 'aar')
    ...
}

2. Code obfuscation configuration

The security SDK itself has obfuscated the code. In order to ensure the RPC and native modules work properly, you need to add the following configuration when opening the ProGuard obfuscation configuration in release versions：

copy

#Reserved attribute
-keepattributes InnerClasses, *Annotation*, Signature, SourceFile, LineNumberTable

#user-defined class
-keep class com.alipay.alipaysecuritysdk.** { *; }

3. Repository setting

Include the following repositories in your project-level repository settings:

copy

repositories {
    google()
    mavenCentral()
    jcenter()
    maven {
        url 'https://maven.google.com'
    }
    flatDir {
        dirs './app/libs'
    }
}

4. User permission

For the SDK to obtain the related device information, you need to add the following user permissions to AndroidManifest.xml and request for permissions dynamically:

copy

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

5. Apache HTTP support

The security SDK requires support for Apache HTTP Client during configuration. Since Android 6.0 release removed support for the Apache HTTP Client, the following declaration must be made in AndroidManifest.xml and build.gradle respectively:

copy

<uses-library android:name="org.apache.http.legacy" android:required="false"/>

copy

android {
    useLibrary 'org.apache.http.legacy'
}

SDK instantiation and configuration

Interface

The following methods in com.alipay.alipaysecuritysdk.face package is used to instantiate and configure an APSecuritySdk instance.

copy

package com.alipay.alipaysecuritysdk.face;

// Step 1. instantiate an APSecuritySdk instance
/**
     * @return APSecuritySdk instance
**/
public static APSecuritySdk getInstance();

// Step 2. set configuration for the APSecuritySdk instance
/**
     * @param  tConfiguration   RPC configuration
     * @return APSecuritySdk instance
**/
public APSecuritySdk configuration(Configuration tConfiguration);

// Step 3. initiate the instance
/**
     * @param context    Application context
     * @param appName    App's identifier
     * @param bizToken   Business token
     * @return
**/
public synchronized void init(Context context, String appName, String bizToken);

The Configuration object used in Step 2 can be created with the following API from com.alipay.alipaysecuritysdk.common.configpackage:

copy

package com.alipay.alipaysecuritysdk.common.config;	
      
/**
     * @param gateway   RPC Network Gateway
     * @param envMode   Environment Mode
     * @param headers   RPC header
     * @param needUmid  Whether umid is required
     * @param secret    Data encryption type, can be set to "1"
     * @return configuration
 */
public static Configuration createConfiguration(String gateway, int envMode, Map<String, String> headers, boolean needUmid, String secret)

// Below are the available values for envMode
public static final int ENV_MODE_ONLINE;
public static final int ENV_MODE_PRE;
public static final int ENV_MODE_SIT;
public static final int ENV_MODE_DAILY;
public static final int ENV_MODE_DEV;

Code sample

copy

// 1. Import the required packages
import com.alipay.alipaysecuritysdk.face.APSecuritySdk;
import com.alipay.alipaysecuritysdk.common.config.Configuration;

// 2. Define RPC headers
Map<String, String> headers = new HashMap<>();
headers.put("workspaceid", ""); // You can pass in empty String in most cases
headers.put("appid", ""); // You can pass in empty String in most cases

// 3. Instantiate and configure a APSecuritySdk instance 
APSecuritySdk.getInstance()
             .configuration(Configuration.createConfiguration("<gateway>", Configuration.ENV_MODE_ONLINE, headers, false, "1"))
             .init(getApplicationContext(), "<appname>", "<biztoken>");

Asynchronous token initialization

Interface

After the instantiation, it is ready to initiate the APDID token, for example, the DFP of the device. The initiation process is asynchronous and only needs to be invoked once during the entire app lifecycle.

copy

package com.alipay.alipaysecuritysdk.face;

/**
 * @param appName       App name
 * @param inputParams   Init params
 * @param listener      Callback listener
 **/
public static void initToken(String appName, Map<String, String> inputParams, final InitResultListener listener);

The InitResultListener callback is defined as below:

copy

public interface InitResultListener {
    /**
    * @param TokenResult token
    * @param msg 
    */
    void onResult(Boolean success, TokenResult tokenResult, String msg);
}

The TokenResult includes the following fields:

copy

public class TokenResult {
    public String apdidToken;   // Apdidtoken
    public String clientKey;   
    public String apdid;      
    public String umidToken;    
}

Code sample

copy

// 1. Import the required package
import com.alipay.alipaysecuritysdk.face.APDID;
import com.alipay.alipaysecuritysdk.face.APSecuritySdk;

// 2. Define the input parameters for initiation 
Map<String,String> inputParams = new HashMap<String,String>();
inputParams.put("tid", "");    // You can pass in empty String in most cases
inputParams.put("userId", ""); // You can pass in empty String in most cases

// 3. Initiate the token with callback listener
APDID.initToken("<appname>", inputParams, new InitResultListener() {
    @Override
    public void onResult(Boolean success, TokenResult tokenResult, String msg) {
        if (success && tokenResult != null) {
            String apdidToken = tokenResult.apdidToken;
        } 
    }
});

Apdid token retrieval

Interface

After the token initiation is done, you can synchronously retrieve the token whenever and wherever is needed. The following API is used to retrieve the local token:

copy

package com.alipay.alipaysecuritysdk.face;

/**
 * @param appName  App name
 * @return token result
**/
public static TokenResult getTokenResult(String appName)

Code sample

copy

// 1. Import the required package
import com.alipay.alipaysecuritysdk.face.APDID;

// 2. Retrieve TokenResult
TokenResult *result = APDID.getTokenResult("<appname>");
String apdidToken = result.apdidToken;

Overall code sample

copy

// 1. Import the required package
import com.alipay.alipaysecuritysdk.face.*;
import com.alipay.alipaysecuritysdk.common.config.Configuration;

// 2. Instantiate and configure an APSecuritySdk instance
Map<String, String> headers = new HashMap<>();
 headers.put("workspaceid", "");
 headers.put("appid", "");
 APSecuritySdk.getInstance()
              .configuration(Configuration.createConfiguration("<gateway>", ENV_MODE_ONLINE, headers, false, "1"))
              .init(getApplicationContext(), "<appname>", "<biztoken>");

// 3. Initiate the token with callback listener
Map<String,String> inputParams = new HashMap<String,String>();
inputParams.put("tid", "<tid>");    // If not available, pass in empty String
inputParams.put("userId", "<userid>"); // If not available, pass in empty String
APDID.initToken("<appname>", inputParams, new InitResultListener() {
        @Override
        public void onResult(Boolean success, TokenResult tokenResult, String msg) {
            if (success && tokenResult != null) {
                String apdidToken = tokenResult.apdidToken;
            } 
        }
 });

/*...your code...*/

// 4. Retrieve the token result synchronously wherever needed
TokenResult *result = APDID.getTokenResult("<appname>");
String apdidToken = result.apdidToken;

Validation

After you complete the integration steps above, your application can obtain the TokenResult object and retrieve the apdidToken value. In normal cases, apdidToken is a String of length 56. If not, please check the device's network and proxy, and make sure the network is working properly. You may approach our support if the problem persists.

General procedure for iOS

Preparation

1. Add dependency for SDK

After you have received the security SDK libraries, add the framework files to your project target.

2. Add system library dependency

Add the following frameworks/libraries to your project:

Foundation
CoreLocation
CoreMotion
CoreTelephony
libc++.dylib
libz.dylib
SystemConfiguration

SDK configuration

Interface

The following methods in APPSecuritySDKCore/APSecureSdk.h library are used to initiate and configure an APSecuritySdk instance.

copy

<APPSecuritySDKCore/APSecureSdk.h>

/**
     * @param config     RPC configuration
     * @param bizToken   Business token
     * @param appName    App's identifier
     * @return
**/
- (void)initWithRpcConfiguration:(NSDictionary *) config bizToken: (NSString *) bizToken appName:(NSString *)appName;

The config parameter above is of Dictionary type and consists of 3 key-value pairs. Defined keys are as follows:

Key	Required	Description
ASS_RPC_GATEWAY_ADDR	Yes	RPC server gateway address
ASS_RPC_WORKSPACEID	Yes	workspaceid in rpc header
ASS_RPC_APPID	Yes	appid in rpc header

Code sample

copy

// 1. Import the APSecureSdk library
#import <APPSecuritySDKCore/APSecureSdk.h>

// 2. Define the RPC configuration
NSDictionary* rpcParams = @{ASS_RPC_GATEWAY_ADDR:@"<gateway>",
                                ASS_RPC_APPID:@"<appid>",
                                ASS_RPC_WORKSPACEID:@"<workspaceid>"
    };

// 3. Initiate APSecureSdk with defined configuration
[[APSecureSdk sharedInstance] initWithRpcConfiguration:rpcParams bizToken:@"<biztoken>" appName:@"<appname>"];

Asynchronous token initialization

Interface

The initToken method in the APDID.h library is used to initiate the device token. The initiation process is asynchronous and only needs to be invoked once during the entire app lifecycle.

copy

<APPSecuritySDKCore/APDID.h>

/**
     * @param appName    App's identifier
     * @param params     Environment configuration
     * @param callback   Callback listener
     * @return
**/
+ (void) initToken:(NSString*)appName params:(NSDictionary*)params callback:(ASSSecureSdkCallback)callback;

The params parameter above is of Dictionary type and consists of 3 key-value pairs. Defined keys are as follows:

Key	Required	Description	Defined values
ASS_ENVIRONMENT	Yes	Current environment mode	ASS_ENVIRONMENT_ONLINE ASS_ENVIRONMENT_SIT ASS_ENVIRONMENT_DAILY ASS_ENVIRONMENT_PRE
ASS_TID	No	tid	Empty string "" if not available
ASS_USERID	No	user ID	Empty string "" if not available

The callback listener TokenResultListener can be instantiated with the following interface:

copy

typedef void(^ASSSecureSdkCallback)(ASSTokenResult* result, NSString* error);

The ASSTokenResult includes the following fields:

copy

@interface ASSTokenResult : NSObject

@property (nonatomic, strong) NSString* vkeyidToken; // The APDID token
@property (nonatomic, strong) NSString* clientKey; 
@property (nonatomic, strong) NSString* umidToken;
@property (nonatomic, strong) NSString* vkeyid;

@end

Code sample

copy

// 1. Import the APDID library
#import <APPSecuritySDKCore/APDID.h>

// 2. Assign environment mode
NSDictionary* params = @{ASS_ENVIRONMENT:ASS_ENVIRONMENT_ONLINE,
                                 ASS_TID:@"<tid>",
                                 ASS_USERID:@"<userid>"
                         };

// 3. Initiate the DeviceToken with callback method
[APDID initToken:@"<appname>" params:params callback:^(ASSTokenResult *result, NSString* error) {
            NSLog(@"token:%@", result.vkeyidToken);
}];

Device token retrieval

Interface

After the token initiation is done, you can synchronously retrieve the token whenever and wherever is needed. The following API is used to retrieve the local token:

copy

<APPSecuritySDKCore/APDID.h>

/**
     * @param appName       App's identifier
     * @return tokenResult  Token result
 */
+ (ASSTokenResult*)getTokenResult:(NSString*)appName ;

Code sample

copy

// 1. Import the APDID library
#import <APPSecuritySDKCore/APDID.h>

// 2. Retrieve TokenResult
ASSTokenResult *result = [APDID getTokenResult:@"<appname>"];
NSLog(@"token:%@",result.vkeyidToken);

Overall code sample

The following code snippet demonstrates a complete sample of token initialization and retrieval.

copy

// 1. Import the required libraries
#import <APPSecuritySDKCore/APSecureSdk.h>
#import <APPSecuritySDKCore/APDID.h>

// 2. Define RPC configuration and initiate the APSecureSdk instance
NSDictionary* rpcParams = @{ASS_RPC_GATEWAY_ADDR:@"<gateway>",
                                ASS_RPC_APPID:@"",
                                ASS_RPC_WORKSPACEID:@""
    };
[[APSecureSdk sharedInstance] initWithRpcConfiguration:rpcParams bizToken:@"<biztoken>" appName:@"<appname>"];

// 3. Define environment configuration and initiate the token
NSDictionary* params = @{ASS_ENVIRONMENT:ASS_ENVIRONMENT_ONLINE,
                                 ASS_TID:@"",  // If not available, pass in empty String
                                 ASS_USERID:@"" // If not available, pass in empty String
                                 };
[APDID initToken:@"<appname>" params:params  callback:^(ASSTokenResult *result, NSString* error) {
            NSLog(@"token:%@",result.vkeyidToken);	
}];

/*...your code...*/

// 4. Retrieve the token result synchronously wherever needed
ASSTokenResult *tokenResult = [APDID getTokenResult:@"<appname>"];
NSLog(@"token:%@",tokenResult.vkeyidToken);

Validation

More information

Introduction

Getting started

Use case: Balance payment

API integration guide

API reference

Glossary

What's new