iOS SDK - Developer Tools

WLW'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 WLW platform.

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

• Location Services
• User Error Messages
• Logging Utility
• Network Monitoring
• Activity Tracking

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). WLW’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.

1<key>NSLocationWhenInUseUsageDescription</key>
2<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;

User Error Messages

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

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

1[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.

Create a log message

|+ (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.

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.

Configure log file

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

1{
2    NSMutableArray *msgs;
3    unsigned int nextMsg;
4}
5    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;

Network Monitoring

Periodically check a device's connectivity and ability to reach the WLW 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.

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;