NFCMonitor

The NFCMonitor SPI is used for the SDK's internal monitoring. The MPP uses this SPI to detect the SDK's execution status.

Method signature

copy
public interface NFCMonitor {
    void track(String monitorId, Map<String, String> params);
}

Request parameters

Item

Type

Description

Required

track(String monitorId, Map<String, String> params)

Function

Provides monitoring point information for the MPP.Parameters of this function:

monitorId: The SDK's internal ID of the monitoring point.
params: A key-value object that contains the monitor fields of monitorId and their values. For details about monitoring points and their fields, see the Monitor tracking points section.

Required

Monitor tracking points

NFC card activation monitor

monitorId = EVENT_APPLY

This monitor reports the following data when the card activation process is completed.

Field	Description	Type
applyLoopTimeConsume	Total time spent for the card application polling.	String
activateLoopTimeConsume	Total time spent for the card activation polling.	String
applyTimeConsume	Total time spent for the card application process.	String
applyResult	The result of the card application process.	String
phase	The phases of the card application process. If the card application fails, you can locate the failing phase with this field.	Array<String>
isSilent	Whether the card activation is in silent mode. Valid values are: `true`: yes `false`: no	String
current_id	This unique ID identifies the user connecting the SDK. The value of this field is generated when the app calls the connect API.	String
utdId	The user's device fingerprint.	String

Card activation confirmation monitor

monitorId = EVENT_CONFIRM

This monitor reports the following data when the card activation confirmation is completed.

Field

Description

Type

confirmResult

The result of card activation confirmation.

Valid values are:

true: successful
false: failed

String

errorCode

The error code associated with the failure.

This field returns only when the confirmation fails.

String

replenish API monitor

monitorId = EVENT_REPLENISH

This monitor reports the following data when the replenish process is triggered.

Field	Description	Type
countCredential	The number of credentials issued by Mastercard. A value of `0` is reported by default if the replenishment process fails.	String
replenishResult	The result of the replenishment process. Valid values are: `true`: successful `false`: failed	String
errorCode	The error code associated with the failure. This field is returned if the replenishment process fails.	String
errorMsg	The error message associated with the failure. This field is returned if the replenish process fails.	String

Session rebuild monitor

monitorId = EVENT_SESSION

This monitor reports the following data when the SDK rebuilds a session with Mastercard Digital Enablement Service upon session expiration.

Field

Description

Type

sessionResult

The result of the session rebuilding process.

Valid values are:

true: successful
false: failed

String

errorCode

The error code associated with the failure.

This field is returned if the session rebuilding process fails.

String

BIN exchange monitor

monitorId = EVENT_CHANGE_BIN

This monitor reports the following data when the MPP app initiates the BIN changing process.

Field	Description	Type
current_id	The unique ID assigned by the SDK to identify the current connection.	String
enterChangeBin	Whether the BIN changing process is initiated. Valid values are: `true`: yes `false`: no	String
changeBinState	The state of the BIN changing process. Valid values are: `-1`: not initiated `0`: completed `1`: in progress	String

SDK risk control time-consuming monitor

monitorId = EVENT_RISK

This monitor reports the following data when the SDK risk control process is completed.

Field

Description

Type

ret

The result of risk control evaluation.

Valid values are:

true: risk detected
false: risk not detected

String

risk_time

The time spent for the risk control evaluation.

String

SDK identity verification monitor

monitorId = EVENT_AUTH_POLICY

This monitor reports the following data when the SDK identity verification process is completed.

Field	Description	Type
secure_screen	Whether the screen lock password is set. Valid values are: `true`: set `false`: not set	String
has_auth	Whether the identity has been verified. Valid values are: `true`: yes `false`: no	String
context_match	Whether the transaction context changes in the double-tapping scenario. Valid values are: `true`: changed `false`: not changed	String
policy_time	Time spent for the policy evaluation.	String
biz_permit	The permission decision returned by the business side SPI. Valid values are: `true`: permitted `false`: declined	String
risk_sdk	Whether the risk control SDK judgment has been initiated. Valid values are: `true`: yes `false`: no	String
policy_type	The type of security policies. Valid values are: `ConsentPolicy`: policy related to user consent `TransitPolicy`: policy related to transit transactions `RiskJudgePolicy`: policy related to risk assessment and evaluation `WithoutConsentPolicy`: no consent-related policy required	String

Transaction monitor

monitorId = EVENT_TRANSACTION

This monitor reports the following data when the transaction is completed.

Field	Description	Type
ret	The result of the transaction. Valid values are: `true`: successful `false`: failed	String
transaction_time	The time spent for this transaction.	String
command_sum	The total time spent for executing all commands within the transaction.	String
command_i	The time taken to execute the command with sequence number `i`. In the standard MCBP interaction, `i` ranges from 0 to 8.	String
errorCode	The error code associated with the failure. This field is returned if the transaction fails.	String
current_id	The unique ID to identify the current user.	String

connect API time-consuming monitor

monitorId = EVENT_CONNECT

This monitor reports the following data when the MPP app calls the connect API.

Field	Description	Type
core_init_time	The time taken to initiate the SDK core.	String
connect_time	The total time spent for the connection.	String
cache_init_time	The time taken to initiate the SDK cache.	String
current_id	The unique ID used to identify the current SDK.	String

disconnect API monitor

monitorId = EVENT_DISCONNECT

This monitor reports the following data when the MPP app calls the disconnect API.

Field	Description	Type
current_id	The unique ID used to identify the current connection.	String

auth API monitor

monitorId = EVENT_AUTH

This monitor reports the following data when the MPP app calls the auth API.

Field	Description	Type
is_auth	The value of the isAuth sub-parameter within the authInfo parameter.	String

Transaction information monitor

monitorId = EVENT_TRANSACTION_INFO

This monitor reports the following data when the transaction process is completed.

Field	Description	Type
mcc	The Merchant Category Code.	String
type	The type of the transaction.	String
amount	The transaction amount.	String
merchant_name	The name of the merchant. Note: The value of this field returns in HEX encoding.	String
country_code	The country code. Note: The value of this field returns in HEX encoding.	String
isDebitBin	Whether the card is a debit card. Valid values are: `true`: yes `false`: no	String
current_id	The unique ID to identify the current user.	String
customIAD	The customize data.	String
transit_check_advancepay_limit_switch	Whether the advance pay limit check is enabled. Valid values are: `0`: disabled `1`: enabled	String
transit_advancepay_limit_status	The status of the advance pay limit returned from the server APIs. Valid values are: `0`: The payment amount is limited. `1`: The payment amount is unlimited.	String

Event exception monitor

monitorId = EVENT_EXCEPTION

This monitor reports the following data when an event exception is detected.

Field	Description	Type
err_msg	The descriptive error message associated with this exception.	String
ext1	Additional information associated with this exception.	String
ext2	Additional information associated with this exception.	String

Initialization exception monitor

monitorId = EVENT_LAST_CRASH

This monitor reports the following data when an initialization related exception is detected.

Field	Description	Type
next_step_type	The action required after the last crash is detected.	String

White box initialization exception monitor

monitorId = EVENT_WB_EXCEPTION

This monitor reports the following data when a white box initialization exception is detected.

Field

Description

Type

err_msg

The error message returned upon detection of a white box initialization exception.

String

is_success

Whether the initialization is successful.

Valid values are:

true: successful
false: failed

String

Event listener monitor

monitorId = EVENT_ACTION

This monitor reports the following data when the scenarios defined in the Events section occur.

Field	Description	Type
current_id	The unique ID to identify the current SDK.	String
behavior	The action currently being performed by the SDK in this scenario.	String
ext	Additional information associated with this scenario.	String
msg	The message returned in this scenario.	String

Events

Scenario	behavior	ext	msg
Start to query for the exchange rate	Connected	/	SDK is already connected
Exchange rate query succeeded.	Destroy	/	SDK is already destroy
The isPaymentAvailable API is called but the token is not connected.	isPaymentAvailable	"currentStatus = " + `TokenStatus.TOKEN_NOT_CONNECTED`	TokenStatus.TOKEN_NOT_CONNECTED
The isPaymentAvailable API is called but the token is in progress.	isPaymentAvailable	"currentStatus = " + `TokenStatus.TOKEN_STATUS_IN_PROGRESS`	TokenStatus.TOKEN_STATUS_IN_PROGRESS
Calling isPaymentAvailable API is successful.	isPaymentAvailable	"currentStatus = " + `tokenStatus`	Query Token Status
The activatePayment API is called but the SDK is not connected.	activatePayment	`NFCActivateParams`	sdk is not connected
The activatePayment API is called but request parameters got issues.	activatePayment	"NFCActivateParams" + "config :" + `config.isNeedConfirmActivate()`	INPUT_PARAMS got issues
The activatePayment API is called but the device fingerprint service is null.	activatePayment	`NFCActivateParams`	Device FingerPrint Service is null
The activatePayment API is called but the device fingerPrint is empty or its length is less than 64-digit.	activatePayment	`deviceFingerPrint`	Device FingerPrint is empty or not exceed 64
Receive a push notification.	onNotificationDataReceived	`notificationData`	Receive Push Notification Data
Deactivate a transaction.	transactionDeactivate	/	processApdu transaction deactivate from terminal
Delete a card by server.	delete card	"tur=" + `tur`	IAPVirtualCardClientImpl: syncTokenStatusWithServer() by status == deactivated
Delete a card by push.	delete card	"tur=" + `tur` + ",pushTokenStatus=" + `pushTokenStatus`	IAPVirtualCardClientImpl: syncTokenStatusByPush() by status == deactivated
Sync token status by push.	syncTokenStatusByPush	"tur=" + `tur` + ",pushTokenStatus=" + `pushTokenStatus`	IAPVirtualCardClientImpl: syncTokenStatusByPush()
Initiate the SDK.	sdk init	/	NFCWrapperManager: init()
Reset the SDK.	sdk reset	/	NFCWrapperManager: reset()
Clear the SDK.	sdk clear	/	NFCWrapperManager: clear()
Set a default card.	device save card	"uid=$uid,cardId=$cardId"	NFCWrapperManager: setDefaultCard()
Check the local card status.	Check local card	"device has card = $hasCard"	NFCWrapperManager: canApplyToken()
Clear the `StorageServiceImpl`.	SharedPreferences clear	/	by StorageServiceImpl clear()
Clear the `SharePreferences`.	SharedPreferences clear	/	by SPManager clear()
Reset the `SharePreferences`.	SharedPreferences clear	/	by SPManager reset()

Database storage initiation monitor (SDK version 1.5)

Event id = EVENT_DB_STORAGE_INIT

Field	Description	Type
current_id	The unique ID to indentify the current user.	String
init_time	The total time spent to initialize the database.	String
is_migration	Whether to migrate data. Valid values are: `true`: migrate data `false`: do not migrate data	String
migration_ret	The result of data migration. Valid values are: `true`: successful `false`: failed	String
ret	The result of database initialization. Valid values are: `true`: successful `false`: failed	String

Database storage exception monitor (SDK version 1.5)

Event id = EVENT_DB_STORAGE_EXCEPTION

Field	Description	Type
current_id	The unique ID to indentify the current user.	String
err_msg	The error message about this exception.	String

Transaction result monitor (SDK version 1.5)

Event ID = EVENT_NEW_TRANSACTION

Field	Description	Type	Site
ret	The result of the transaction. Valid values are: `true`: successful `false`: failed	String	Alipay, AlipayHK
transaction_time	The total time spent to process the transaction.	String	Alipay, AlipayHK
command_i	The time taken to execute the command with sequence number `i`. In the standard MCBP interaction, `i` ranges from 0 to 8.	String	Alipay, AlipayHK
errorCode	The error code associated with the failure.	String	Alipay, AlipayHK
command_sum	The total time spent for executing all commands within the transaction.	String	Alipay, AlipayHK
apdu_node	The name of the last received APDU command.	String	Alipay, AlipayHK
cApdu	The content of the last received APDU command.	String	Alipay, AlipayHK
rApdu	The content of the last responded APDU command.	String	Alipay, AlipayHK
current_id	The unique ID assigned to identify a user.	String	Alipay, AlipayHK
tur	The unique ID assigned to identify a card.	String	Alipay, AlipayHK
os_version	The operation system.	String	Alipay, AlipayHK
model	The device model.	String	Alipay, AlipayHK
manufacturer	The device manufacturer.	String	Alipay, AlipayHK
mcc	The Merchant Category Code.	String	Alipay, AlipayHK
type	The type of the transaction. Valid values are: `PURCHASE`: ordinary transaction `REFUND`: refund `CASH`: cash withdrawl `TRANSIT`: transit transaction `PURCHASE_WITH_CASHBACK`: purchase with cashback `UNKNOWN`: unknown type	String	Alipay, AlipayHK
amount	The transaction amount.	String	Alipay, AlipayHK
merchant_name	The name of the merchant. The value of this field is hex-encoded.	String	Alipay, AlipayHK
country_code	The country code. The value of this field is hex-encoded.	String	Alipay, AlipayHK
isDebitBin	Whether the card is a debit card. Valid values are: `true`: The card is a debit card. `false`: The card is not a debit card. In the Alipay site, this parameter only returns `false`.	String	Alipay, AlipayHK
customIAD	The customized data.	String	Alipay, AlipayHK
transit_check_advancepay_limit_switch	Whether the advance pay limit check is enabled. Valid values are: `0`: disabled `1`: enabled	String	Alipay
transit_advancepay_limit_status	The status of the advance pay limit returned from the server APIs. Valid values are: `0`: The payment amount is limited. `1`: The payment amount is unlimited.	String	Alipay
connect_time	The total time spent for SDK initialization.	String	Alipay, AlipayHK
connect_timestamp	The time that the SDK initialization is finished.	String	Alipay, AlipayHK
transaction_info_json	The transaction information in JSON format.	String	Alipay, AlipayHK

Response parameters

N/A

Sample

The following is a sample about how to use this SPI:

copy
public class DemoNFCMonitor implements NFCMonitor {
    @Override
    public void track(String monitorId, Map<String, String> params) {
        params.put("monitor_type", monitorId);
        Log.d("NFC_MONITOR", JSON.toJSONString(params));
    }
}

The following is a sample of the returned params parameter:

copy
{"countCredential":"24","errorCode":"","errorMsg":"","monitor_type":"EVENT_REPLENISH","replenishResult":"true"}  