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)

InitializeListener initializeListener = new InitializeListener() {
    @Override
    public void onInitializeSuccess() {
        // SDK is ready to use
    }
    @Override
    public void onInitializeError(String error) {
        // 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)

PrinterSelectListener printerSelectListener = new PrinterSelectListener() {
    @Override
    public void onPrinterSelected(String printerId, String printerName) {
        // Save printerId for printing
    }
    @Override
    public void onPrinterSelectionCancelled() {
        // Handle cancellation
    }
    @Override
    public void onPrinterSelectionError(String error) {
        // Handle error
    }
};

EasyTool.selectPrinter(printerSelectListener);

Core Features

Print Operations

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
    }
}

PrintListener printListener = new PrintListener() {
    @Override
    public void onPrintSuccess(String result) {
        // Print successful
    }
    @Override
    public void onPrintError(String error) {
        // 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)

SignOutListener signOutListener = new SignOutListener() {
    @Override
    public void onSignOutSuccess() {
        // Signed out
    }
    @Override
    public void onSignOutError(String error) {
        // 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 */ }
    }
}

@Override
public void onInitializeError(String error) {
    if (error.toLowerCase().contains("network")) {
        // Handle network error
    } else if (error.toLowerCase().contains("subscription number")) {
        // 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

PreviousPrint Receipt In-App Integration NextModels

Last updated 5 months ago