Print API: Custom America Printers

The Custom America Printer API allows printing of simple text, certain HTML elements, bar codes, and QR codes to supported Custom America thermal printers. 

In addition, the Custom America Printer API can return information about the results of a specific printing job and the status of a connected Custom America printer.

Primary Functions

Formatting Functions

Callbacks

Related Settings

Requirements

  • JavaScript API > Access JavaScript API
    • 'By Import' - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
    • 'By Injection' - only works offline, may not be available 'onload' event.
  • Printing > Custom America Printer = On
  • Printing > Custom America Printer Settings > Select Custom America Printer = selected
  • Connection to a supported Custom America printer

Supported Devices

This app supports the following Custom America thermal kiosk printers:

D-ONE K3 KPM150H
KPM180H KPM216H 200 dpi KPM216H 300 dpi
KPM216H ETH 200 dpi KPM216H ETH 300 dpi KPM302H
KUBE KUBE ETHERNET mPLUS2
MY3A MYPRINTER PLUS2
PLUS4 Q1 Q3
TG02-H TG2460H TG2480H
TL60 TL80 VK80
VKP80II VKP80II ETHERNET VKP80III

Your iOS device must be connected to the Custom America printer either through a local WiFi connection or via Bluetooth (recommended), which must be configured prior to app launch in iOS Settings.

For more information about Custom America printers, you can visit CustomAmerica.com. In addition, Custom America has a utility app available through the iTunes App Store that can be used for testing and configuration, available for free here.

Sample Code

This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.  
To run sample code, set the app's homepage to http://www.kioskproapp.com/custom-print

kp_CustomAmericaPrinterAPI_printText

This function prints the text parameter defined.

Format
kp_CustomAmericaPrinterAPI_printText(text, pixelLeftAlign, pixelTextWidth, feed, wordWrap, callback);
		
Parameters
  • text = text to be printed, formatted as a string.
  • pixelLeftAlign = the left margin in pixels, formatted as a string.
  • pixelTextWidth = text width in pixels, formatted as a string. Pass '-1' to use maximum available width.
  • feed = integer representing whether to automatically add a line feed at the end of the request. Possible values are:
    • 1 = adds a line feed.
    • 0 = does not add a line feed and the next print request will print immediately following this one without a break.
  • wordWrap = integer representing whether to automatically wrap words at the end of a line, using the 'Word Wrap Page Width' in Kiosk Pro settings. Possible values are:
    • 1 = formats the text with word wrapping.
    • 0 = does not format the text with word wrapping and so individual words may break at the end of a line.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_printImage

This function prints the image parameter defined.

Format
kp_CustomAmericaPrinterAPI_printImage(pathToImage, imageJustification, imageScale, imageWidth, callback);
		
Parameters
  • pathToImage = relative path to image stored in Kiosk Pro's documents folder or full URL to remotely stored image, formatted as a string.
  • imageJustification = justification of the image on the page. Possible values are:
    • 0 = left justification.
    • -1 = center justification.
    • -2 = right justification.
  • imageScale = determines how the image is scaled prior to printing. Possible values are:
    • 0 = no scaling.
    • 1 = image is scaled to fit page width.
    • 2 = image is scaled to the width provided in 'imageWidth' parameter below.
  • imageWidth = width of the image in pixels. Pass '-1' to use the maximum available width. Only has an effect if 'imageScale' parameter above is set to '2'.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_printHTMLElement

This function prints the contents of the HTML element defined through parameters. This function allows you to pass both text and images as part of a single print call and can recognize basic .html formatting including header tags (e.g., h1, h2), formatting tags (e.g., bold, italic, underline), margin and alignment tags. See the .html code sample for more details.

Format
kp_CustomAmericaPrinterAPI_printHTMLElement(elementID, wordWrap, callback);
		
Parameters
  • elementID = relative path to image stored in Kiosk Pro's documents folder or full URL to remotely stored image, formatted as a string.
  • wordWrap = justification of the image on the page. Possible values are:
    • 1 = formats the text with word wrapping.
    • 0 = does not and individual words may break at the end of a line.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_printBarCode

This function prints defined text parameter as a 1D barcode, including UPC and EAN barcodes.

Format
kp_CustomAmericaPrinterAPI_printBarCode(text, type, justification, hri, barWidth, height, callback);
		
Parameters
  • text = text to be printed in barcode format, formatted as a string.
  • type = barcode format to be used. Possible values are:
    • -1 = CODEBAR
    • -2 = UPC-A
    • -3 = UPC-E
    • -4 = EAN13
    • -5 = EAN8
    • -6 = CODE39
    • -7 = ITF
    • -8 = CODE93
    • -9 = CODE128
    • -10 = CODE32
    • Each format has its own requirements so if, for example, you attempt to print a 6-digit string as a UPC-A (traditionally a 12-digit string), an error will be returned.
  • justification = justification of the bar code on the page. Possible values are:
    • 0 = left justification.
    • -1 = center justification.
    • -2 = right justification.
  • hri = 'human readable input', the text of the barcode. Possible values are:
    • 1 = HRI above the barcode.
    • 2 = HRI below the barcode.
    • 3 = HRI above and below the barcode.
  • barWidth = horizontal width of the barcode, defined as the width of the narrow bar. Possible values are:
    • 1 = narrow
    • 2 = medium
    • 3 = wide
  • height = height of the barcode in pixels.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_print2DBarCode

This function prints defined text parameter as a 2D barcode, including QR codes and PDF417 barcodes.

Format
kp_CustomAmericaPrinterAPI_print2DBarCode(text, type, justification, width, callback);
		
Parameters
  • text = text to be printed in barcode format, formatted as a string.
  • type = barcode format to be used. Possible values are:
    • -101 = QR CODE
    • -102 = MICRO QR CODE
    • -103 = DATAMATRIX
    • -104 = PDF417
    • -105 = MICRO PDF417
    • -106 = AZTEC
  • justification = justification of the bar code on the page. Possible values are:
    • 0 = left justification.
    • -1 = center justification.
    • -2 = right justification.
  • width = width of the barcode in pixels. Pass '-1' to use the maximum available width.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_feed

This function instructs the printer to feed a specific number of lines.

Format
kp_CustomAmericaPrinterAPI_feed(numberOfLFToSend, callback);
		
Parameters
  • numberOfLFToSend = determines number of lines to feed, formatted as a string.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_cut

This function instructs the printer to cut.

Format
kp_CustomAmericaPrinterAPI_cut(cutType, callback);
		
Parameters
  • cutType = determines cut type. Possible values are:
    • 0 = full cut.
    • 1 = partial cut. If partial cut is specified and printer does not support partial cut, a full cut will be performed.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getPageWidth

This function returns the width of the thermal paper roll in pixels through a callback.

Format
kp_CustomAmericaPrinterAPI_getPageWidth(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(errorDic, pageWidth);
		
Callback return values
  • errorDic = an array containing the domain, code, and description of any error that occurred during the request.
  • pageWidth = the width in pixels of the thermal paper the printer is configured to use.

kp_CustomAmericaPrinterAPI_setFontCharWidth

This function sets the character width of the printer.

Format
kp_CustomAmericaPrinterAPI_setFontCharWidth(value, callback);
		
Parameters
  • value = the character width as a multiplier of the base size of the current font. Possible values are:
    • 0 = indicates that the font is being printed at the default 1x character width.
    • 1 = at 2x.
    • 2 = at 3x.
    • 3 = at 4x.
    • 4 = at 5x.
    • 5 = at 6x.
    • 6 = at 7x.
    • 7 = at 8x.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getFontCharWidth

This function returns the current character width of the printer through a callback.

Format
kp_CustomAmericaPrinterAPI_getFontCharWidth(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(errorDic, charWidth);
		
Callback return values
  • errorDic = an array containing the domain, code, and description of any error that occurred during the request.
  • charWidth = the current character width as a multiplier of the base size of the current font. Possible values are:
    • 0 = indicates that the font is being printed at the default 1x character width.
    • 1 = at 2x.
    • 2 = at 3x.
    • 3 = at 4x.
    • 4 = at 5x.
    • 5 = at 6x.
    • 6 = at 7x.
    • 7 = at 8x.

kp_CustomAmericaPrinterAPI_setFontCharHeight

This function sets the character height of the printer.

Format
kp_CustomAmericaPrinterAPI_setFontCharHeight(value, callback);
		
Parameters
  • value = the character height as a multiplier of the base size of the current font. Possible values are:
    • 0 = indicates that the font is being printed at the default 1x character height.
    • 1 = at 2x.
    • 2 = at 3x.
    • 3 = at 4x.
    • 4 = at 5x.
    • 5 = at 6x.
    • 6 = at 7x.
    • 7 = at 8x.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getFontCharHeight

This function returns the current character height of the printer through a callback.

Format
kp_CustomAmericaPrinterAPI_getFontCharHeight(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(errorDic, charHeight);
		
Callback return values
  • errorDic =- an array containing the domain, code, and description of any error that occurred during the request.
  • charHeight = the current character height as a multiplier of the base size of the current font. Possible values are:
    • 0 = indicates that the font is being printed at the default 1x character height.
    • 1 = at 2x.
    • 2 = at 3x.
    • 3 = at 4x.
    • 4 = at 5x.
    • 5 = at 6x.
    • 6 = at 7x.
    • 7 = at 8x.

kp_CustomAmericaPrinterAPI_setFontEmphasizedProperty

This function sets whether the printer should print in bold font weight.

Format
kp_CustomAmericaPrinterAPI_setFontEmphasizedProperty(value, callback);
		
Parameters
  • value = indicates whether the font should be printed in bold font weight. Possible values are:
    • 0 = indicates that the font is not being printed in bold.
    • 1 = indicates that the font is being printed in bold.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getFontEmphasizedProperty

This function returns whether the printer is currently printing in bold font weight through a callback.

Format
kp_CustomAmericaPrinterAPI_getFontEmphasizedProperty(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(errorDic, isEmphasized);
		
Callback return values
  • errorDic = an array containing the domain, code, and description of any error that occurred during the request.
  • isEmphasized = integer value defining whether text is currently printing in bold weight. Possible values are:
    • 0 = indicates that the font is not being printed in bold.
    • 1 = indicates that the font is being printed in bold.

kp_CustomAmericaPrinterAPI_setFontItalicProperty

This function sets whether the printer should print in italics.

Format
kp_CustomAmericaPrinterAPI_setFontItalicProperty(value, callback);
		
Parameters
  • value = indicates whether the font should be printed in italics. Possible values are:
    • 0 = indicates that the font is not being printed in italics.
    • 1 = indicates that the font is being printed in italics.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getFontItalicProperty

This function that returns whether the printer is currently printing in italics through a callback.

Format
kp_CustomAmericaPrinterAPI_getFontItalicProperty(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(errorDic, isItalic);
		
Callback return values
  • errorDic = an array containing the domain, code, and description of any error that occurred during the request.
  • isItalic = integer indicating whether the font will be printed in italics. Possible values are:
    • 0 = indicates that the font is not being printed in italics.
    • 1 = indicates that the font is being printed in italics.

kp_CustomAmericaPrinterAPI_setFontUnderlineProperty

This function sets whether the printer should print with underline.

Format
kp_CustomAmericaPrinterAPI_setFontUnderlineProperty(value, callback);
		
Parameters
  • value = indicates whether the font should be printed with underline. Possible values are:
    • 0 = indicates that the font is not being printed with underline.
    • 1 = indicates that the font is being printed with underline.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getFontUnderlineProperty

This function that returns whether the printer is currently printing with underline through a callback.

Format
kp_CustomAmericaPrinterAPI_getFontUnderlineProperty(callback);
		
Parameters
  • value = indicates whether the font should be printed with underline. Possible values are:
    • 0 = indicates that the font is not being printed with underline.
    • 1 = indicates that the font is being printed with underline.
  • callback = callback name as a string.
Callback format
callback(errorDic, isUnderline);
		
Callback return values
  • errorDic = an array containing the domain, code, and description of any error that occurred during the request.
  • isUnderline = integer indicating whether the font will be printed with underline. Possible values are:
    • 0 = indicates that the font is not being printed with underline.
    • 1 = indicates that the font is being printed with underline.

kp_CustomAmericaPrinterAPI_setFontJustificationProperty

This function sets how the printer should justify text.

Format
kp_CustomAmericaPrinterAPI_setFontJustificationProperty(value, callback);
		
Parameters
  • value = indicates whether the font should be printed with underline. Possible values are:
    • 0 = left justification.
    • 1 = center justification.
    • 2 = right justification.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getFontJustificationProperty

This function returns how the printer is currently justifying text through a callback.

Format
kp_CustomAmericaPrinterAPI_getFontJustificationProperty(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(errorDic, justification);
		
Callback return values
  • errorDic = an array containing the domain, code, and description of any error that occurred during the request.
  • justification = integer indicating how the font will be justified. Possible values are:
    • 0 = left justification.
    • 1 = center justification.
    • 2 = right justification.

kp_CustomAmericaPrinterAPI_setCharFontType

This function sets which system font should be used for printing. Note that the font used will affect the 'Word Wrap Page Width' in Kiosk Pro settings.

Format
kp_CustomAmericaPrinterAPI_setCharFontType(value, callback);
		
Parameters
  • value = indicates which system font should be used for printing. Possible values are:
    • 0 - font A, default system font.
    • 1 - font B, a narrower, more compact font option.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getCharFontType

This function returns which of the two system fonts is being used for printing through a callback. Note that the font used will affect the 'Word Wrap Page Width' in Kiosk Pro settings.

Format
kp_CustomAmericaPrinterAPI_getCharFontType(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(errorDic, charFontType);
		
Callback return values
  • errorDic = an array containing the domain, code, and description of any error that occurred during the request.
  • charFontType = indicates which system font will be used for printing. Possible values are:
    • 0 = font A, default system font.
    • 1 = font B, a narrower, more compact font option.

kp_CustomAmericaPrinterAPI_setFontInternationalCharSetType

This function sets which international character set type should be used for printing.

Format
kp_CustomAmericaPrinterAPI_setFontInternationalCharSetType(value, callback);
		
Parameters
  • value = indicates which system font should be used for printing. Possible values are:
    • 0 = printer default.
    • 1 = Russian, code page 866.
    • 2 = Turkish, code page 857.
    • 3 = Eastern European, code page 852.
    • 4 = Israeli, code page 862.
    • 5 = Greek, code page 737.
  • callback = callback name as a string.
Callback format
callback(errorDic);
		
Callback return values errorDic = an array containing the domain, code, and description of any error that occurred during the request.

kp_CustomAmericaPrinterAPI_getFontInternationalCharSetType

This function returns the international character set type being used for printing through a callback.

Format
kp_CustomAmericaPrinterAPI_getFontInternationalCharSetType(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(errorDic, charSetType);
		
Callback return values
  • errorDic = an array containing the domain, code, and description of any error that occurred during the request.
  • charSetType = indicates which international character set will be used for printing. Possible values are:
    • 0 = printer default.
    • 1 = Russian, code page 866.
    • 2 = Turkish, code page 857.
    • 3 = Eastern European, code page 852.
    • 4 = Israeli, code page 862.
    • 5 = Greek, code page 737.

kp_CustomAmericaPrinterAPI_printerDidConnect

This callback is triggered when a successful connection is made to the printer selected in Kiosk Pro settings.

Format
kp_CustomAmericaPrinterAPI_printerDidConnect(nameOfPrinter);
		
Return values nameOfPrinter = name of connected printer as string.

Example

This example triggers an alert whenever a Custom America printer is connected. It requires that you access the JavaScript API 'By Import' and include 'kiosk_functions.js' prior to these calls.

function kp_CustomAmericaPrinterAPI_printerDidConnect(nameOfPrinter) {
    alert("Printer: "+nameOfPrinter+" is connected.");
    }

kp_CustomAmericaPrinterAPI_printerDidDisconnect

This callback is triggered when a Custom America printer is disconnected. Can be used to trigger a notification that there is a problem with the printer's connection status.

Format
kp_CustomAmericaPrinterAPI_printerDidDisconnect();
		

Example

This example triggers an alert whenever a connected Custom America printer is disconnected. It requires that you access the JavaScript API 'By Import' and include 'kiosk_functions.js' prior to these calls.

function kp_CustomAmericaPrinterAPI_printerDidDisconnect() {
    alert("Printer is disconnected.");
    }

Still stuck? How can we help? How can we help?