SDK Functionality

The Pensa library is a lightweight SDK that simplifies interactions through straightforward method calls. This SDK enables you to:

• Locate stores: Easily find the stores you're looking for.

• Access stores directly: Use global store IDs to access a specific store and initiate a scan directly.

• View store history: Conveniently access a list of previously visited stores.

• Monitor scan uploads: Track the upload status of your scans.

Searching stores

To initiate a store search using the Pensa SDK, integrate the following code snippet into your Activity or Fragment:

PensaSdk.showStoreSearchView(
    context = this,
    onError = { error ->
        println("Error displaying search store: $error")
    }
)

This will present a search interface where you can input keywords (e.g., store name, location) to find the desired store. Upon selecting a store from the search results, the SDK will automatically redirect you to that store's details, allowing you to begin a scan.

The entered keyword must be at least 3 characters long.

Accessing Stores Directly with Global Store IDs

The Pensa SDK lets you directly access a store and initiate a scan using its global store ID. To do this, use the showStoreChecklist method:

PensaSdk.showStoreChecklist(
    context = this,
    globalStoreId = "example-id",
    guid = null,
    sectionKey = null,
    onError = { error ->
        println("Error displaying store: $error")
    }
)

Sending Custom Parameters with Scans

In addition to using global store IDs, the Pensa SDK allows you to send custom parameters along with your scans. This can be useful for including company-specific information or metadata.

To send custom parameters, use the sectionKey and guid parameters in the showStoreChecklist method.

It's important to note that both sectionKey and guid must be used together. If either parameter is missing, the SDK will only consider the globalStoreId parameter.

PensaSdk.showStoreChecklist(
    context = this,
    globalStoreId = "example-id",
    sectionKey = "example-section",
    guid = "example-guid",
    onError = { error ->
        println("Error displaying store: $error")
    }
)

Recently Visited Stores

The Pensa SDK maintains a cache of recently visited stores for easy access and reuse. This allows you to quickly return to a previously scanned store without searching for it again.

Adding Stores to the Cache

A store is automatically added to the "Recently Visited Stores" cache when you:

• Use the showStoreChecklist() method to access a store.

• Select a store from the search results after using showStoreSearchView().

Accessing Recently Visited Stores

To display the "Recently Visited Stores" screen, use the following code:

PensaSdk.showStoresScreen(
    context = this,
    onError = { error ->
        println("Error displaying recently visited stores: $error")
    }
)

This will present a screen listing the recently visited stores. You can select a store from this screen to access its details and initiate a new scan.

Monitoring Scan Uploads

The Pensa SDK provides convenient methods to monitor the progress of your scan uploads. There are two separate methods depending on the type of scan:

Shelf Scans

To monitor shelf scan uploads, use the following method:

PensaSdk.showShelfScans(
    context = this,
    onError = { error ->
        println("Error displaying shelf uploads: $error")
    }
)

Product Scans

PensaSdk.showProductScans(
    context = this,
    onError = { error ->
        println("Error displaying product uploads: $error")
    }
)

Both methods present a screen that displays the status of each scan upload. You can use these screens to:

• Track upload progress: Observe the progress of ongoing uploads.

• View completed uploads: See a history of successfully uploaded scans.

• Cancel uploads: Stop the upload of any scan that is in progress.

These features give you complete control over your scan uploads and ensure you're always informed about their status.

Stocking Screen

The Pensa SDK allows you to access the stocking screen. This screen is used to review and manage stock actions related to the selected store.

To display the stocking screen, use the following method:

PensaSdk.showStockingScreen(
    context = this,
    onError = { error ->
        println("Error displaying stocking screen: $error")
    }
)

Scan Area

To directly open a scan area, you must provide a scanId and either a storeId or a globalStoreId.:

PensaSdk.showScanArea(
    context = this,
    globalStoreId = globalStoreId,
    storeId = storeId,
    scanId = scanId,
    onError = { error ->
        println("Error displaying scan area: $error")
    }
)

This method allows you to navigate directly to a scan area without going through the store selection flow.

Scan & Image APIs (Android)

This section documents the programmatic APIs exposed by the Pensa Android SDK that allow you to:

• Fetch processing statuses for one or more scans.

• Retrieve on-demand analytical reports for a given scan.

• Fetch a product image as a Base64‑encoded string.

All examples below assume that:

• PensaSdk.initPensa(...) has been called successfully, and

• PensaSdk.isPensaStarted() returns true.

---

Fetch scan statuses

Method

@JvmStatic
fun fetchScanStatuses(
    scanIds: List<Int>,
    onSuccess: (List<PensaScanStatus>) -> Unit,
    onError: (String) -> Unit
)

Use this method to query the processing status and basic metadata for one or more scans.

If the SDK is not initialized, the method calls onError("Pensa SDK is not started.").

Parameters

• scanIds: List of scan IDs to query.

• onSuccess: Invoked with a list of PensaScanStatus objects when the request succeeds.

• onError: Invoked with an error message when the request fails.

From Java:

List<Integer> scanIds = Arrays.asList(1234, 4567);

PensaSdk.fetchScanStatuses(
    scanIds,
    statuses -> {
        for (PensaScanStatus status : statuses) {
            Log.d("Pensa", "Scan " + status.getId() + " status: " + status.getStatus());
        }
        return null;
    },
    errorMessage -> {
        Log.e("Pensa", "Failed to fetch scan statuses: " + errorMessage);
        return null;
    }
);

Models

data class PensaScanStatus(
    val id: Int,
    val scanAreaId: Int?,
    val status: String?,
    val fastStatus: String?,
    val scanTimestamp: String?,
    val created: String?,
    val captureType: String?,
    val frameHeight: Int?,
    val frameWidth: Int?,
    val hasOutOfServiceSegment: Boolean?,
    val imageCaptureQuality: String?,
    val publish: Boolean?,
    val scannerId: Int?,
    val shelfScanPeriodId: Int?,
    val metadata: PensaScanMetadata?
)

data class PensaScanMetadata(
    val applicationId: String?,
    val deviceNetworkName: String?,
    val deviceNetworkType: String?,
    val focalLength: Double?,
    val frameCaptureRate: Double?,
    val guid: String?,
    val ignoreLateUpload: Boolean?,
    val imageHeight: Int?,
    val imageWidth: Int?,
    val lensDistortion: List<Double>?,
    val lensIntrinsicCalibration: List<Double>?,
    val mobileCaptureCompleted: String?,
    val odrStatus: String?,
    val pauseList: List<String>?,
    val pipelineName: String?,
    val sensorPhysicalWidthHeight: List<Double>?,
    val serverUploadStarted: String?
)

Field reference: PensaScanStatus

• id: Scan ID.

• scanAreaId: Scan area ID associated with this scan.

• status: Current overall processing status of the scan (for example, IN_PROGRESS, COMPLETE).

• fastStatus: Status of earlier pipeline steps, used as a quicker approximation before the final status is available.

• scanTimestamp: Timestamp when the scan was captured.

• created: Timestamp when the scan record was created.

• captureType: Capture type (for example, IMAGE).

• frameHeight: Frame height in pixels.

• frameWidth: Frame width in pixels.

• hasOutOfServiceSegment: Indicates whether the scan includes an out‑of‑service segment.

• imageCaptureQuality: Capture quality classification.

• publish: Indicates whether the scan is marked for downstream publishing.

• scannerId: Identifier of the scanner device.

• shelfScanPeriodId: Identifier of the shelf scan period.

• metadata: Nested PensaScanMetadata with additional capture details.

Field reference: PensaScanMetadata

• applicationId

• deviceNetworkName

• deviceNetworkType

• focalLength

• frameCaptureRate

• guid

• ignoreLateUpload

• imageHeight

• imageWidth

• lensDistortion

• lensIntrinsicCalibration

• mobileCaptureCompleted

• odrStatus

• pauseList

• pipelineName

• sensorPhysicalWidthHeight

• serverUploadStarted

Example usage (Kotlin)

val scanIds = listOf(1234, 4567)

PensaSdk.fetchScanStatuses(
    scanIds = scanIds,
    onSuccess = { statuses ->
        statuses.forEach { status ->
            println("Scan ${status.id} status: ${status.status ?: "UNKNOWN"}")
            println("Fast status: ${status.fastStatus ?: "N/A"}")
        }
    },
    onError = { error ->
        println("Failed to fetch scan statuses: $error")
    }
)

---

Fetch on‑demand reports

Method

@JvmStatic
fun fetchOnDemandReports(
    scanId: Int,
    projectId: Int?,
    onSuccess: (PensaOnDemandReport) -> Unit,
    onError: (String) -> Unit
)

Use this method to fetch on‑demand analytical reports for a given scan. The primary report currently exposed is the ITEMS_SEEN report, which lists observed products for the scan.

If the SDK is not initialized, the method calls onError("Pensa SDK is not started.").

Parameters

• scanId: ID of the scan to fetch reports for.

• projectId: Optional project ID. Set this if you need to disambiguate between multiple projects.

• onSuccess: Invoked with a PensaOnDemandReport on success.

• onError: Invoked with an error message on failure.

From Java:

int scanId = 43049;
Integer projectId = null;

PensaSdk.fetchOnDemandReports(
    scanId,
    projectId,
    report -> {
        PensaOnDemandReportBucket bucket = report.getItemsSeen();
        if (bucket != null) {
            for (PensaOnDemandProduct product : bucket.getProductList()) {
                Log.d("Pensa", "Product: " + product.getProduct() + " / UPC: " + product.getUpc());
            }
        }
        return null;
    },
    errorMessage -> {
        Log.e("Pensa", "Failed to fetch on-demand reports: " + errorMessage);
        return null;
    }
);

Models

data class PensaOnDemandReport(
    val itemsSeen: PensaOnDemandReportBucket?,
)

data class PensaOnDemandReportBucket(
    val productList: List<PensaOnDemandProduct>
)

data class PensaOnDemandProduct(
    val brand: String?,
    val brandId: Int?,
    val category: String?,
    val categoryId: Int?,
    val manufacturer: String?,
    val manufacturerId: Int?,
    val product: String?,
    val productId: Int?,
    val upc: String?
)

Field reference

• PensaOnDemandReport.itemsSeen: Container for the ITEMS_SEEN report (if present).

• PensaOnDemandReportBucket.productList: List of products observed in the scan.

• PensaOnDemandProduct.brand: Brand name.

• PensaOnDemandProduct.brandId: Brand identifier.

• PensaOnDemandProduct.category: Category name.

• PensaOnDemandProduct.categoryId: Category identifier.

• PensaOnDemandProduct.manufacturer: Manufacturer name.

• PensaOnDemandProduct.manufacturerId: Manufacturer identifier.

• PensaOnDemandProduct.product: Product display name.

• PensaOnDemandProduct.productId: Product identifier.

• PensaOnDemandProduct.upc: UPC code for the product.

Example usage (Kotlin)

val scanId = 43049
val projectId: Int? = null

PensaSdk.fetchOnDemandReports(
    scanId = scanId,
    projectId = projectId,
    onSuccess = { report ->
        val bucket = report.itemsSeen
        if (bucket != null) {
            println("Items seen count: ${bucket.productList.size}")
            bucket.productList.forEach { product ->
                println("Product: ${product.product ?: "N/A"} (UPC: ${product.upc ?: "N/A"})")
            }
        } else {
            println("No ITEMS_SEEN bucket available for this scan.")
        }
    },
    onError = { error ->
        println("Failed to fetch on-demand reports: $error")
    }
)

---

Fetch product image as Base64

Method

@JvmStatic
fun fetchProductImageBase64(
    context: Context,
    productId: Int,
    onSuccess: (String) -> Unit,
    onError: (String) -> Unit
)

This helper method downloads the default reference image for the given product and returns it as a Base64‑encoded string.

Encodes the image bytes as a Base64 string and passes it to onSuccess.

If the SDK is not initialized, it calls onError("Pensa SDK is not started.").

Parameters

• context: Android Context used for image loading.

• productId: ID of the product whose reference image should be fetched.

• onSuccess: Invoked with a Base64‑encoded string representing the image.

• onError: Invoked with an error message when the operation fails.

Example: Converting Base64 back to Bitmap

PensaSdk.fetchProductImageBase64(
    context = this,
    productId = 1001,
    onSuccess = { base64 ->
        try {
            val bytes = android.util.Base64.decode(base64, android.util.Base64.DEFAULT)
            val bitmap = android.graphics.BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
            runOnUiThread {
                imageView.setImageBitmap(bitmap)
            }
        } catch (e: Exception) {
            e.printStackTrace()
        }
    },
    onError = { error ->
        println("Failed to fetch product image: $error")
    }
)

Example Project

For code examples and integration best practices, refer to our GitHub repository.