iOS SDK - Bluetooth Low Energy (BLE) Module

Use the endpoints of this module to enable integration with supported Bluetooth Low Energy (BLE) devices in order to detect a transmitted checkout token value and connect to the transaction without scanning a QR code. The primary use case for this functionality is drive-through transactions.

Initialize BLE Facade

Prior to invoking any transaction module endpoints:

  1. Create a new request object for the relevant coordinator.
  2. Implement the delegate for the coordinator to handle responses.
self.bLECoordinator = [[PDBLECoordinator alloc] init];
self.bLECoordinator setDelegate:self];

Set optional BLE properties

Configure either of the following optional settings for the BLE service.

Setting Description
@property(assign)BOOL beaconMode; Set to TRUE to run the library in a conectionless mode so that all BLE peripherals operate as iBeacons.
@property(nonatomic, assign)NSInteger scanningTimeOut; Set this property to the number of seconds for which the SDK will scan for supported BLE devices before disconnecting. If not set, the default value of 10 is applied.

registerBLEEvents

Enables the BLE service to notify the app when the specified events are detected.

Element Value
Method Signature -(void) registerBLEEvents:(NSArray *)events and Delegate:(idPDBLEEventNotificationDelegate)delegate;

events - The set of events about which the app will be notified. Possible values are:
0 kPDBLEEventUnknown - An event triggered by any activity other than a payment.
1 kPDBLEEventPayment - An event triggered by a Paydiant mobile payments checkout token.

delegate - Sets an instance of PDBLEEventNotificationDelegate as the listener for the events.
Success Successful completion of this call returns no payload.
Failure Failure returns the applicable error inherited from Apple's CoreBluetooth Foundation class.
Error Description
1 CHARACTERISTIC_NOT_FOUND
2 UNEXPECTED_DISCONNECTION
3 FAILED_TO_DISCOVER_SERVICES
4 GENERAL_FAILURE
5 FAILED_TO_DISCOVER_CHARACTERISTICS
6 CHARACTERISTIC_READ_NOT_PERMITTED
7 CHARACTERISTIC_WRITE_NOT_PERMITTED
8 FAILED_TO_CONNECT
9 FAILED_TO_READ_CHARACTERISTIC

pairBLEEvent

Enables the app to automatically read the data (such as the checkout token value) embedded in a detected event transmitted by a supported device.

Element Value
Method Signature -(void) pairBLEEvent:(PDBLEEvent)event andBLEDevices:(NSArray *)deviceParameters;

event - The event that the app wants to read. Possible values are:
0 kPDBLEEventUnknown - An event triggered by any activity other than a payment.
1 kPDBLEEventPayment - An event triggered by a Paydiant mobile payments checkout token.

deviceParameters - The set of PDBLEDeviceParameters instances for the devices known to the app from which the app would try to read a detected event.
Success Successful completion of the call returns no payload.
Failure Failure returns the applicable error inherited from Apple's CoreBluetooth Foundation class.
Error Description
1 CHARACTERISTIC_NOT_FOUND
2 UNEXPECTED_DISCONNECTION
3 FAILED_TO_DISCOVER_SERVICES
4 GENERAL_FAILURE
5 FAILED_TO_DISCOVER_CHARACTERISTICS
6 CHARACTERISTIC_READ_NOT_PERMITTED
7 CHARACTERISTIC_WRITE_NOT_PERMITTED
8 FAILED_TO_CONNECT
9 FAILED_TO_READ_CHARACTERISTIC

statusChanged Delegate

The BLECoordinator of the SDK invokes this delegate when it detects a change in the BLE connection state. Configure an app response for each possible status value returned by the delegate.

Element Value
Delegate -(void) pdBLECoordinator:(PDBLECoordinator *)pdBLECord statusChanged:(PDBLEStatus *)aNewStatus;

pdBLECoord - The BLE service to which the change applies.
aNewStatus - An enum value representing the updated status. Possible values are:
kPDBLEStatusUnknown (default)
kPDBLEStatusTurnedOn
kPDBLEStatusTurnedOff
kPDBLEStatusResetting
kPDBLEStatusUnauthorized
kPDBLEStatusNotSupported

didStopScanning Delegate

The BLECoordinator of the SDK invokes this delegate when the active scanning session stops scanning for new peripherals. Configure an app response based on the BLE status at the time scanning stops.

Note: Do not assume that the BLE service is turned off when new peripheral scanning has stopped; it may still be reading characteristics for peripherals that were discovered before the peripheral scanning stopped.

Element Value
Delegate -(void) didStopScanning:(PDBLECoordinator *)pdBLECord;

pdBLECoord - The BLE service that has stopped active scanning.

Note: It is a best practice to implement a 2-3 second programming delay before invoking a new scan in response to this delegate to avoid continuous scanning that can interfere with the timeout function. The following sample shows this delay:

- (void) didStopScanning:(PDBLECoordinator *)pdBLECoord {
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(2 * NSEC_PER_SEC)),  dispatch_get_main_queue(), ^{
        [self scan:nil];
    });
}

BLEEventReceived Delegate

The BLECoordinator of the SDK invokes this delegate when it successfully pairs with a supported BLE device and reads the relevant event information. Configure an app response for each possible event type.

Element Value
Delegate -(void) pdBLECoordinator:(PDBLECoordinator *)pdBLECord BLEEventReceived:(PDBLEEvent *)event withEventDictionary:(NSDictionary *)eventDict;

pdBLECoord - The BLE service that received the event.
event - The retrieved event. Possible values are:
0 kPDBLEEventUnknown - An event triggered by any activity other than a payment.
1 kPDBLEEventPayment - An event triggered by a Paydiant mobile payments checkout token.
eventDict - A dictionary object that maps received text references with their relevant event identifiers.