MailingsWebsite PersonalizationLoyalty Activities at CheckoutWeb Push NotificationsMobile Push

6. Integrating Actions in Your App

🚧

Before you begin, make sure you’ve completed these steps:

To submit details on customers’ actions, you’ll need to create API methods. For more information, please refer to the API integrations section.

Mindbox’s SDK offers the following 2 methods to call API methods from a mobile app:

  • executeAsyncOperation to send data to the system,
  • executeSyncOperation to receive data from the system.

Use the OperationBodyRequest constructor to create a request body when calling an API method.

Integration specifications

In this guide, we’ll demonstrate an example of how to call the SDK’s API to transmit data.

To submit data to Mindbox, relevant API methods must be set up. These must be configured separately for each project.

Your customer success manager is responsible for setting up and documenting these API methods.

❗️

You’ll need to have a document detailing all the required API methods before you proceed to the steps below.

Call scripts: examples

Authentication in the app

fun authorizeCustomer() {
    Mindbox.executeAsyncOperation(
        context,
        operationSystemName = "CheckGuide.auth",
        operationBody = OperationBodyRequest(
            customer = CustomerRequest(
                mobilePhone = "12025550159"
            )
        )
    )
}

Submitting Product and Category View actions

fun viewProduct() {
    Mindbox.executeAsyncOperation(
        context,
        operationSystemName = "CheckGuide.viewProduct",
        operationBody = OperationBodyRequest(
            viewProductRequest = ViewProductRequest(
                product = ProductRequest(
                    ids = Ids(
                        "website" to "123"
                    )
                )
            )
        )
    )
}

fun viewProductCategory() {
    Mindbox.executeAsyncOperation(
        context,
        operationSystemName = "CheckGuide.viewCategory",
        operationBody = OperationBodyRequest(
            viewProductCategory = ViewProductCategoryRequest(
                productCategory = ProductCategoryRequest(
                    Ids(
                        "website" to "123"
                    )
                )
            )
        )
    )
}

Submitting Item Added actions

Mindbox offers 2 methods to handle product lists (customers’ carts, favorites, etc.):

  • Add / delete individual products;
  • Set up list via a single request.

Popular product lists: Cart and Favorites.

fun addProductToCart() {
    Mindbox.executeAsyncOperation(
        context,
        operationSystemName = "CheckGuide.addProductToCart",
        operationBody = OperationBodyRequest(
            addProductToList = ProductListItemRequest(
                product = ProductRequest(
                    Ids(
                        "website" to "<Id Product в Website>"
                    )
                ),
                pricePerItem = 10.0

            )
        )
    )
}

fun setCart() {
    Mindbox.executeAsyncOperation(
        context,
        operationSystemName = "CheckGuide.setUpCart",
        operationBody = OperationBodyRequest(
            productList = arrayListOf(
                ProductListItemRequest(
                    count = 2.0, // <Number of items>
                    product = ProductRequest(
                        Ids(
                            "website" to "<Id Product в Website>"
                        )
                    ),
                    isPricePerItem = false, // if price per item is passed
                    price = 10.0
                ),
                ProductListItemRequest(
                    count = 2.0, // <Number of items>
                    product = ProductRequest(
                        Ids(
                            "website" to "<Id Product в Website>"
                        )
                    ),
                    isPricePerItem = true, // if price per line item is passed
                    price = 10.0
                ),
                ProductListItemRequest(
                    count = 2.0, // <Number of items>
                    productGroup = ProductGroupRequest(
                        Ids(
                            "website" to "<Id Product в Website>"
                        )
                    ),
                    isPricePerItem = true, // if price per line item is passed
                    price = 10.0
                ),
            )
        )
    )
}

Checking customer in segment: example

Run this request to check whether a customer belongs to a specific segment.

fun checkSegment() {
    Mindbox.executeSyncOperation(
        operationSystemName = "CheckGuide.checkSegment",
        context = context,
        operationBody = OperationBodyRequest(),
        onSuccess = { response -> Log.i("Success ", response.toString())},
        onError = {error -> Log.i("Error", error.toString())}
    )
}

Receiving personal recommendations: example

Run this request to return a personalized list of products compiled using one of the product recommendation algorithms.

fun getReco() {
    Mindbox.executeSyncOperation(
        operationSystemName = "CheckGuide.getReco",
        context = context,
        operationBody = OperationBodyRequest(
            recommendation = RecommendationRequest(
                limit = 3
            )
        ),
        onSuccess = { response -> Log.i("getReco Success", response.toString())},
        onError = {error -> Log.i("getReco Error", error.toString())}
    )
}

A detailed description of the executeAsyncOperation call

Run the Mindbox.executeAsyncOperation SDK method to submit data to Mindbox using async methods.

This method receives:

  • the system name of the operation;
  • the body of the request to Mindbox.

Instructions on calling the method Mindbox.executeAsyncOperation

Mindbox.executeAsyncOperation<T>(
  context: Context,
  operationSystemName: String,
  operationBody: T
)

val customerRequestBody = OperationBodyRequest(
  customer = CustomerRequest(
    email = "[email protected]",
    mobilePhone = "12025550159",
    customFields = CustomFields(
      "myField" to "myString"
    ),
    subscriptions = arrayListOf(
      SubscriptionRequest(
        isSubscribed = true,
        pointOfContact = PointOfContactRequest.EMAIL
      )
    )
  )
)

Mindbox.executeAsyncOperation(
  context = context,
  operationSystemName = "MyOperation",
  operationBody = CustomerRequestBody
)

Check your results:

  1. Create an API method in your Mindbox project,
  2. Integrate Mindbox.shared.executeAsyncOperation so that it is called in your app (for example, by tapping a button),
  3. Start the app and run the target action,
  4. Find the customer profile in the system and check that their profile displays the expected entry on the Actions tab.

For information on how to debug common errors, refer to the SDK Integration Checklist.

A detailed description of the executeSyncOperation call

Run Mindbox.shared.executeSyncOperation to execute synced operations.

This SDK method receives as parameters:

  • the system name of the operation
  • the body of the request to Mindbox
  • the callback for successful operations
  • the callback for unsuccessful operations.

A type object is passed to such callbacks, which includes the parsed Mindbox response.

You can also create your own class to process Mindbox’s responses if processing cannot be carried out using the SDK’s structures.

This class will be passed to the function call as an individual parameter.

Using a predefined class

Method description

Mindbox.executeSyncOperation(
  context: Context,
  operationSystemName: String,
  operationBody: T,
  onSuccess: (OperationResponse) -> Unit,
  onError: (MindboxError) -> Unit
)

Use the operationSystemName and operationBody parameters to make a request.

The request response is the Result\<OperationResponse, MindboxError> entity.

Example

Mindbox.executeSyncOperation(
      operationSystemName = "CheckGuide.getReco",
      context = context,
      operationBody = OperationBodyRequest(
          recommendation = RecommendationRequest(
              limit = 3
          )
      ),
      onSuccess = { response -> Log.i("getReco Success", response.toString())},
      onError = {error -> Log.i("getReco Error", error.toString())}
  )

Response definitions

OperationResponse is a model listing all the fields that a server might return. All these fields are optional.

MindboxError is an error model that Mindbox returns. Server errors could be:

  • validationError that contains the ValidationError model. This refers to fields with incorrect values;
  • protocolError that contains the ProtocolError model, returned for server responses with a 4XX status or for certain 5XX errors;
  • serverError that is returned for a 5ХХ status response without data from the server;
  • connectionError that is a request error due to a connection failure;
  • invalidResponse that is returned for an invalid server response;
  • internalError that refers to Mindbox’s configuration errors, response decoding errors, etc.;
  • unknown that is returned for unexpected behavior when the nested type is Error.

Use the errorDescription parameter for debugging.

Updated about 1 year ago