# 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

```java
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:

```java
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:

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