iOS SDK - Bluetooth Low Energy (BLE) Module

DOCS

Last updated: Aug 15th, 6:18am

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:

Create a new request object for the relevant coordinator.
Implement the delegate for the coordinator to handle responses.

1self.bLECoordinator = [[PDBLECoordinator alloc] init];
2self.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:(id<PDBLEEventNotificationDelegate>)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 WLW 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 WLW 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:

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

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 WLW mobile payments checkout token.
eventDict - A dictionary object that maps received text references with their relevant event identifiers.

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 WLW mobile payments checkout token. `eventDict` - A dictionary object that maps received text references with their relevant event identifiers.