Easy Tool SDK (App to App)


This document will help you integrate and use the Easy Tool SDK in your Android applications.

Introduction

The Easy Tool SDK is a secure Android SDK designed for seamless communication with Easytool app. It provides a simple API for printing text, raw bytes, images, controlling cash drawers, and managing sessions with type-safe callbacks.

Installation

Gradle

Add the following to your app's build.gradle file:

dependencies {
    implementation 'sa.easypay:easypay-toolsdk:1.6.0'
}

Maven

<dependency>
    <groupId>sa.easypay</groupId>
    <artifactId>easypay-toolsdk</artifactId>
    <version>1.6.0</version>
</dependency>

Permissions

Ensure the following permissions are added to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Getting Started

Initialize the SDK

To start using the SDK, initialize it with your subscription number:

val initializeListener = object : InitializeListener {
    override fun onInitializeSuccess() {
        // SDK is ready to use
    }
    
    override fun onInitializeError(error: String) {
        // Handle initialization error
    }
}

EasyTool.initialize(this, "your_subscription_number", initializeListener)

Printer Selection

Prompt the user to select a printer:

val printerSelectListener = object : PrinterSelectListener {
    override fun onPrinterSelected(printerId: String, printerName: String?) {
        // Save printerId for printing
    }
    override fun onPrinterSelectionCancelled() {
        // Handle cancellation
    }
    override fun onPrinterSelectionError(error: String) {
        // Handle error
    }
}

EasyTool.selectPrinter(printerSelectListener)

Core Features

  • Print Text

EasyTool.printText(printerId, "Hello World!", printListener)
  • Print Bytes

val escPosBase64 = "G0EAIC" // Example ESC/POS command
EasyTool.printBytes(printerId, escPosBase64, printListener)
  • Print Image

val base64Image = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
EasyTool.printImage(printerId, base64Image, printListener)
  • Open Cash Drawer

EasyTool.openCashDrawer(printerId, printListener)

PrintListener Example

val printListener = object : PrintListener {
    override fun onPrintSuccess(result: String?) {
        // Print successful
    }
    override fun onPrintError(error: String) {
        // Print failed
    }
}

Session Management

Sign out and clear all session data:

val signOutListener = object : SignOutListener {
    override fun onSignOutSuccess() {
        // Signed out
    }
    override fun onSignOutError(error: String) {
        // Handle error
    }
}

EasyTool.signOut(signOutListener)

Advanced Usage

Custom Error Handling

override fun onInitializeError(error: String) {
    when {
        error.contains("network", ignoreCase = true) -> { /* Handle network error */ }
        error.contains("Subscription number", ignoreCase = true) -> { /* Handle subscription error */ }
        else -> { /* Handle other errors */ }
    }
}

Base64 Data Preparation

val escPosCommands = byteArrayOf(0x1B, 0x40)
val base64Data = Base64.encodeToString(escPosCommands, Base64.DEFAULT)
EasyTool.printBytes(printerId, base64Data, printListener)

Error Handling

The SDK provides comprehensive error handling with automatic recovery. Initialization failures trigger complete state cleanup, and sign out errors still perform local cleanup.

Version History

  • 1.5.0: Added robust Easy Tool app installation check and user prompt

  • 1.4.0: Enhanced security, improved error handling

  • 1.3.0: Added sign out functionality, enhanced error recovery, version centralization

  • 1.2.0: Enhanced security, improved error handling

  • 1.1.0: Added Base64 image support, optimized flow

  • 1.0.0: Initial release

Last updated