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 UIViewController/UIView:

 Pensa.shared.showStoreSearchView()

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:

Pensa.shared.showStoreChecklist(sectionKey: nil, guid: nil, globalStoreId: storeId)

This method takes the globalStoreId as a parameter and navigates directly to the specified store.

Handling Errors

To handle potential errors during store initialization, you can provide an onError callback to the showStoreChecklist method:

Pensa.shared.showStoreChecklist(globalStoreId: storeId,
                                onError: { error in
                                    print(error.localizedDescription)
                                })

The onError callback will be executed if an error occurs, providing a PensaError object that contains information about the 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.

Here's an example code block demonstrating how to use these parameters:

Pensa.shared.showStoreChecklist(sectionKey: sectionKey,
                                guid: guid,
                                globalStoreId: storeId,
                                onError: { error in
                                    print(error.localizedDescription)
                                })

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(globalStoreId:) 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:

Pensa.shared.showStoresScreen()

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:

Pensa.shared.showShelfScans()

Product Scans

Pensa.shared.showProductScans()

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:

Pensa.shared.showStockingScreen()

Scan Area

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

Pensa.shared.showScanArea(
    scanId: scanId,
    storeId: storeId,
    globalStoreId: globalStoreId
)

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

Scan & Image APIs

This section documents the programmatic APIs exposed by the Pensa iOS 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:

• Pensa.shared.initPensa(...) has been called successfully.

• Pensa.shared.isPensaStarted() returns true.

---

Fetch scan statuses

Method

public func fetchScanStatuses(
    scanIds: [Int],
    onSuccess: @escaping ([PensaScanStatus]) -> Void,
    onError: @escaping (PensaError) -> Void
)

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 with a PensaError("Pensa is not initialized.").

Parameters

• scanIds: List of scan IDs to query.

• onSuccess: Called with an array of PensaScanStatus objects when the request succeeds.

• onError: Called with a PensaError when the request fails.

Model: PensaScanStatus

public struct PensaScanStatus {
    public let id: Int
    public let scanAreaId: Int?
    public let status: String?
    public let fastStatus: String?
    public let scanTimestamp: String?

    public let created: String?
    public let scanMetadataGuid: String?
    public let scanMetadataServerUploadStarted: String?

    public let captureType: String?
    public let frameHeight: Int?
    public let frameWidth: Int?
    public let hasOutOfServiceSegment: Bool?
    public let imageCaptureQuality: String?
    public let publish: Bool?
    public let scannerId: Int?
    public let shelfScanPeriodId: Int?
}

Field reference:

• 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 the early processing 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.

• scanMetadataGuid: GUID from the scan metadata.

• scanMetadataServerUploadStarted: Timestamp when the server-side upload for this scan started.

• 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

• scannerId: Identifier of the scanner device.

• shelfScanPeriodId: Identifier of the shelf scan period.

Example usage

let scanIds = [1234, 4567]

Pensa.shared.fetchScanStatuses(
    scanIds: scanIds,
    onSuccess: { statuses in
        for status in statuses {
            print("Scan \(status.id) status: \(status.status ?? "UNKNOWN")")
            print("Fast status: \(status.fastStatus ?? "N/A")")
            print("Scan GUID: \(status.scanMetadataGuid ?? "N/A")")
        }
    },
    onError: { error in
        print("Failed to fetch scan statuses: \(error.localizedDescription)")
    }
)

---

Fetch on-demand reports

Method

public func fetchOnDemandReports(
    scanId: Int,
    projectId: Int?,
    onSuccess: @escaping (PensaOnDemandReport) -> Void,
    onError: @escaping (PensaError) -> Void
)

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 with a PensaError("Pensa is not initialized.").

Parameters

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

• projectId: Optional project ID. Set this if you need to.

• onSuccess: Called with a PensaOnDemandReport on success.

• onError: Called with a PensaError on failure.

Models

public struct PensaOnDemandReport {
    public let itemsSeen: PensaOnDemandReportBucket?

    public init(
        itemsSeen: PensaOnDemandReportBucket?
    ) {
        self.itemsSeen = itemsSeen
    }
}

public struct PensaOnDemandReportBucket {
    public let productList: [PensaOnDemandProduct]

    public init(productList: [PensaOnDemandProduct]) {
        self.productList = productList
    }
}

public struct PensaOnDemandProduct {
    public let brand: String?
    public let brandId: Int?
    public let category: String?
    public let categoryId: Int?
    public let manufacturer: String?
    public let manufacturerId: Int?
    public let product: String?
    public let productId: Int?
    public let upc: String?

    public init(
        brand: String?,
        brandId: Int?,
        category: String?,
        categoryId: Int?,
        manufacturer: String?,
        manufacturerId: Int?,
        product: String?,
        productId: Int?,
        upc: String?
    ) {
        self.brand = brand
        self.brandId = brandId
        self.category = category
        self.categoryId = categoryId
        self.manufacturer = manufacturer
        self.manufacturerId = manufacturerId
        self.product = product
        self.productId = productId
        self.upc = upc
    }
}

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

let scanId = 43049
let projectId: Int? = nil

Pensa.shared.fetchOnDemandReports(
    scanId: scanId,
    projectId: projectId,
    onSuccess: { report in
        if let bucket = report.itemsSeen {
            print("Items seen count: \(bucket.productList.count)")
            for product in bucket.productList {
                print("Product: \(product.product ?? "N/A") (UPC: \(product.upc ?? "N/A"))")
            }
        } else {
            print("No ITEMS_SEEN bucket available for this scan.")
        }
    },
    onError: { error in
        print("Failed to fetch on-demand reports: \(error.localizedDescription)")
    }
)

---

Fetch product image as Base64

Method

public func fetchProductImageBase64(
    productId: Int,
    onSuccess: @escaping (String) -> Void,
    onError: @escaping (PensaError) -> Void
)

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

Encodes the data as Base64 and returns it via onSuccess.

If the SDK is not initialized or the URL is invalid, it calls onError.

Parameters

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

• onSuccess: Called with a Base64-encoded string representing the image.

• onError: Called with a PensaError when the operation fails.

Example: Converting Base64 back to UIImage

Pensa.shared.fetchProductImageBase64(
    productId: 1001,
    onSuccess: { base64 in
        if let data = Data(base64Encoded: base64),
           let image = UIImage(data: data) {
            DispatchQueue.main.async {
                imageView.image = image
            }
        } else {
            print("Failed to decode Base64 image data.")
        }
    },
    onError: { error in
        print("Failed to fetch product image: \(error.localizedDescription)")
    }
)

Example Project

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