Android SDK - Logging Utility

The com.paydiant.android.common.util.PaydiantLoggingUtility utility class exposes the functionality that allows the app to inform the WLW platform of its activity based on key event triggers, such as payment, logout, data retrieval, etc. This logging information is critical to providing accurate and efficient technical support and troubleshooting.

As of SDK version 4.6, the WLW Logging Utility automatically logs all events that pass through the mobile gateway, so the developer does not need to specifically configure events and event parameters to be logged or determine when the logs should be submitted.

Developers have the option of disabling this internal logging feature in favor of defining a custom approach to log messages for each SDK event. The Android SDK also supports a hybrid approach to SDK event logging, in which custom logging can be used in conjunction with internal logging in order to provide additional information. This chapter discusses the methods that are exposed in the SDK that allow developers to leverage WLW’s internal logging as well as the custom logging mechanisms to ensure that the most useful information is captured for efficient and effective technical support and troubleshooting.

Alternatively, developers can bypass the WLW Logging Utility entirely and implement a logging utility that is more specifically tailored to the business logic required by the issuer. Refer to the Custom Logging Utility, for details about the SDK methods and logging format specification required to initialize an alternative logging utility class.

Using the WLW Logging Utility

The com.paydiant.android.common.util.PaydiantLoggingUtility class uses the com.paydiant.android.ui.service.logging.PaydiantLoggingService class to submit log entries.

To add the functionality of provided by the WLW Logging Utility, add the PaydiantLoggingService class as a service to the AndroidManifest.xml.

1< ?xml version="1.0" encoding="utf-8"? >
2< manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >
3...
4< application ... >
5...
6< service android:name = "com.paydiant.android.ui.service.logging.PaydiantLoggingService" / >
7...
8< /application >
9< /manifest >

As of SDK 5.10, the app no longer needs to initialize the loggin utility explicitly. If the service is included in the AndroidManifest, the SDK will automatically initialize the class.

Setting Error Display Messages for Internally Logged Events

During a failure event (such as an exception thrown during a payment), the error message displayed to the wallet owner must be set within the failure logging message for internally logged events. Otherwise, the SDK will have no means of connecting the failure event to the displayed error and, should the user contact tech support and describe the behavior in the app, the logs will have no record of the error message that the user describes, making troubleshooting very difficult.

WLW exposes an Add Failed Event Log Message method in the PaydiantLoggingUtility to pass the error display message in the failure logging entry. Invoke this call immediately upon a failure event (even before actually displaying the error message) because certain events (such as payment and login failures) are configured to submit the logging entry immediately upon occurrence and any delays in setting the error message may result in its omission from the logged entry.

Disable Internal Logging for Select Events

To implement custom logging for individual events, but keep internal logging for other events, set setCustomLoggingEnabled=TRUE immediately prior to calling the relevant event’s SDK method, then set setCustomLoggingEnabled=FALSE after handling the success and failure callbacks for the method.

Logging Event Types

The WLW Logging Utility automatically creates log entry messages for the event types defined in the com.paydiant.android.core.enums.PaydiantLoggingEventType enum class.

The following table provides the list of default event types, which developers can reference for use when providing custom logging implementations.

Some events take parameters that must be populated with values returned by the server upon event completion. Events for which parameter values are required list the required parameters in the description and each parameter is a hyperlink to its definition in Table 6.

Logging utility event types

Logging Event Parameters

The logging event parameters included with the event types defined in Table 5 above are provided as set of key/value pairs, with keys defined in the com.paydiant.android.core.enums.PaydiantLoggingEntryKey enum class. Table 6 lists the event parameters available in the WLW Logging Utility.

Unavailable event parameters

Available logging events

The following event parameters are available for use in logging events.

SCAN_EVENT_TOKEN

Value returned when a token is successfully captured.

TRANSACTION_EVENT_TX_TYPE

Attribute value that specifies the type of transaction, such as purchase, refund, cash access, etc.

TRANSACTION_EVENT_REF_ID

Transaction reference id that uniquely identifies a specific transaction.

TRANSACTION_EVENT_MERCHANT_NAME

The value that identifies the mobile wallet acceptance merchant. for the transaction.

TRANSACTION_EVENT_STORE_LOCATION_NAME

The value that identifies the merchant location where the transaction occurred.

TRANSACTION_EVENT_PAYMENT_TOTAL

The final amount exchanged for the transaction.

RECEIPTS_EVENT_COUNT

The number of receipts returned from a successful retrieval.

DEVICE_STATUS_CHECK_EVENT_ACTIVE

The device’s active status.

DEVICE_STATUS_CHECK_EVENT_REGISTERED

The device’s registered status.

CUSTOM_MESSAGE_KEY

A key that can be used to send custom messages to the logs.

LATITUDE

A key that can be used to check the latitudinal position of the device at the time of the event.

LONGITUDE

A key that can be used to check the longitudinal position of the device at the time of the event.

ROUNDTRIP_DURATION

The amount of time, in milliseconds, that elapsed for the completion of a call, from the initial request to the completion of the response.

LOCATION_LOGGING_ENABLED

A key that specifies whether including the geo-location of the device in the log message is enabled in the SDK instance. The default value is NO.

SDK_VERSION

The version of the SDK on which the current app was a built.

LOYALTY_REGISTRATION_STATUS

The value of the setting indicating whether the wallet user is enrolled in the loyalty program.

TX_FLOW_STEP

The value of the flow rule that was executing at the time the event occurred.

APP_VERSION_CODE

Key indicating the versionCode attribute value set in the AndroidManifest.xml file.

BLE_DEVICE_NAME

Key indicating the name of a broadcasting BLE device discovered by the app.

BLE_DEVICE_ADDRESS

Key indicating the UUID of the discovered BLE device.

BLE_SERVICE_ID

Key indicating the name of a discovered BLE service.

BLE_SERVICE_UUID

Key indicating the UUID of the discovered BLE service.

BLE_SERVICES

A list of all BLE services (by name and UUID) discovered by the app.

BLE_SCAN_START

A timestamp that identifies when the BLE service began scanning, in the format MM/dd/yyy HH:mm:ss Z.

BLE_SCAN_END

A timestamp indicating when the BLE service stopped scanning, in the format MM/dd/yyy HH:mm:ss Z.

SDK_PROFILE_START_DATE

The timestamp indicating when the call was sent by the SDK, in the format MM-dd-yyy hh:mm:ss.

SDK_PROFILE_DURATION

The amount of time, in nano seconds, that it took for the call to complete.

Logging Utility Methods

The following methods are available for use by the developer to utilize the functionality of the WLW Logging Utility.

Initialize WLW logging utility

This method initializes the WLW Logging Utility and creates an instance for the purpose of collecting and sending log entries. This must be called before using any of the methods of the Logging Utility.

Get instance

Retrieves the instance of the WLW Logging Utility created by the init method. If this method is called before the init method, it throws the UnsupportedOperationException. Use init(ContextWrapper, int, boolean) to initialize the singleton instance.

Activate custom logging

For SDK instances where the default internal logging of the WLW Logging Utility is not desired, developers should invoke this method to disable the feature and avoid duplicate logging.

Add successful event log message

Use these overloaded methods to record log messages for successful operations originating from within the SDK.

Use the following method to log success events that require addition data to be passed, such as token values, transaction reference ids, etc.

Add successful external event log message

Use this method to record log messages for successful wallet-related events that occur outside this SDK, such as social media activity or store location searches. Use the eventParameters attribute to pass any additional information that is relevant to the event.

Add failed event log message

Use these overloaded methods to log failed events. Any user prompts and exceptions thrown by the SDK should be included.

Use the following method to log success events that require additional data to be passed, such as token values, transaction reference ids, etc.

Add failed external event log message

Use this method to record log messages for failed wallet-related events that originate outside this SDK, such as social media activity or store location searches. Use the eventParameters attribute to pass any additional information that is relevant to the event or its cause for failure.

Add display message to failed event log

This method appends the log message for each failed event in the log with the message that was displayed to user in conjunction with the failure event. For example, the display message for a PASSWORD_UPDATE_FAIL event might be "The password must contain at least 1 capital and one number. Please try again." Developers should incorporate the display messages configured in the app for each different error condition that produces a failure for which a message is displayed to the user in the app in order to facilitate efficient and effective technical support.

Send log messages

Submits the queue contents to the backend for logging. Sending log messages should be performed during the following key events:

• User Logoff
• Successful or failed sales, refunds and cash access operations
• Successful or failed user registration
• Device Unlink

Effective as of SDK 4.6, when the SDK is configured to use internal logging, developers are no longer required to send log messages for the noted key events above. However, if customer logging is fully enabled or partially enabled for any of the key events listed above, developers are still responsible for submitting log messages upon completion of any of these events that are not utilizing the SDK’s internal logging feature.