iOS SDK - Developer Tools

Paydiant's iOS SDK provides a set of utility methods, properties, and classes to aid in the development and certification of a mobile wallet app for the Paydiant platform.

For steps on setting up your development environment, see iOS Mobile SDK 101: Setup Your Development Environment.

Location Services

If the issuer supports Location-Based Services (LBS) to find near-by merchants, target offers, etc., using the GPS location of the device, use the following utilities to initialize and configure LBS for your app.

Check LBS instance

Determine whether an instance of the location manager has been created.

-(BOOL)isLBSStarted;

Initialize LBS

Create a shared instance of the location manager at the time of SDK instantiation.

-(void)initLBS;

Check LBS status

Determine whether LBS is currently turned ON for the SDK instance. Returns TRUE if the service is already enabled or FALSE if LBS is disabled.

-(BOOL)isLBSEnabled;

Enable/Disable LBS

Toggle LBS operation by passing YES or NO in the isEnabled parameter. Default is YES.

-(void)enableLBS:(BOOL)isEnabled;

Start/Stop LBS

Temporarily suspend or continue location collection as needed, such as when the app is in the background, without completely disabling the service.

-(void)startLBS; -(void)stopLBS;

Set when in use operation

iOS supports LBS configuration settings of Always and WhenInUse(location data is collected only when the app is running in the foreground on the device). Paydiant’s SDK automatically configures the WhenInUse setting in order to avoid the automatic iOS authorization message displayed to users when an app is configured for Always, giving the user the option to turn location services off entirely.

Add the NSLocationWhenInUserUsageDescription key to the app’s information property list (info.plist) file to ensure that the setting is honored.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Populate the StoreFinder feature to display participating locations near the user’s current location.</string>

Collect the Device Location

Retrieve the geographic coordinates of the device for use in location-dependent services in the app or appending location data to event log messages.

-(NSString *)getDeviceLocationLongitude; -(NSString *)getDeviceLocationLatitude;

Note: These calls return 0 when LBS is not initialized. Check LBS Instance before invoking.

User Error Messages

Map error messages displayed to the wallet user to their originating errors to facilitate troubleshooting and application support services.

Element Description
Method -(void)setUserErrorMessage:(NSString *)anErrorMessage forErrorDomain:(NSString *)domainKey errorCode:(NSString *)anErrorCode

anErrorMessage - The text of the message that is displayed to the end user when the error occurs. Once set, the message is defined in the PDUserErrorMessageCollection dictionary within the PDPaydiantContext object.
domainKey - The domain key that identifies the specific SDK module and call during which the error occurred.
anErrorCode - Paydiant's error code that triggers the specified message when returned by the corresponding domain module.

The following sample shows a call to set the user message for a failed login in which the PIN entered was not correct.

[self.messageCollection setUserErrorMessage:@"The PIN entered is not correct. Please try again." forErrorDomain:kUserErrorLoginWithPinDomain errorCode:@"401"]

Logging Utility

The SDK records relevant events that are transmitted through the mobile gateway (see SDK Logged Events.

Configure the app to log the following events that occur locally in the app and are not handled by the SDK to aid in reporting and troubleshooting support.

Event Send to Server Immediately Message Syntax
accounts_refresh_success FALSE result:accounts_refresh_success
accounts_refresh_fail FALSE result:accounts_refresh_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<
receipts_refresh_success FALSE result:receipts_refresh_success
receipts_refresh_fail FALSE result:receipts_refresh_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<
username_save_success FALSE result:username_save_success
username_save_fail FALSE result:username_save_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<
saved_username_retrieve_success FALSE result:saved_username_retrieve_success
saved_username_retrieve_fail FALSE result:saved_username_retrieve_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<
single_account_refresh_success FALSE result:single_account_refresh_success
single_account_refresh_fail FALSE result:single_account_refresh_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<
single_available_offer_refresh_success FALSE result:single_available_offer_refresh_success
single_available_offer_refresh_fail FALSE result:single_available_offer_refresh_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<
single_my_offer_refresh_success FALSE result:single_my_offer_refresh_success
single_my_offer_refresh_fail FALSE result:single_my_offer_refresh_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<
single_available_offer_retrieve_success FALSE result:single_available_offer_retrieve_success
single_available_offer_retrieve_fail FALSE result:single_available_offer_retrieve_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<
single_my_offer_retrieve_success FALSE result:single_my_offer_retrieve_success
single_my_offer_retrieve_fail FALSE result:single_my_offer_retrieve_fail&#124;userMsg:>&#124;errCode:###&#124;errDesc:<

Create a log message

Element Description
+ (PDLogMessage*) message:(NSString *)what when:(NSString *)when val:(NSString *)val;

what - The text message that is written to the log, using the Message Syntax convention.
when - The time at which the event fired.
val - The sequential number of the message in relation to the maximum allowed messages.

Append location data to log message

If location logging is enabled for the issuer (by default it is not), set how often the geo-location of the device should be appended to log messages.

Element Description
Setting -(void)setLocationService:(nonatomic,assign) PDLocationLoggingService locationService;

kPDLoggingAllLocationUpdates - Include the geo-location in every logged event. Use this setting if your app requires fine-tuning of location event delivery.
kPDLoggingSignificantUpdates - (DEFAULT) Include the geo-location only to identify the initial location and then again only if the location changes by a significant distance.

Configure log storage

In the SDK Instance Configuration utility, configure whether and how many logged messages are maintained in memory when they cannot be transmitted to the server immediately.

Element Description
Setting -(void)setStoreLogsInMemory:(BOOL)storeOrNot;
-(void)numberOfLogsInMemory:(NSInteger)numberOfLogs;

Tip: This setting directly affects memory usage. Paydiant recommends a limit of 10.

Configure log file

Configure the maximum number of messages a log can contain, how messages are overwritten, and when messages are sent to Paydiant.

{
    NSMutableArray *msgs;
    unsigned int nextMsg;
}
    LoggingUtilMaxMessages 100

Add a single message to the log when the event occurs

- (void)addMessage:(PDLogMessage*)msg networkCoordinator:(PDNetworkCoordinator *)networkCoordinator;

Replace a previously logged message for the same event

- (void)replaceMessage:(PDLogMessage*)msg networkCoordinator: (PDNetworkCoordinator *)networkCoordinator;

Clear the log of all existing messages

-(void)reset;

Export the list of messages to a transmittable format

- (NSMutableDictionary *)getMessagesAsDict;

Retrieve the device model for use in troubleshooting and reporting

- (NSString *)getDeviceModel;

Send the log data

- (void)sendLogToServer:(PDNetworkCoordinator *)networkCoordinator;

Important: If the method fails, the log is maintained in memory until the transmission succeeds, but if the maximum number of messages is reached, messages will be overwritten in the order they were originally recorded, whether they have been successfully transmitted or not.

Network Monitoring

Periodically check a device's connectivity and ability to reach the Paydiant through the mobile gateway host.

Initialize Network Utility

-(id)initWithHostName:(NSString *)hostName;

Check Generic Reachability

-(BOOL) isHostReachable;

Check WIFI

-(BOOL) isHostReachableViaWIFI;

Specify WIFI

-(NSString *) nameOfWifi;

Check WWAN

-(BOOL) isHostReachableViaWWAN;

Specify WWAN

-(NSString *) nameOfWWAN;

Enable Notifications

-(BOOL) startNotifier;

Disable Notifications

-(BOOL) stopNotifier;

Change Notifications

Receive notification when the network status, heartbeat, or reachability changes.

-(void) networkCoordinator:(PDNetworkCoordinator *)pdNetworkCoordinator networkStatusChanged:(PDNetworkStatus)networkStatus;

Reset

Automatically check connectivity whenever the app has been sent to the background and then returns.

-(void) reset;

Activity Tracking

Track start and end times of the wallet user's activity in the app for the following event keys.

Event Key Description
AUTH_LOGIN_START
AUTH_LOGIN_END
Timestamps for starting and completing a login request.
AUTH_GET_FINPRINT_START
AUTH_GET_FINPRINT_END
Timestamps for starting and completing the fingerprint generation.
AUTH_GEN_APPID_START
AUTH_GEN_APPID_END
Timestamps for starting and completing the application identification process.
AUTH_LOGIN_WITH_MFA The time at which the MFA device registration was requested.
AUTH_LOGIN_END The time at which the registration and login process completed.

Log an NSDate object timestamp

+(void)logCollectedTimeWithId:(NSDate *)eventTime ids:(NSString *)identifier;

Log an iOS mach timestamp

+(void)logCollectedTimeWithIdMachTime:(uint64_t) eventTime ids:(NSString *)identifier;

Retrieve statistics

+(NSMutableDictionary *)retrieveCollectedStatistics;

Verify statistic collection

+(BOOL) isStatisticCollected: (NSString *)identifier;

Clear statistics

+(void) clearAllStatistics;

Feedback

Have feedback?

Let us know.