# 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:
```gradle
dependencies {
implementation 'sa.easypay:easypay-toolsdk:1.6.0'
}
```
#### Maven
```xml
sa.easypay
easypay-toolsdk
1.6.0
```
#### Permissions
Ensure the following permissions are added to your `AndroidManifest.xml`:
```xml
```
### Getting Started
#### Initialize the SDK
To start using the SDK, initialize it with your subscription number:
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
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)
```
{% endtab %}
{% tab title="Java" %}
```java
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);
```
{% endtab %}
{% endtabs %}
### Printer Selection
Prompt the user to select a printer:
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
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)
```
{% endtab %}
{% tab title="Java" %}
```java
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);
```
{% endtab %}
{% endtabs %}
### Core Features
#### Print Operations
* **Print Text**
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
EasyTool.printText(printerId, "Hello World!", printListener)
```
{% endtab %}
{% tab title="Java" %}
```java
EasyTool.printText(printerId, "Hello World!", printListener);
```
{% endtab %}
{% endtabs %}
* **Print Bytes**
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
val escPosBase64 = "G0EAIC" // Example ESC/POS command
EasyTool.printBytes(printerId, escPosBase64, printListener)
```
{% endtab %}
{% tab title="Java" %}
```java
String escPosBase64 = "G0EAIC"; // Example ESC/POS command
EasyTool.printBytes(printerId, escPosBase64, printListener);
```
{% endtab %}
{% endtabs %}
* **Print Image**
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
val base64Image = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
EasyTool.printImage(printerId, base64Image, printListener)
```
{% endtab %}
{% tab title="Java" %}
```java
String base64Image = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
EasyTool.printImage(printerId, base64Image, printListener);
```
{% endtab %}
{% endtabs %}
* **Open Cash Drawer**
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
EasyTool.openCashDrawer(printerId, printListener)
```
{% endtab %}
{% tab title="Java" %}
```java
EasyTool.openCashDrawer(printerId, printListener);
```
{% endtab %}
{% endtabs %}
#### PrintListener Example
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
val printListener = object : PrintListener {
override fun onPrintSuccess(result: String?) {
// Print successful
}
override fun onPrintError(error: String) {
// Print failed
}
}
```
{% endtab %}
{% tab title="Java" %}
```java
PrintListener printListener = new PrintListener() {
@Override
public void onPrintSuccess(String result) {
// Print successful
}
@Override
public void onPrintError(String error) {
// Print failed
}
};
```
{% endtab %}
{% endtabs %}
### Session Management
Sign out and clear all session data:
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
val signOutListener = object : SignOutListener {
override fun onSignOutSuccess() {
// Signed out
}
override fun onSignOutError(error: String) {
// Handle error
}
}
EasyTool.signOut(signOutListener)
```
{% endtab %}
{% tab title="Java" %}
```java
SignOutListener signOutListener = new SignOutListener() {
@Override
public void onSignOutSuccess() {
// Signed out
}
@Override
public void onSignOutError(String error) {
// Handle error
}
};
EasyTool.signOut(signOutListener);
```
{% endtab %}
{% endtabs %}
### Advanced Usage
#### Custom Error Handling
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
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 */ }
}
}
```
{% endtab %}
{% tab title="Java" %}
```java
@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
}
}
```
{% endtab %}
{% endtabs %}
#### Base64 Data Preparation
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
val escPosCommands = byteArrayOf(0x1B, 0x40)
val base64Data = Base64.encodeToString(escPosCommands, Base64.DEFAULT)
EasyTool.printBytes(printerId, base64Data, printListener)
```
{% endtab %}
{% tab title="Java" %}
```java
byte[] escPosCommands = new byte[] { 0x1B, 0x40 };
String base64Data = Base64.encodeToString(escPosCommands, Base64.DEFAULT);
EasyTool.printBytes(printerId, base64Data, printListener);
```
{% endtab %}
{% endtabs %}
### 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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.easypay.sa/easypay/easy-tool-sdk-app-to-app.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.