Embedded Connection SDK

📄 Embedded Connection SDK developer documentation 📄

About The Project

The Embedded Connection SDK offers a solution for use the peripheral hardware of POS Clip devices in your project.

Getting started

To facilitate the integration testing process, follow the steps below to request a test POS device from our team:

Reach Out to Us

Email: Contact our integration support team at [email protected]

Provide Details

Your Information: Include your name, contact information, company name, and industry.
Integration Requirements: Provide a brief overview of your integration requirements and goals.
Timeline: Indicate your preferred timeline for testing and integration.

Request a Test POS Device

Mention in your email or message that you would like to request a test POS device for integration testing purposes. Our team will review your request and get in touch to discuss further details.

Arrange Shipment

Once your request is approved, we will arrange for the shipment of a test POS device to your designated address. Tracking information will be provided so you can monitor the delivery status.

Installing dependency

Add JitPack Repository: Open your settings file and add the JitPack repository to your Maven repositories list.
Add Dependency: Open your build file and add the SDK dependency.

 dependencyResolutionManagement {    
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)    
    repositories {    
	    mavenCentral()    
	    maven {
	        url = uri("https://jitpack.io")
	    }
	}
}

Example for adding the dependency into build.gradle.kts kotlin file.

dependencies {
	implementation("TBD")
}

Supported Devices

Embedded Connection SDK is supported on the following Clip Devices:

Clip Total
Clip Total2

Clip Printer

Presentation

Embedded Connection SDK allows you to integrate the POS Clip printer in your app in a friendly way.

If your app need print tickets, orders, summarizes or anything that you want, this solution fits for you.

Structure

To make a successful implementation in your app we are going to introduce some concepts about how you can use the SDK.

ClipPrinter

Is the responsible for printing content to a Clip POS, is your first contact with the printer. This object uses the builder pattern for instantiation.

PrintableContent

When you have an idea about what is that you want to print you will use this object. With the PrintableContent you will structure the format of your ticket using different Printable components available for you in this SDK

Printable

Is the base unit to build different structures of your ticket. You can mix all the Printable provided and create tickets according to your necessities.

The printable components available are the following:

Printable name	Description
`Section`	Represents a printable text section with formatting options and optional line breaks
`Heading`	Represents a printable heading with text, alignment, font size, and optional top line breaks
`Divider`	Represents a printable divider, which can be a simple line or a line with a centered title
`LineBreak`	Represents a printable line break, adding vertical space to the printed output
`ListPrintable`	Represents a printable list of `ItemList`, where each item can be a single line of text or a two-column row
`ItemList`	Represents a printable item list that can be either a single line of text or a two-column row
`PrintableImage`	Represents a printable image

Examples

Basic Example

The printer implementation can be summarized in 3 steps:

Create ClipPrinter object.
Customize the PrintableContent.
Call ClipPrinter.print() function.

fun print(context: Context) {

// STEP 1.
// Create CliPrinter using builder pattern.
    clipPrinter = ClipPrinter.Builder().setContext(context).build()

// STEP 2.
// Create image variables for example purposes:
// One image for header and last image for print in ticket body.
    val myHeaderImage =
        context.getDrawable(R.drawable.ic_food_restaurant_foreground)?.toBitmap()
    val myPrintableImage = context.getDrawable(R.drawable.ic_launcher_foreground)?.toBitmap()

    /* Create the PrintableContent using builder pattern.
     The printableContent structure is divided in three parts: Header (Optional), Body and Footer(Optional).
     In this example the body has two printable components: Section and Divider.
     */
    val myPrintableContent =
        PrintableContent.Builder()
            .setHeader("CLIP PRINTER SDK", myHeaderImage)
            .addPrintable(
                Section(
                    text = "Lorem ipsum dolor sit amet, consectetur adipiscing",
                    alignment = TextAlignment.CENTER,
                )
            ).addPrintable(Divider())
            .addPrintable(PrintableImage(myPrintableImage!!))
            .setFooter(
                listOf(
                    "Aplican términos y condiciones",
                    "Conserve el ticket para futuras aclaraciones",
                    "clip.mx",
                )
            )
            .build()

// STEP 3.
// The print function receive two parameters: The printableContent and a ClipPrinterListener.
    clipPrinter.print(
        myPrintableContent,
        object : ClipPrinterListener {
            override fun onSuccessfulPrint() {
                //TODO: Add printing success action
            }

            override fun onFailedPrint(clipPrinterError: ClipPrinterError) {
                //TODO: Add printing error action
            }
        },
    )

}

Example for printing Lists

You can implement lists in your ticket with different parameters of customization. This section will show you an overview about how create items for you list.

We can create items for simulate a two-columns row:

val itemList =
    ListPrintable(
        listOf(
            ItemList(rowContent = RowContent("U. Producto", "Precio", isListHeader = true)),
            ItemList(rowContent = RowContent("1 Milk", "$34")),
            ItemList(rowContent = RowContent("1 Orange", "$34")),
            ItemList("Netus luctus massa habitasse"),
            ItemList("Interdum eleifend iaculis;"),
            ItemList("Rhoncus donec quam torquent"),
            ItemList(rowContent = RowContent("1 Coffee", "$34")),
        ),
    )

In this example we pass to ListPrintable object an ItemList list. For this example is created an ItemList in two different ways:

Creating a single ItemList: Only will show the text passed to constructor.
Passing a RowContent: With the purpose to simulate two columns in the ticket (like a table).

As you can see, its possible mix in the same ListPrintable different instances of an ItemList.

Also, you can add a divider that will apply for all elements in your ListPrintable:

val itemListWithDivider =
    ListPrintable(
        listOf(
            ItemList(rowContent = RowContent("Left", "Right", isListHeader = true)),
            ItemList(rowContent = RowContent("1 Product", "$34")),
            ItemList(rowContent = RowContent("1 Product", "$34")),
            ItemList("Netus luctus massa habitasse"),
            ItemList("Interdum eleifend iaculis;"),
            ItemList("Rhoncus donec quam torquent"),
        ),
        divider = Divider()
    )

With our itemList and itemListWithDivider variables we can finish the printing process:

val myPrintableContentList = PrintableContent.Builder()
    .addPrintable(Heading(text = "My first list"))
    .addPrintable(itemList)
    .addPrintable(Heading(text = "My second list with dividers"))
    .addPrintable(itemListWithDivider).build()

clipPrinter.print(myPrintableContentList, object : ClipPrinterListener {
    override fun onSuccessfulPrint() {
        TODO("Not yet implemented")
    }

    override fun onFailedPrint(clipPrinterError: ClipPrinterError) {
        TODO("Not yet implemented")
    }
})

Example using all components

private val itemList =
    ListPrintable(
        listOf(
            ItemList(rowContent = RowContent("U. Producto", "Precio", isListHeader = true)),
            ItemList(rowContent = RowContent("1 Milk", "$34")),
            ItemList(rowContent = RowContent("1 Orange", "$34")),
            ItemList("Netus luctus massa habitasse"),
            ItemList("Interdum eleifend iaculis;"),
            ItemList("Rhoncus donec quam torquent"),
            ItemList(rowContent = RowContent("1 Coffee", "$34")),
        ),
    )

private val itemListWithDivider =
    ListPrintable(
        listOf(
            ItemList(rowContent = RowContent("Left", "Right", isListHeader = true)),
            ItemList(rowContent = RowContent("1 Product", "$34")),
            ItemList(rowContent = RowContent("1 Product", "$34")),
            ItemList("Netus luctus massa habitasse"),
            ItemList("Interdum eleifend iaculis;"),
            ItemList("Rhoncus donec quam torquent"),
        ),
        divider = Divider(),
    )

private val footerList =
    listOf(
        "Aplican términos y condiciones",
        "Conserve el ticket para futuras aclaraciones",
        "clip.mx",
    )

private fun printableContent(
    bitmap: Bitmap?,
    secondImage: Bitmap?,
): PrintableContent =
    PrintableContent
        .Builder()
        .setHeader("CLIP PRINTER SDK", bitmap)
        .addPrintable(
            Section(
                text = "Total:",
                alignment = TextAlignment.CENTER,
            ),
        ).addPrintable(
            Heading(
                "$25.00",
                alignment = TextAlignment.CENTER,
                fontSize = FontSize.SUPER_LARGE,
            ),
        ).addPrintable(
            Heading(
                text = "VENTA",
                alignment = TextAlignment.CENTER,
                fontSize = FontSize.MEDIUM,
            ),
        ).addPrintable(
            Section(
                text = "Lorem ipsum dolor sit amet, consectetur adipiscing",
                alignment = TextAlignment.CENTER,
            ),
        ).addPrintable(Divider())
        .addPrintable(
            Heading(
                text = "TRANSACCIÓN APROBADA",
                alignment = TextAlignment.CENTER,
                lineBreaksTop = 1,
            ),
        )
        .addPrintable(Divider('#'))
        .addPrintable(PrintableImage(secondImage!!))
        .addPrintable(Divider(title = "COPY OF RECEIPT"))
        .addPrintable(itemListWithDivider)
        .addPrintable(LineBreak(4))
        .addPrintable(itemList)
        .setFooter(footerList)
        .build()

Anatomy and properties

`ClipPrinter.Builder`

fun setContext(context: Context): Builder

Use the context required for building the printer

Parameters
`context`	The Android context

fun build(): ClipPrinter

Sets up the reader device and creates a ClipPrinter using the provided context.

Throws ClipPrinterNotBuiltException if no Clip reader with a printer is detected or if the printer cannot be built.
Throws ContextNotInitializedException if the provided context is null.

`ClipPrinter`

fun print(printableContent: PrintableContent, clipPrinterListener: ClipPrinterListener)

Prints the provided PrintableContent to the printer

Parameters
`printableContent`	The content to be printed
`clipPrinterListener`	A listener to receive the print result. This listener will be notified when the print operation is successful or if it fails.

`PrintableContent.Builder`

fun setHeader(title: String, image: Bitmap): Builder

Sets the header for the printable content. Set a header is optional

Parameters
`title`	The title of the header.
`image`	An optional bitmap image to include in the header.

fun addPrintable(printable: Printable): Builder

Adds a printable item to the list.

Parameters
`printable`	The printable item to add.

fun setFooter(texts: List<String>): Builder

Sets the footer for the printable content.

Parameters
`texts`	A list of strings to include in the footer.

fun build(): PrintableContent

Creates a PrintableContent instance using the configured values.

Printable

The following objects are components where you will be able to build and customize the structure of your tickets.

Section

class Section(text: String, lineBreaks: Int, alignment: TextAlignment, fontSize: FontSize, boldEnabled: Boolean)

Represents a printable text section with formatting options and optional line breaks.

Attributes
`texts`	The text content of the section.
`lineBreaks`	The number of line breaks to add after the section. Default is 0.
`alignment`	The text alignment for the section. Default is `TextAlignment.LEFT`
`fontSize`	The font size for the section. Default is `FontSize.MEDIUM`.
`boldEnabled`	Indicates whether the text should be printed in bold. Default is `false`.

Heading

class Heading(text: String, alignment: TextAlignment, fontSize: FontSize, lineBreaksTop: Int)

Represents a printable heading with text, alignment, font size, and optional top line breaks.

Attributes
`text`	The text content of the heading.
`alignment`	The text alignment for the heading. Default is `TextAlignment.LEFT`.
`fontSize`	The font size for the heading. Default is `FontSize.LARGE`.
`lineBreaksTop`	The number of line breaks to add before the heading. Default is 0.

Divider

class Divider(divider: Char, title: String)

Represents a printable divider, which can be a simple line or a line with a centered title.

Attributes
`divider`	The character used to create the divider line. Default is `-`.
`title`	An optional title to be centered within the divider. Default is null.

Line break

class LineBreak(spaces: Int)

Represents a printable line break, adding vertical space to the printed output.

Attributes
`spaces`	The number of line breaks to add. Default is 1.

List Printable

class ListPrintable(items: List<ItemList>, bulletSpan: Char, divider: Divider)

Represents a printable list of items, where each item can be a single line of text or a two-column row. Items can be optionally prefixed with a bullet point and separated by a divider.

Attributes
`items`	The list of `ItemList` objects to be printed.
`bulletSpan`	The character used for the bullet point. Default is `*`.
`divider`	An optional `Divider` to be printed after each item. Default is `null`.

Item List

class ItemList(text: String, boldEnabled: Boolean, rowContent: RowContent)

Represents a printable item list that can be either a single line of text or a two-column row.

Attributes
`text`	The text to be printed as a single line. Default is an empty string.
`boldEnabled`	Indicates whether the text should be printed in bold. Default is `false`.
`rowContent`	The content of the two-column row. Default is `null`.

Throw ItemListContentException if both text and rowContent are provided.

class RowContent(textColumn1: String, textColumn2: String, isListHeader: Boolean)

Represents the content of a two-column row for printing.

Attributes
`textColumn1`	The text content for the first column.
`textColumn2`	The text content for the second column.
`isListHeader`	Indicates whether this row is a header for a list. Default is `false`.

Printable image

class PrintableImage(bitmapResource: Bitmap)

Represents a printable image provided by your project resources.

Attributes
`bitmapResource`	The bitmap image to be printed.

`FontSize`

For the vast majority of Printable components you can customize the font size. You can use the following fontSize:

EXTRA_SMALL
SMALL
MEDIUM
LARGE
EXTRA_LARGE
SUPER_LARGE

`TextAlignment`

Same as the FontSize, you can customize the text alignment of your Printable components. You can use the following types:

LEFT
CENTER
RIGHT

`ClipPrinterListener`

interface ClipPrinterListener {

    fun onSuccessfulPrint()

    fun onFailedPrint(clipPrinterError: ClipPrinterError)
}

A listener interface for receiving events related to clip printing. Implement this interface to be notified of the success or failure of a clip printing operation.

Method
`onSuccessfulPrint()`	Called when a clip is successfully printed.
`onFailedPrint(clipPrinterError: ClipPrinterError)`	Called when a clip printing operation fails.

`ClipPrinterError`

If the ClipPrinterListener calls onFailedPrint() you will receive a ClipPrinterError. These error are described in the following table:

ClipPrinterError	Description
`PRINT_FAIL`	General printing failure.
`ADD_STRING_FAIL`	Failed to add a string to the print buffer.
`ADD_IMAGE_FAIL`	Failed to add an image to the print buffer.
`PRINTER_BUSY`	The printer is currently busy with another operation.
`PAPER_LACK`	The printer is out of paper.
`WRONG_PACKAGE`	Incorrect or incompatible printer driver or package.
`PRINTER_FAULT`	A general printer fault has occurred.
`PRINTER_TOO_HOT`	The printer has overheated.
`PRINTER_UNFINISHED`	A previous printing operation was not completed.
`NO_PRINTER_FOUND`	No compatible printer was found.
`UNKNOWN`	An unknown error occurred.

Stay updated

We strongly recommend staying informed about new versions of our SDK and updating your library frequently. While we strive to provide clean updates with no breaking changes, keeping your SDK version up-to-date ensures you have access to the latest features and improvements.

And that's it! With these steps, you can have fun with the POS Clip in your application.

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github		.github
app		app
embedded-connection-sdk		embedded-connection-sdk
gradle		gradle
.gitignore		.gitignore
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

ClipMX/mobile.android.blaze.embedded-connection.sdk

Folders and files

Latest commit

History

Repository files navigation

Embedded Connection SDK

About The Project

Table of contents

Getting started

Installing dependency

Supported Devices

Clip Printer

Presentation

Structure

ClipPrinter

PrintableContent

Printable

Examples

Basic Example

Example for printing Lists

Example using all components

Anatomy and properties

ClipPrinter.Builder

ClipPrinter

PrintableContent.Builder

Printable

Section

Heading

Divider

Line break

List Printable

Item List

Printable image

FontSize

TextAlignment

ClipPrinterListener

ClipPrinterError

Stay updated

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Uh oh!

Contributors 2

Uh oh!

Languages

`ClipPrinter.Builder`

`ClipPrinter`

`PrintableContent.Builder`

`FontSize`

`TextAlignment`

`ClipPrinterListener`

`ClipPrinterError`

Packages