Porting Guide

Changes

Major themes throughout the SDK

  • Abstract class methods have been replaced with listeners. Some of the listeners are optional and may not be needed depending on your use case.
  • Objects are now created via a Builder pattern.
  • The use of DM SDK now requires a license key from Digimarc. An evaluation key can be obtained from the Digimarc Barcode Manager website. This key replaces the resolver username and password used in older SDK versions.
  • The minimum supported Android version is now Android 5.0 (API 21).

CameraHelper library

  • This class has been moved within the SDK package. It is now part of the DMS library rather than being a separate package.
  • The CameraHelperAdaptive and CameraHelperAdvance classes have been removed. All camera access is performed through the CameraHelper class.
  • The abstract methods used by the CameraHelper... classes have been replaced with listeners.
    • You may not need to implement any of the listeners in your app.
    • Listeners fall into the following categories
      • Configuration (CameraConfigurationListener)
        • Performs the function of the onConfigureCamera, onConfigureCamera2 and onConfigureResolution abstract methods in CameraHelper... objects.
        • Unless your app needs to override camera configuration or set any specific camera parameters you do not need to implement this listener.
      • Frame callback (CameraDataListener)
        • Performs the function of the onPreviewFrame abstract method in CameraHelper.
        • If your app is simply giving frames to the VideoCaptureReader you do not need to implement this listener. Instead, construct the CameraHelper object first and then pass the CameraHelper object to the VideoCaptureReader builder.
      • Notify (CameraNotifyListener): Identical to the CameraNotify interface in DM SDK 2.x
      • Error (CameraErrorListener)
        • Identical to the onError abstract method in the CameraHelper... objects.
        • Use this if you want to show your own error message if a camera error occurs. If the listener is not present the error message is shown in a dialog.
  • CameraNotify interface has been renamed to CameraNotifyListener
  • The frames are now accessed via an ImageData object rather than using a byte array for Camera1 image frames.

AudioHelper library

  • Audio capture support has now been integrated into the AudioCaptureReader class. With very few exceptions your application will not need to create an AudioHelper object.
  • This class has been moved within the SDK package. It is now part of the DMS library rather than being a separate package.
  • The abstract methods used by the AudioHelper class have been replaced with a listener.

SdkSession

  • This is an optional class that validates a license key at runtime.
  • It either loads the key from the application's manifest/strings table or the key can be passed in
  • As long as the license key is present in the application's manifest you will not need to directly use the SdkSession object. The reader and resolver objects will automatically load the license key at run-time.

ReaderResult

  • The ReadResult object has been replaced with ReaderResult.
  • When using the VideoCaptureReader your app will now receive a ReaderResult for each frame. The object will contain zero or more decode records for your app to process.
  • The ReaderResult can contain multiple results for each internal decoder.
    • The getPayloads() method returns all payloads decoded in this operation. This may include payloads that were also decoded in the last operation. In most use cases we recommend that you use the getNewPayloads() method instead.
    • The getNewPayloads() method returns a list of the payloads that are new in this frame. See the ReaderResult documentation for more information.
    • If you want to get metadata from the read operation use the getMetadata() method to get a list containing one or more DataDictionary objects pertaining to this payload.

Asynchronous Readers

  • The asynchronous readers (VideoCaptureReader and AudioCaptureReader) use a listener to receive results. The listener methods are comparable to the abstract methods in the DM SDK 2.x asynchronous readers.

Resolver

  • The resolver used (Live vs. Labs vs. a custom URL) is now set internally based on the license key.
  • The Resolver abstract methods have been replaced with a ResolveListener interface. The listener methods are the same as the abstract class methods.

DMSDetectorView

  • A valid license key must be present in the application's manifest. Information on this can be found in the DMSDetectorView documentation.
  • DISListener and DISExtendedListener have been replaced by the DISResultListener interface.
  • The DISNotify interface is now DISNotifyListener for consistency.
  • isTorchAvailable() method renamed to getIsTorchAvailable().
  • setTorch() method is now called setTorchOn().
  • The spinner shown during network operations is now based on the Android system spinner. A custom spinner can still be set but a default one is now supplied.
  • he waveform audio visualizer has been removed.

Payload

  • Representations may now be returned in more relevant types than String. See the representation documentation for information on the data type returned by each representation.
  • The helper classes DataBarInfo, ExpandedFreshInfo, SgtinInfo, and SimpleProductInfo have been removed. All of the data exposed by those classes is available via representations.
  • The GS1 AI data previously exposed by the DataBarInfo class can be retrieved with the getGS1Data() method.

Porting process

First Steps

  1. Replace the old library.
    1. Copy the new DMS.AAR library over the existing DM SDK 2.x library in your project.
    2. Remove the CameraHelper and AudioHelper libraries from your project.
  2. Update the project's minSdkVersion to 21 (if required).
  3. Add your license key by adding the following block of text to the "application" section of your app's manifest. The android:value="" entry can either contain your key string itself or it can contain an Android path to a string resource (i.e. "@string/license_key").
<meta-data android:name="com.digimarc.LicenseKey"
      android:value="license-key-goes-here">

If your application uses DMSDetectorView

  1. Replace your DISListener or DISExtendedListener object with a DISResultListener. The new interface is similar to the DISExtendedListener; however, it uses the new ReaderResult object. See the DetectorViewDemo sample application for an example of how ReaderResults can be handled. After a callback to your DISResultListener's onImageResult() or onAudioResult() your application should return a list of the payloads from the ReaderResult that should be resolved. A simple example that resolves all new decodes from each result is shown below: 
          DISResultListener resultListener = new DISResultListener() {
          @Override
          public List<Payload> onImageResult( @NonNull ReaderResult result ) {
              return result.getNewPayloads();
          }
       
          @Override
          public List<Payload> onAudioResult( @NonNull ReaderResult result ) {
              return result.getNewPayloads();
          }
       
          @Override
          public void onResolved( @NonNull ResolvedContent result ) {
              // Launch resolved content here
          }
      };
  2. If your class uses a DISNotify instance change the object to DISNotifyListener. Other than the name change the interface is the same.
  3. If your app uses the static haveCameraPermission() or haveAudioPermission() methods remove their static imports and re-import them.
  4. If your app uses a spinner, remove both the spinner class (if you have one locally) and calls to DMSDetectorView.setSpinner().
  5. Change any setTorch() calls to setTorchOn().

If your application uses SDK objects (readers, resolver, CameraHelper, etc.)

  1. Camera and Audio support:
    1. Remove all imports from the CameraHelper and AudioHelper packages (com.digimarc.dms.helpers.*).
    2. Layouts containing camera objects like CameraSurfaceView need an updated class path. The camera objects are now found in the com.digimarc.capture.camera package.
    3. Find any CameraHelper-derived objects in the code (CameraHelperAdaptive or CameraHelperAdavance) and use the following guidelines to determine which listener methods you should implement. CameraHelper listeners fall into the following categories:
      1. Configuration (CameraConfigurationListener): Only needed when your app needs to override camera setup.
      2. Frame callback (CameraDataListener): Generally used when your app does something more with the frames than just pass them to the reader.
      3. Error (CameraErrorListener): Only needed if you want to display a custom dialog for errors.
      4. Notify (CameraNotifyListener): Identical to DM SDK 2.x. No changes are needed.
    4. Implement the listener interfaces your app needs. The implementation of the listener methods can generally be copied from your app's CameraHelper... abstract method implementations.
    5. Construct your CameraHelper object: 
                CameraHelper helper = CameraHelper.Builder()
                  .setConfigurationListener( configListener )     // If needed
                  .setDataListener( dataListener )                // If needed
                  .setErrorListener( errorListener )              // If needed
                  .setNotifyListener( notifyListener )            // If needed
                  .build();
  2. Readers
    1. Implement a ResultListener interface. This will be used by both the VideoCaptureReader and AudioCaptureReader objects to report results.
      1. Copy the code from your reader implementations of the onRead() and onError() methods into the ResultListener methods.
      2. ReaderResults can be processed by stepping through the payloads in getNewPayloads() and operating on them. Additional metadata, as well as the source image frame, are also available from the ReaderResult if needed.
    2. Construct a VideoCaptureReader object: 
                VideoCaptureReader cameraReader = VideoCaptureReader.Builder()
                .setSymbologies( imageSymbologies )
                .setResultListener( resultListener )
                .setReaderOptions( readerOptions )                          // If you are any setting reader options
                .setCameraHelper( cameraHelper )
                .build();
    3. Construct an AudioCaptureReader object (if needed): 
                AudioCaptureReader audioReader= AudioCaptureReader.Builder()
                  .setSymbologies( audioSymbologies )
                  .setResultListener( resultListener )
                  .setReaderOptions( readerOptions )                      // If you are any setting reader options
                  .build();
      1. Replace all calls to the AudioHelper start(), stop() and release() methods with calls to the comparable methods on your AudioCaptureReader object.
      2. Remove all use of the AudioHelper class.
  3. Resolver
    1. Create a ResolveListener interface object. You can copy the implementation from the DM SDK 2.x Resolver abstract methods into the listener methods.
    2. Construct a Resolver object: 
                ResolveListener resolveListener = Resolver.Builder()
                .setResultListener( resolveListener )
                .build();
Back to Documentation