In-app store

Owned by Roman Teterin (Unlicensed)
Last updated: Aug 14, 2024
4 min read

SDK Overview

The SDK provides functionality for users to purchase various in-app products, such as maps, POI bundles, voice packs, and more.

InAppStoreManager

The primary interface for managing in-app purchases is the InAppStoreManager class.

Item

The Item class serves as the base class for all in-app store items, which include groups, countries, and products. Each item is identified by a unique identifier and has a name. An item can also contain a badge represented by the ItemBadge class, which is a small icon that can be displayed alongside the item in the UI.

Each item also has the refresh() method, which must be called when the installation status changes to update the data stored in the item.

Products

A product is an item within the in-app store that can be purchased (if not free) and installed.

Product Dependencies

Products can have both required and optional dependencies:

  • Required Dependencies: Automatically installed when the product is installed.

  • Optional Dependencies: Can be installed by passing a parameter to the installProduct() method (described below).

Groups

Groups are used to organize in-app store items. Each group contains a list of items and offers methods to provide aggregate statistics, such as getUpdateCount().

Countries

A country is a specialized group that includes an ISO3 code. It also contains a list of maps, accessible via the getMaps() method. One map is designated as the main map, which can be retrieved using the getMainProduct() method.

Subscribing to In-App Store Events

The SDK offers the InAppStoreEventListener interface to receive notifications about in-app store events, including product list preparation, product installation, and product purchase.

Working with the InAppStoreManager

Obtaining an Instance of InAppStoreManager

You can obtain an instance of InAppStoreManager by calling the SDK.getInAppStoreManager() method. Unlike other methods, this one requires an Activity argument, which will host the system purchase dialogs if needed during installation.

Preparing the Product List

Before using the in-app store, the product list must be downloaded from the server by calling the InAppStoreManager.prepareProductList() method. Upon successful completion, as notified by the InAppStoreEventListener.onProductListPrepared() callback, retrieve the root group using the InAppStoreManager.getRootGroup() method.

The root group contains top-level items (usually regions, such as Europe or Asia). Applications can:

  • Display these items for user navigation (similar to a file manager).

  • Collect all products by traversing the tree recursively and display them linearly.

  • Implement other interfaces as needed.

Note: The product list may contain loops, so care should be taken when iterating recursively.

The current status of the product list preparation can be retrieved using the isProductListPreparationInProgress() and isProductListPrepared() methods of the InAppStoreManager.

Retrieving Items

The InAppStoreManager class offers methods to retrieve items by their identifiers:

  • getGroup()

  • getCountry()

  • getProduct()

If an item with the specified identifier doesn't exist, these methods will return null.

Another set of methods is provided to retrieve products in a specific state (such as purchased or installed products) or belonging to a specific product type (e.g., all maps):

  • getInstalledProducts()

  • getPurchasedProducts()

  • getProductsBeingInstalled()

  • getProductsWithUpdate()

  • getProducts(ProductType)

Searching the Product List

The SDK enables you to search for specific items using a pattern with the InAppStoreManager.findItems() method. This method accepts the root group's identifier, the search pattern, and a listener for notification upon successful completion. To cancel an ongoing search, use the InAppStoreManager.cancelItemsSearch() method.

Purchasing Products

If a product needs to be purchased, call the InAppStoreManager.purchaseProduct() method, passing the product's identifier. The user will be redirected to the system purchase dialog to complete the purchase. Upon successful purchase, the InAppStoreEventListener.onProductPurchased() callback will be called, and the product can be installed either immediately or at a later time.

Installing Products

To install a product, call the InAppStoreManager.installProduct() method, passing the product identifier and the includeOptionalDependencies parameter. Installation progress can be monitored through the following InAppStoreEventListener callbacks:

  • onInstallationStatusChanged

  • onInstallationProgressChanged

  • onInstallationErrorOccurred

  • onInstallationFinished: Called when the installation process is completed, regardless of success, failure, or cancellation.

In addition to these callbacks, it’s possible to retrieve the current installation status by using the corresponding methods of the InAppStoreManager:

  • getInstallationStatus()

  • getInstallationProgress()

  • getInstallationError()

The InstallationProgress class contains the getPercentage() method, which returns the progress as a floating-point value ranging from 0 to 100, and the isPaused() method, which returns true if the installation is paused.

The InstallationStatus class contains the getStatusCode() method, allowing users to determine the current status of the installation (whether the product is queued, downloading, installing, etc.).

Both status and progress can be retrieved for each product individually or for the entire installation.

Purchase-related operations have their own callbacks, such as:

  • onProductPurchased()

  • onProductPurchaseFailed()

Once the installation is successful, the installed products will be available to the SDK.

Updating Products

If a product has an available update, its hasUpdate() method will return true. The product can be updated by calling the InAppStoreManager.updateProduct() method. The update process is similar to the installation process.

Pausing and Resuming Installation

To pause the installation of a specific product or all products, use the InAppStoreManager.pauseInstallation() overloaded methods:

  • Method with a string parameter: Pauses the installation of the product with the specified identifier.

  • Method without parameters: Pauses the entire installation process.

To resume installation, use the corresponding resumeInstallation() methods.

Cancelling Installation

You can cancel the installation of a specific product or all products using the InAppStoreManager.cancelInstallation() overloaded methods:

  • Method with a string parameter: Cancels the installation of the specified product.

  • Method without parameters: Cancels the entire installation process.

Removing Installed Products

To remove an installed product, call the InAppStoreManager.uninstallProduct() method, passing either a single product identifier or a list of identifiers.

Promotions

The SDK allows you to retrieve a list of promoted products, which, for example, can be displayed in a banner inside the application. A promotion is represented by the Promotion class and contains the following information:

  • title

  • text

  • URL

  • priority

  • rating

  • price

  • Whether it’s free or paid

  • Whether it’s new or has an update

  • The identifier of the corresponding product

The list of promotions can be retrieved via the InAppStoreManager.getPromotions() method.