Getting Started under Android

This guide is split in three parts:

The first part shows how you can integrate the SDK in your own app in 5 easy steps.
The second part describes how to build the demo project that comes with the SDK.
The last part contains some troubleshooting tips.

1. Integrating the SDK in your own app

1.1 Get your SDK

Create your personal account at http://account.scandit.com, get a free Development License and download the SDK (scanditsdk-devel-android_x.x.x.zip).

1.2 Add the SDK to your project

The ZIP file you downloaded contains a folder named libs. Copy this folder into your Eclipse project at the root level.
Add the scanditsdk-barcodepicker-android-x.x.x.jar, which is contained in the libs folder, to your build path (right click → “Build Path” → “Add to Build Path”).
Copy the raw folder located inside the res folder to the res folder of your Eclipse project.
The Scandit SDK requires Android 2.1. If the minimum SDK level in your manifest is below 7, change it to 7.

1.3 Add license key file to your project

Download your personal license key file from http://account.scandit.com (via the “Download” menu) and place it in the res/raw folder. Your license key file is named one of the following:

development_license_key.txt
production_license_key_free_apps.txt
production_license_key_paid_apps.txt

1.4 Prepare class to receive scanning events

To receive events from the Scandit SDK you have to implement the ScanditSDKListener interface. To do this, you need to perform the following steps:

Specify that your class implements the ScanditSDKListener interface. If your class is an activity called DemoActivity, this looks something like this:
```
public class DemoActivity extends Activity
                          implements ScanditSDKListener {
}
```
Import the necessary interface by pressing Ctrl-Shift-O.

Add the following callback methods to the class (as defined by the interface):

@Override
public void didScanBarcode(String barcode, String symbology) {}

@Override
public void didManualSearch(String entry) {}

@Override
public void didCancel() {}

Process the barcode and symbology values received by the didScanBarcode method. The barcode argument contains the data read from the barcode / 2d code, while the the symbology argument contains one of the following strings: "EAN8", "EAN13", "UPC12", "UPCE", "EAN128", "CODE39", "ITF", "QR", "DATAMATRIX"

1.5 Add code to start the scanning process

Scandit SDK for Android offers two different scanners (“pickers”): A standard picker, which is available on Android 2.2 and higher, as well as a legacy picker, which was specifically developed for Android 2.1, where it allows for scanning in portait mode (Android 2.1 does not provide a video feed in portrait mode natively). We recommend the use of the standard picker for all devices that run Android 2.2+ and the legacy picker for Android 2.1 devices. The Scandit SDK provides a dedicated method that allows you to determine which picker to use.

Check whether the device supports the standard picker (if you are only targeting devices with Android 2.2 and higher, you can leave this out):
```
if (ScanditSDKBarcodePicker.canRunPortraitPicker()) {
  // the standard picker can be used
} else {
  // the legacy picker must be used
}
```
Instantiate the appropriate picker. Do not forget to replace ##AppKey## with your personal app key in the following code snippet. You can look up the app key by signing in to your account at http://account.scandit.com (see “App key” link). Note that the app key is not the same as the string listed in your license key file.

For the standard picker:
```
ScanditSDK picker = new ScanditSDKBarcodePicker(
    this, R.raw.class, "##AppKey##");
```
For the legacy picker:
```
ScanditSDK picker = new LegacyPortraitScanditSDKBarcodePicker(
    this, R.raw.class, "##AppKey##");
```

The demo application that is provided with the Scandit SDK provides a full working example.

Import the necessary interface by pressing Ctrl-Shift-O.
Specify the object that will receive the callback events. In this example, we assume that the receiver is the same class that also instantiated the picker:
```
Picker.getOverlayView().addListener(this);
```
Start the scanning process. Starting and stopping should normally happen in the onPause() and onResume() methods of the same activity that contains the picker. It does not matter whether the picker is the root view of the activity or just a subview in the hierarchy. The camera resource needs to be freed before the activity ends or goes into the background, so stopping the picker in onPause() is a necessity. On the other hand, whether you start it in onResume() is not as important. Your code should look something like this, assuming that mPicker references the picker you created earlier:
```
private ScanditSDK mPicker;

@Override
protected void onResume() {
    mPicker.startScanning();
    super.onResume();
}

@Override
protected void onPause() {
    mPicker.stopScanning();
    super.onPause();
}
```
Show the scanner to the user. The easiest way to do so is by setting it as the content view of your activity:
```
setContentView(picker);
```

2. Building the demo project

The ZIP file you downloaded (scanditsdk-devel-android_x.x.x.zip) is itself a complete Eclipse project. To build this demo project, perform the following steps:

In Eclipse, select “File” → “New” → “Android project”. Choose “Create project from existing source” and specify the path to the extracted ZIP file. Press “Finish”.
Download your personal license key file from http://account.scandit.com (via the “Download” menu) and place it in the res/raw folder. Your license key file is named one of the following:
- development_license_key.txt
- production_license_key_free_apps.txt
- production_license_key_paid_apps.txt
Refresh your Eclipse project after adding the license file.
In the ScanditSDKDemo.java and ScanditSDKSampleBarcodeActivity.java files, locate the sScanditSdkAppKey constant and paste your personal app key between the quotation marks. Sign in to your account at http://account.scandit.com to look up your app key (see “App key” link). Note that the app key is not the same as the string listed in your license key file.
```
private static final String sScanditSdkAppKey = "";
```
Run the demo project as an Android application.

3. Customizing the SDK

The Scandit SDK offers a number of customization features. Among others, the Scandit SDK offers options to:

Customize the scan view within your app
Disable barcode symbologies your app will not support
Add additional locales
Change the scan beep

For a detailed list of available API methods, see the Javadoc of the ScanditSDKBarcodePicker, LegacyPortraitScanditSDKBarcodePicker and ScanditSDKOverlay classes.

4. Problems, crashes?

Please check the LogCat output in Eclipse. The Scandit SDK writes log messages to LogCat that can help you identify problems.

If you have problems with the demo project: Did you change the project settings as described above? Did you include the license file and the app key as described above?

If your app crashes and you are using a development SDK: Does your phone have access to the internet? Your app will terminate otherwise. Note that production versions do not have this requirement and work without network access.

Getting Started with Scandit SDK for Android