Device Connection Criteria
Before attempting to connect to devices such as card readers and printers, the integrator has the option to set the specific connection criteria to use during the device search. This will ensure that Commerce SDK will only attempt to search for the devices specified by the integrator, which will result in a faster connection to the device. The connection criteria are also used for specifying the details of a connection over an IP channel, such as the IP address, port, and encryption type.
Setting the connection configuration is only required if IP connection parameters need to be specified. If not set, Commerce SDK will search for all other supported devices by default.
Note that this method is only used to setup the connection configuration that will be used for future device searches. For an example of performing an actual device search that will use the connection configuration set by this method, see [doclink id=“card-reader-connection”]Card Reader Connection[/doclink].
note
All data transferred over IP has a TLS (formerly known as SSL) encryption scheme where the card reader acts as a server and Commerce SDK is the client.
Timings: CSDK Find Devices vs CSDK 4.1
Pinpad | Sample App | Connection Type | Find Devices | 1st SALE | Find Devices | Connect | 4.1 1st SALE | 4.1 Find/Connect |
---|---|---|---|---|---|---|---|---|
Default | Defined Values | Default | Defined Values | |||||
Link 2500 | C♯/CWS | USB | 3.59 secs | 2.33 secs | 2.39 secs (OnDemandApp-CardReaderSearch) | 2.05 secs (OnDemandApp-CardReaderSearch) | 3.39 secs | 6.26 secs (OnDemandApp-CardReaderSearch) |
Link 2500 | C♯/CWS | Wi-Fi | 17.39 secs | 16.89 secs | 17.23 secs (OnDemandApp-CardReaderSearch) | 15.64 secs (OnDemandApp-CardReaderSearch) | 17.00 secs | 2.60 secs (OnDemandApp-CardReaderSearch) |
Link 2500 | Android | WI-FI | 24 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) | 17 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) | 18 seconds (including time to select the device after initial find/connect to when it’s initialized) 18 sec | 13 seconds (including time to select the device after initial find/connect to when it’s initialized) 9 sec | 19 sec | 16 sec |
Link 2500 | iOS | WI-FI | 5 seconds | 5 seconds | 6 seconds | 4 seconds | 10 seconds | 8 seconds |
Link 2500 | IOS | BT | 6-7 seconds | 5 seconds | 5 seconds (including time to select the device after initial find/connect to when it’s initialized) | 5 seconds (including time to select the device after initial find/connect to when it’s initialized) | 12 secs (from starting SALE on sample app to Insert, Swipe or Tap screen) | 9 seconds |
ICMP | Android | BT | 20 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) | 8 seconds | 19 seconds (including time to select the device after initial find/connect to when it’s initialized) | 7 seconds (including time to select the device after initial find/connect to when it’s initialized) | 16 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) | 9 seconds |
ICMP | IOS | BT | 6 sec | 5 seconds | 6 seconds | 6 seconds | 12 secs (from starting SALE on sample app to Insert, Swipe or Tap screen) | 11 sec |
ICMP | C♯/CWS | USB | 4.74 secs | 2.23 secs | 5.92 secs (OnDemandApp-CardReaderSearch) | 2.46 secs (OnDemandApp-CardReaderSearch) | 4.42 secs | 7.54 secs (OnDemandApp-CardReaderSearch) |
ROAM | Android | Audio | 21 sec | 13 sec | 22 seconds | 10 seconds | 33 seconds | 32 seconds |
ROAM | IOS | BT | 4 | 2.75sec | 4.65 sec | 2.71 sec | 2.95 | 2.81sec |
ISC250 | C♯/CWS | USB | 5.78 secs | 2.99 secs | 2.59 secs (OnDemandApp-CardReaderSearch) | 2.52 secs (OnDemandApp-CardReaderSearch) | 5.47 secs | 3.13 secs (OnDemandApp-CardReaderSearch) |
ISC250 | C♯/CWS | IP | 18.75 secs | 11.49 secs | 18.62 secs (OnDemandApp-CardReaderSearch) | 20.61 secs (OnDemanApp-CardReaderSearch) | 25.19 secs | 18.15 secs (OnDemandApp-CardReaderSearch) |
iSC250 | iOS | IP | 6 seconds | 5 seconds | 5-6 seconds | 5 seconds | 11 seconds | 11 seconds |
IPP320 | C♯/CWS | USB | 4.93 secs | 2.64 secs | 2.52 secs (OnDemandApp-CardReaderSearch) | 2.44 secs (OnDemandApp-CardReaderSearch) | 4.27 secs | 2.25 secs (OnDemandApp-CardReaderSearch) |
IPP320 | C♯/CWS | IP | 21.30 secs | 17.29 secs | 6.59 secs (OnDemandApp-CardReaderSearch) | 2.51 secs (OnDemandApp-CardReaderSearch) | 22.03 secs | 16.07 secs (OnDemandApp-CardReaderSearch) |
note
For C♯/CWS: CWS was stopped/restarted before every test run. Connection times reflect first transaction connection times.
Prerequisites for IP Configuration
- Configure the card reader to accept plain data transfer over IP.
- Establish IP-based communication channel between application and card reader.
- Enable SSL on the card reader (refer to the Client Certificate for IP Communication section of the appropriate integration method).
Code Samples
CWS
Request
Property | Description |
---|---|
method string | required | setDeviceConnectionConfiguration |
requestId string | required | Transaction Request ID |
targetType string | required | api |
parameters JSONObject | required | All relevant parameters for card reader configuration. |
connectionCriteria JSONObject | required | Device Connection Criteria Holds the device connection parameters. |
providerTypes array | required | Device Provider Types Valid values: - INGENICO_RBA_UPP - ROAM_RUA - MAGTEK - STAR - EPSON - RDM |
connectionTypes array | required | Connection Types Valid values: - USB - BT - IP - AUDIO |
deviceTypes array | required | Device Types Valid values: - CARD_READER<BR> - PRINTER CHECK_READER |
inetAddress JSONObject | optional | INET Address Specifies the host, port, and encryption scheme of the INET address. Important: Required if connectionTypes contains IP. |
host string | required | Host IP Address |
port int | required | Port Number |
encryptionScheme string | required | Encryption Scheme Indicates whether or not the IP channel is TLS-enabled. Set to TLS_12 to encrypt the data. |
Response
Property | Description |
---|---|
requestId string | Transaction Request ID As specified in the request. |
statusDetails string | Request Status |
data JSONObject | Object holding various responses. |
completed boolean | Request Result Device configuration result. Valid values: - true - false |
error string | If an error occurred. |
Example
Request
{
"method" : "setDeviceConnectionConfiguration",
"requestId" : "1253881538",
"targetType" : "api",
"parameters" : {
"connectionCriteria" : {
"providerTypes" : ["INGENICO_RBA_UPP", "STAR"],
"connectionTypes" : ["USB", "IP"],
"deviceTypes" : ["CARD_READER", "PRINTER"],
"inetAddress" : {
"host" : "192.168.1.137",
"port" : 12000,
"encryptionScheme" : "NONE"/"TLS_12"
}
}
}
}
Response
{
"requestId" : "1253881538",
"statusDetails" : "REQUEST_ACCEPTED",
"data" : {
"completed" : true
}
}
getDeviceConnectionConfiguration
There is additional request/response for getDeviceConnectionConfiguration:
Request
Property | Description |
---|---|
method string | required | getDeviceConnectionConfiguration |
requestId string | required | Transaction Request ID |
targetType string | required | api |
Response
Property | Description |
---|---|
requestId string | Transaction Request ID As specified in the request. |
statusDetails string | Request Status |
data JSONObject | Object holding various responses. |
completed boolean | Request Result Get Connection Configuration result. |
connectionCriteria JSONObject | Object holding the current connection criteria. |
providerTypes array | Array of Provider Types |
connectionTypes array | Array of Connection Types |
deviceTypes array | Array of Device Types |
inetAddress JSONObject | INET Address Specifies the host, port, and encryption scheme of the INET address. |
host string | Host IP Address |
port int | Port Number |
encryptionScheme string | Encryption Scheme Indicates whether or not the IP channel is TLS-enabled. |
Request
{
"method" : "getDeviceConnectionConfiguration",
"requestId" : "1253881539",
"targetType" : "api"
}
Response
{
"requestId" : "1253881539",
"statusDetails" : "REQUEST_ACCEPTED",
"data" : {
"completed" : true
"connectionCriteria" : {
"providerTypes" : ["INGENICO_RBA_UPP", "STAR"],
"connectionTypes" : ["USB", "IP"],
"deviceTypes" : ["CARD_READER", "PRINTER"],
"inetAddress" : {
"host" : "192.168.1.137",
"port" : 12000,
"encryptionScheme" : "TLS_12"
}
}
}
}
Java
Set Up
Retrieve an instance of
ECLConnectionConfiguration
.The call to
getInstance()
returns a reference to a global singleton object, so you cannot have multipleECLConnectionConfiguration
at the same time.Create an
ECLConnectionCriteria
and set it.You can get the currently set
ECLConnectionCriteria
at any time.
Code Sample
ECLConnectionConfiguration config = ECLConnectionConfiguration.getInstance();
EnumSet<ECLDeviceProviderType> providerTypes = EnumSet.of(ECLDeviceProviderType.INGENICO_RBA_UPP, ECLDeviceProviderType.ROAM_RUA, ECLDeviceProviderType.STAR);
EnumSet<ECLConnectionType> connectionTypes = EnumSet.of(ECLConnectionType.AUDIO, ECLConnectionType.BT, ECLConnectionType.IP);
EnumSet<ECLDeviceType> deviceTypes = EnumSet.of(ECLDeviceType.CARD_READER, ECLDeviceType.PRINTER);
ECLConnectionCriteria.Builder criteriaBuilder = new ECLConnectionCriteria.Builder();
ECLConnectionCriteria criteria = criteriaBuilder
.setEnabledDeviceProviderTypes(providerTypes)
.setEnabledConnectionTypes(connectionTypes)
.setEnabledDeviceTypes(deviceTypes)
.setInetAddress(new ECLInetAddress(ip, port, ECLEncryptionScheme.TLS_12))
.setConnectionParameters(connectionParameters)
.setClientKeystoreDate(keystoreDateYYYYMMDD)
.build();
try
{
config.setConnectionCriteria(criteria);
}
catch (ECLCommerceException ece)
{
showError("Connection Configuration Exception", "Error trying to set connection criteria: %s", ece.getCode().name());
}
//get
ECLConnectionCriteria currentCriteria = config.getConnectionCriteria();
Reset Connection Configuration
You can reset the connection configuration to the default, which will search for all supported devices.
try
{
config.setConnectionCriteria(null);
}
catch (ECLCommerceException ece)
{
//should not get this when setting to null
}
note
Do not reset the connection configuration while a device search is in progress.
Objective-C (iOS)
Set Up
- Use
ECLConnectionConfiguration:sharedInstance
to retrieve the globalECLConnectionConfiguration
instance. The call toECLConnectionConfiguration:sharedInstance
returns a reference to a global singleton object, so you cannot have multipleECLConnectionConfiguration
at the same time. - Create an
ECLConnectionCriteria
object and set it. - You can get the currently set
ECLConnectionCriteria
at any time, usingECLConnectionConfiguration:getConnectionCriteria:
.
Code Sample
// Get ECLConnectionConfiguration global instance...
ECLConnectionConfiguration *connectionConfiguration = [ECLConnectionConfiguration sharedInstance];
// Define what device providers, connection types, and device types you wish to search for...
NSSet <NSNumber *> *enabledDeviceProviderTypes = [NSSet setWithArray:@[@(ECLDeviceProviderType_INGENICO_RBA_UPP),@(ECLDeviceProviderType_ROAM_RUA),@(ECLDeviceProviderType_STAR)]];
NSSet <NSNumber *> *enabledConnectionTypes = [NSSet setWithArray:@[@(ECLConnectionType_AUDIO),@(ECLConnectionType_BT),@(ECLConnectionType_IP)]];
NSSet <NSNumber *> *enabledDeviceTypes = [NSSet setWithArray:@[@(ECLDeviceType_CARD_READER),@(ECLDeviceType_PRINTER)]];
ECLConnectionCriteria *criteria = [ECLConnectionCriteria makeWithBuilder:^(ECLConnectionCriteriaBuilder *builder) {
builder.enabledDeviceProviderTypes = enabledDeviceProviderTypes;
builder.enabledConnectionTypes = enabledConnectionTypes;
builder.enabledDeviceTypes = enabledDeviceTypes;
builder.inetAddress = [[ECLInetAddress alloc] initWithHostAndClientCertificateInfo:@"192.168.1.1"
port:@(12000)
encryptionScheme:ECLEncryptionScheme_TLS_12
validClientPFXFilePath:certificateKeystorePath
validClientPfxFilePasscode:certificateKeystorePassword
validClientPfxFileDate:certificateKeystoreDate
expiredClientPFXFilePath:expiredCertificateKeystorePath
validPfxFilePasscode:expiredCertificateKeystorePasscode
];
}];
// Set the new search criteria for the global ECLConnectionConfiguration instance...
ECLError *error = [connectionConfiguration setConnectionCriteria:criteria];
if (error == nil)
{
// No error? Then, the connection criteria has been successfully set!
}
else
{
// If an error is returned, please see documentation for each possible ECLConnectionConfiguration:setConnectionCriteria: error (e.g. ECLConnectionCriteriaEmptyDeviceProviderTypes).
}
Reset Connection Configuration
You can reset the connection configuration to the default, just like in Java, which will search for all supported devices.
// Since the criteria is set to the default, ECLConnectionConfiguration:setConnectionCriteria: will always return nil.
ECLError *error = [connectionConfiguration setConnectionCriteria:nil];
C#
private void MySetDeviceConfigComplete(SetDeviceConfigResults crc)
{
String statusDetails = crc.StatusDetails;
if ((null != statusDetails) && (0 < statusDetails.Length))
Log("Status Details: " + statusDetails);
String error = crc.Error;
if ((null != error) && (0 < error.Length))
Log("Error: " + error);
else
Log("No error");
}
DeviceConnectionCriteria connCriteria = new DeviceConnectionCriteria();
connCriteria.providerTypes = new string[] { DeviceProviderType.INGENICO_RBA_UPP, DeviceProviderType.STAR };
connCriteria.connectionTypes = new string[] { ConnectionType.USB, ConnectionType.IP };
connCriteria.deviceTypes = new string[] { DeviceType.CARD_READER, DeviceType.PRINTER };
connCriteria.inetAddress = new InetAddress("121.121.12.12", 12000, EncryptionScheme.TLS_12);
DeviceConfigArgs args = new DeviceConfigArgs();
args.connectionCriteria = connCriteria;
m_CWS.StartSetDeviceConfig(args, MyNotifyCWSEvent, MySetDeviceConfigComplete);
// Get
private void MyGetDeviceConfigComplete(GetDeviceConfigResults crc)
{
DeviceConnectionCriteria connCriteria = crc.GetConnectionCriteria;
}
m_CWS.StartGetDeviceConfig(MyNotifyCWSEvent, MyGetDeviceConfigComplete);