Using the App Extension API

Our App Extension feature allows you to display custom (web) content in your app. Using NewStore's App Extension API, your app extensions can leverage the native functionality of NewStore Shopping App.

Availability

Version supported from

This feature is supported from iOS app version 3.13.x and Android app version 1.106.x or later.

Most methods are available in all contexts and we aim to have all methods available on both platforms. However in some situations the feature that is responsible for exposing the method might not be available given the context. For example: in the context of the Scan & Learn mini app, the cart feature is not available, resulting in any  methods related to managing the cart being not available.

Method availability also depends on the version of the app, which is documented in the API reference.

We have introduced the isMethodAvailable method to query for method availability.

Error handling

Errors are raised using the Promises concept of JavaScript. All methods return a Promise that either contains the requested value or a an error detailing what went wrong. All errors raised by the bridge use the NCABridgeError type (for general errors). Methods can also raise more detailed errors by raising an error that is a subclass of NCABridgeError. See NCABridgeAddProductToCartError for an example.

General error type - NCABridgeError

Setup

// Instantiate a shared instance of the communication bridge
const bridge = new NCABridge();

Minimal example

Storing and retrieving a local storage value​

// Instantiate a shared instance of the communication bridge
const bridge = new NCABridge();

// Get the user's session ID from local storage
async function getUserSession() {
  return bridge.localStorageGet("user_session");
}

// Update the user's session ID in local storage
async function updateUserSession(sessionId) {
  return bridge.localStorageSet("user_session", sessionId);
}

// Remove the user's session ID from local storage
async function removeUserSession() {
  return bridge.localStorageSet("user_session", null);
}

Exhaustive example

Adding a product to the native cart and handling related errors appropriately​

// Instantiate a shared instance of the communication bridge
const bridge = new NCABridge();

async function addToCart() {
  try {

    // Add the product with the given configuration to the native card
    await bridge.addProductToCart("1234", {
      color: "red",
      size: "L"
    },
    true, {
      "text": "Happy!", 
      "logo": "20th_anniversary" 
    });

  }
  catch (error) {

    // Handles specific errors related to the `addProductToCart` method
    if (error instanceof NCABridgeAddProductToCartError) {

      // Every subclass of `NCABridgeError` contains a `code` property which can be used to determine the type of the error programmatically
      switch (error.code) {

        case NCABridgeAddProductToCartError.Code.invalidProductId:
          // The passed product id is invalid. It should be a non-empty String

        case NCABridgeAddProductToCartError.Code.productNotFound:
          // The product does not exist (or not returned from the Ecom API for another reason)

        case NCABridgeAddProductToCartError.Code.configurationUnavailable:
          // The configuration passed to the `addProductToCart` method is invalid or out of stock

        case NCABridgeAddProductToCartError.Code.configurationIncomplete:
          // The configuration passed to the `addProductToCart` method doesn't lead to a buyable product

        default:
          // Any other error
      }
    }
    else if (error instanceof NCABridgeError) {

      switch (error.code) {
        case NCABridgeError.Code.bridgeCommunication:
          // The connection with the native bridge could not be established
        default:
          // Any other error
      }

    }
    else {
      // Anything else
    }
  }
}

API Reference

General

isMethodAvailable

isMethodAvailable(name: String) : Promise<Bool>

Use this method in order to determine whether a method is available in the current context. Method availability could differ between the main app and mini apps, which only offer a subset of features from the main app.

Parameters

Error type NCABridgeIsMethodAvailableError

dismissAppExtension

dismissAppExtension() : Promise<null>

Dismisses the current active App Extension (screen).

Local storage

localStorageSet

localStorageSet(key: String, value: String?) : Promise<null>

Important

The local storage is not intended for storing sensitive information. In theory, any values stored could be read by any content shown in any app extension.

Note

Logging in or out of your account in the app will clear the local storage database.

Stores a value in the local storage using the given key. Values stored can be retrieved using the localStorageGet method

Parameters

Error type NCABridgeLocalStorageSetError

localStorageGet

localStorageGet(key: String) : Promise<String?>

Note

Local storage values are pinned to the domain where the app extension is hosted. A local storage value saved by extensionA.website.com can not be read by an app extension hosted on extensionB.website.com.

Returns the value that is stored in the local storage for the given key. Values stored in local storage using the localStorageSet method can be retrieved using this method.

Parameters

Products

addProductToCart

addProductToCart(productId: String, configuration: Object?, showAnimation: Bool, customisation: Object?) : Promise<null>

Adds a product to the native cart using its ID and the specified configuration.

This method takes 4 input arguments: a product ID (either master or variant), an optional product configuration Object (required, when a master product ID is passed), a boolean value to indicate the app should perform an animation when adding a product to the cart and an optional customization Object.

Parameters

Error type - NCABridgeAddProductToCartError

addProductToFavorites

addProductToFavorites(productId: String, showAnimation: Bool) : Promise<null>

Adds a product to the native favorites feature by its ID.

Parameters

Error type NCABridgeAddProductToFavoritesError

removeProductFromFavorites

removeProductFromFavorites(productId: String) : Promise<null>

Removes a product from the native favorites feature by its ID.

Parameters

Error type NCABridgeRemoveProductFromFavoritesError

fetchFavorites

fetchFavorites() : Promise<String?>

Returns a comma-separated string with all product IDs that have been added to favorites.

getProductConfiguration

async getProductConfiguration() : Promise<Object>

Returns the current product configuration. For example: { "c_size": "m", "color": "464UD1" }

updateProductConfiguration

async updateProductConfiguration(configuration) : Promise<null>

Updates the configuration of the product with the new attribute values provided in the configuration object.

Parameters