E-Commerce Ingest Events

Causal Foundry SDK E-Commerce module consists of events for online marketplace platforms. You need to implement this module if your app offers e-commerce content that may include showcasing items to purchase, logging impressions, checking out events, and also events related to delivery as well.

List of Events

Event Name	Type	Description
Item	item	Track actions on item, views, details, or item impression in a list.
Cart	cart	Track changes in the cart, when an item is being added or removed.
Checkout	checkout	Track when an item is checkout or unable to checkout.
Delivery	delivery	Track when an item is delivered.
Cancel Checkout	cancel_checkout	Track when user cancels a checkout or discards a cart.
Item Report	item_report	Track when user reports an item.
Item Request	item_request	Track when user requests an item.
Item Verification	item_verification	Track when user verifies an item.
Item Impression Listener	item	Track when an item is shown to the user in a list.

---

Item Event

To log item related events which includes when an item is viewed and when an item's detail is viewed.

Format

Param	Usability	Format	Enum Values	Description
action	REQUIRED	STRING	impression, view, detail, add_favorite, remove_favorite, add_reminder, remove_reminder, remove_reminder_auto, top_up, cancel, update, remove, add, select	Action applied on the item.
item	REQUIRED	OBJECT ITEM OBJECT	---	Details about the item used in the event.
meta	OPTIONAL	ANY	---	Any additional value that is sent with the log.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)JSON

    val itemModel = ItemModel(
        id = "testItemId", 
        quantity = 10, 
        price = 1900F, 
        currency = CurrencyCode.USD.name, 
        type = ItemType.drug.name
    )

    CfLogItemEvent.Builder()
        .setItem(itemModel)
        .setItemAction(ItemAction.view)
        .build()

    let itemDetail = {
        id: "itemId",
        type: ItemType.Drug,
        quantity: 1,
        price: 1.45,
        currency: CurrencyCode.EUR,
        stock_status: StockStatus.InStock,
        promo_id: "testPromoId",
    }

    let itemProperties = {
        action: ItemAction.View,
        item: itemDetail,
    }

    CfECom.logItemEvent(itemProperties, catalogObject) // catalog object can be null.

     let itemDetail = {
        id: "itemId",
        type: ItemType.Drug,
        quantity: 1,
        price: 1.45,
        currency: CurrencyCode.EUR,
        stock_status: StockStatus.InStock,
        promo_id: "testPromoId",
    }

    const itemProps = {
        action: ItemAction.AddFavorite
        item: itemDetail,
    }

    ECommerce.logItemEvent(itemProps, catalogObject) // catalog object can be null.

{
  "type": "item",
  "props": {
    "action": "view",
    "item": {
      ...
      // Item Object
    }
  }
}

---

Cart Event

To log cart related events which includes when an item is added or removed from a cart.

Format

Param	Usability	Format	Enum Values	Description
id	REQUIRED	STRING	---	Cart Id for the cart being modified.
action	REQUIRED	STRING	add_item, remove_item	Action applied on the item inside the cart.
cart_price	REQUIRED	FLOAT	---	Total price of the cart.
currency	REQUIRED	STRING	---	ISO based currency code associated with the cart price. (USD, EUR, CAD, ...)
item	REQUIRED	OBJECT ITEM OBJECT	---	Details about the item(s) used in the event.
meta	OPTIONAL	ANY	---	Any additional value that is sent with the log.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)JSON

    val itemModel = ItemModel(
        id = "testItemId", 
        quantity = 10, 
        price = 1900F, 
        currency = CurrencyCode.USD.name, 
        type = ItemType.drug.name
    )

    CfLogCartEvent.Builder()
        .setCartId("testCartId")
        .setCartAction(CartAction.add_item)
        .setItem(itemModel)
        .setCurrency(CurrencyCode.USD.name)
        .setCartPrice(1900)
        .build()

    let itemDetail = {
        id: "itemId",
        type: ItemType.Drug,
        quantity: 1,
        price: 1.45,
        currency: CurrencyCode.EUR,
        stock_status: StockStatus.InStock,
        promo_id: "RandomPromoId",
    }

    let cartProperties = {
        id: "testCartId",
        action: CartAction.AddItem,
        item: itemDetail,
        cart_price: 1.45,
        currency: CurrencyCode.EUR,
    }

    CfECom.logCartEvent(cartProperties)

    let itemDetail = {
        id: "itemId",
        type: ItemType.Drug,
        quantity: 1,
        price: 1.45,
        currency: CurrencyCode.EUR,
        stock_status: StockStatus.InStock,
        promo_id: "RandomPromoId",
    }

    const cartEvent = {
        id: "cartId",
        action: CartAction.AddItem,
        item: itemDetail,
        cart_price: 1.45,
        currency: CurrencyCode.EUR,
    }

    ECommerce.logCartEvent(cartEvent)

{
  "type": "cart",
  "props": {
    "id": "testCartId",
    "action": "add_item",
    "cart_price": 1900.0,
    "currency": "USD",
    "item": {
      ...
      // Item Object
    }
  }
}

---

Checkout Event

To log checkout related events which includes when an items being purchased.

Format

Param	Usability	Format	Enum Values	Description
id	REQUIRED	STRING	---	Order Id for the placement.
cart_id	REQUIRED	STRING	---	Cart Id for the order being checked out.
cart_price	REQUIRED	FLOAT	---	Total price of the cart at checkout.
currency	REQUIRED	STRING	---	ISO based currency code associated with the cart price. (USD, EUR, CAD, ...)
shop_mode	OPTIONAL	STRING	delivery, pickup	shop mode selected the order, if it is a delivery based order or a pickup order.
items	REQUIRED	ARRAY (ITEM OBJECT)	---	Details about the item(s) used in the event, all od the items in the order.
is_successful	REQUIRED	BOOLEAN	---	If the order checked out is successful or not.
meta	OPTIONAL	ANY	---	Any additional value that is sent with the log.

Meta Properties

Some item types requires certain elements to be provided using meta properties. Please refer to your integration notes to verify which fields are required for your use-case.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)JSON

    val itemModel = ItemModel(
        id = "testItemId", 
        quantity = 10, 
        price = 1900F, 
        currency = CurrencyCode.USD.name, 
        type = ItemType.drug.name
    )

    CfLogCheckoutEvent.Builder()
        .setOrderId("testOrderId")
        .setCartId("testCartId")
        .setPrice(900f)
        .setCurrency(CurrencyCode.USD.name)
        .setShopMode(ShopMode.pickup)
        .addItem(itemModel)
        .build()

    let itemDetail = {
        id: "itemId1",
        type: ItemType.Drug,
        quantity: 1,
        price: 1.45,
        currency: CurrencyCode.EUR,
        stock_status: StockStatus.InStock,
        promo_id: "RandomPromoId"
    }

    let checkoutProperties = {
        id: "testOrderId",
        cart_id: "testCartId",
        is_successful: false,
        cart_price: 5.9,
        currency: CurrencyCode.EUR,
        shop_mode: ShopMode.Pickup,
        items_list: [itemDetail]
    }

    CfECom.logCheckoutEvent(checkoutProperties)

    let itemDetail = {
        id: "itemId1",
        type: ItemType.Drug,
        quantity: 1,
        price: 1.45,
        currency: CurrencyCode.EUR,
        stock_status: StockStatus.InStock,
        shop_mode: ShopMode.Pickup,
        promo_id: "RandomPromoId"
    }

    const checkoutEvent = {
        id: orderId,
        is_successful: true,
        cart_price: 1.45,
        currency: CurrencyCode.EUR,
        items: [itemDetail],
        cart_id: "cartId"
    }

    ECommerce.logCheckoutEvent(checkoutEvent)

    {
      "type": "checkout",
      "props": {
        "id": "testOrderId",
        "cart_id": "testCartId",
        "cart_price": 900.0,
        "currency": "EUR",
        "shop_mode": "delivery",
        "is_successful": true,
        "items": [
          {
            ...
            // Item Object
          },
          {
            ...
            // Item Object
          }
        ]
      }
    }

---

Delivery Event

To log delivery related events which includes when an item is delivered.

Format

Param	Usability	Format	Enum Values	Description
id	REQUIRED	STRING	---	Delivery Id for the order being delivered.
order_id	REQUIRED	STRING	---	Order Id for the order being delivered.
action	REQUIRED	STRING	schedule, update, dispatch, delivered	Action applied on the delivery event.
is_urgent	REQUIRED	BOOLEAN	---	Is delivery event marked as urgent delivery.
est_delivery_ts	OPTIONAL	STRING	---	Estimated delivery time in ISO. ISO 8601 format.
delivery_coordinates	OPTIONAL	OBJECT (COORDINATES OBJECT)	---	Coordinates for the place where the delivery is going to be made.
dispatch_coordinates	OPTIONAL	OBJECT (COORDINATES OBJECT)	---	Coordinates for the place where the order is going to be dispatched from.
meta	OPTIONAL	ANY	---	Any additional value that is sent with the log.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)JSON

    CfLogDeliveryEvent.Builder()
        .setOrderId("testOrderId")
        .setDeliveryAction(DeliveryAction.delivered)
        .setDeliveryId("testDeliveryId")
        .build()

    let deliveryProperties = {
        id: "TestDeliveryId",
        order_id: "TestOrderId",
        action: DeliveryAction.Delivered,
    }

    CfECom.logDeliveryEvent(deliveryProperties)

    let deliveryProperties = {
        id: "TestDeliveryId",
        order_id: "TestOrderId",
        action: DeliveryAction.Delivered,
    }

    ECommerce.logDeliveryEvent(deliveryProperties)

{
  "type": "delivery",
  "props": {
    "id": "testDeliveryId",
    "action": "delivered",
    "order_id": "testOrderId"
  }
}

---

Cancel Checkout Event

To log Cancel Checkout related events which includes when item(s) is cancelled.

Format

Param	Usability	Format	Enum Values	Description
id	REQUIRED	STRING	---	Order/cart Id for the order being canceled.
type	REQUIRED	STRING	cart, order	type of the list being canceled.
items	REQUIRED	ARRAY (ITEM TYPE OBJECT)	---	List of items being cancelled.
reason	OPTIONAL	STRING	---	Reason for canceling.
meta	OPTIONAL	ANY	---	Any additional value that is sent with the log.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)JSON

    CfLogCancelCheckoutEvent.Builder()
        .setCheckoutId("testCartId")
        .setCancelType(CancelType.cart)
        .setCancelReason("testreason")
        .addItem(ItemTypeModel("ItemID1", ItemType.drug.name))
        .addItem(ItemTypeModel("ItemID2", ItemType.drug.name))
        .build()

    let itemTypeModel = {
        id: "itemId1",
        type: ItemType.Drug
    }

    let cancelCheckoutProperties = {
        id: "TestOrderId",
        type: "order",
        items_list: [itemTypeModel],
        reason: "took too long"
    }

    CfECom.logCancelCheckoutEvent(cancelCheckoutProperties)

    let itemTypeModel = {
        id: "itemId1",
        type: ItemType.Drug
    }

    let cancelCheckoutProperties = {
        id: "TestOrderId",
        type: "order",
        items_list: [itemTypeModel],
        reason: "took too long"
    }

    ECommerce.logCancelCheckoutEvent(cancelCheckoutProperties)

{
  "type": "cancel_checkout",
  "props": {
    "id": "testCartId",
    "items": [
      {
        ...
        // Item Min Object
      },
      {
        ...
        // Item Min Object
      }
    ],
    "reason": "test reason",
    "type": "cart"
  }
}

---

Item Report Event

To log Item Report Event.

Format

Param	Usability	Format	Enum Values	Description
item	REQUIRED	OBJECT (ITEM TYPE OBJECT)	---	Details for the item in report event.
store_info	REQUIRED	OBJECT (STORE OBJECT)	---	Store details for the item in report event.
report_info	REQUIRED	OBJECT (REPORT OBJECT)	---	Report details for the item in report event.
meta	OPTIONAL	ANY	---	Any additional value that is sent with the log.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)JSON

     CfLogItemReportEvent.Builder()
        .setItem(ItemTypeModel("itemId", ItemType.drug.name))
        .setStoreObject(StoreObject("storeId", 22f, 23f))
        .setReportObject(ReportObject("reportId", "short  Value", "large Value"))
        .build()

    let itemTypeModel = {
        id: "itemId1",
        type: ItemType.Drug,
    }

    let storeObject = {
        id: "storeId",
        lat: 41.390205,
        lon: 2.154007,
    }

    let reportObject = {
        id: "TestReportId",
        short_desc: "order",
        remarks: "took too long",
    }

    let reportProps = {
        item : itemTypeModel,
        store_info : storeObject,
        report_info : reportObject
    }

    CfECom.logItemReportEvent(reportProps)

    let itemTypeModel = {
        id: "itemId1",
        type: ItemType.Drug,
    }

    let storeObject = {
        id: "storeId",
        lat: 41.390205,
        lon: 2.154007,
    }

    let reportObject = {
        id: "TestReportId",
        short_desc: "order",
        remarks: "took too long",
    }

    let reportProps = {
        item : itemTypeModel,
        store_info : storeObject,
        report_info : reportObject
    }

    ECommerce.logItemReportEvent(reportProps)

{
  "type": "item_report",
  "props": {
    "item": {
      "id": "itemId",
      "type": "drug"
    },
    "report_info": {
      "id": "reportId",
      "remarks": "Detailed description",
      "short_desc": "short description"
    },
    "store_info": {
      "id": "storeId",
      "lat": 41.390205,
      "lon": 2.154007
    }
  }
}

---

Item Request Event

To log Item Request Event.

Format

Param	Usability	Format	Enum Values	Description
id	REQUIRED	STRING	---	id for the request element event.
item_name	REQUIRED	STRING	---	Name for the item in request event.
manufacturer	REQUIRED	STRING	---	Manufacturer name for the item in request event.
meta	OPTIONAL	ANY	---	Any additional value that is sent with the log.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)JSON

    CfLogItemRequestEvent.Builder()
        .setItemRequestId("ItemRequestId")
        .setItemName("Item Name")
        .setItemManufacturer("Item Manufacturer")
        .build()

    let requestProps = {
        request_id : "requestId",
        item_name : "testItemName",
        manufacturer : "manufacturer Name"
    }

    CfECom.logItemRequestEvent(requestProps)

    let requestProps = {
        request_id : "requestId",
        item_name : "testItemName",
        manufacturer : "manufacturer Name"
    }

    ECommerce.logItemRequestEvent(requestProps)

{
  "type": "item_request",
  "props": {
    "id": "itemRequestId",
    "item_name": "Item Name",
    "manufacturer": "Item Manufacturer"
  }
}

---

Item Verification Event

To log Item Verification Event.

Format

Param	Usability	Format	Enum Values	Description
scan_channel	REQUIRED	STRING	app, ussd	Scan channel for the item verification.
scan_type	REQUIRED	STRING	pin, qr_code	Scan type for the item verification.
is_successful	REQUIRED	BOOLEAN	---	If Item verification was successful. If no, there will be no Item Info Object.
item_info	REQUIRED	OBJECT (ITEM INFO OBJECT)	---	Details about the Item in verification.
meta	OPTIONAL	ANY	---	Any additional value that is sent with the log.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)JSON

    CfLogItemVerificationEvent.Builder()
        .setScanChannel(ScanChannel.app)
        .setScanType(ScanType.pin)
        .isSuccessful(true)
        .setItemInfo(ItemInfoObject(
            id = "ItemId",
            type = ItemType.drug.name,
            batch_id = "batch000",
            survey_id = "survey_id0",
            reward_id = "reward_id0",
            is_featured = false,
            production_date = System.currentTimeMillis(),
            expiry_date = System.currentTimeMillis()
        )).build()

    let itemInfoProperties = {
        id: "testItemId",
        type: ItemType.Grocery,
        batch_id: "2134",
        survey_id: "9876",
        reward_id: "4455",
        is_featured: true,
        production_date: 1680788331012,
        expiry_date: 1780788331012
    }

    let verificationProps = {
        scan_channel: ScanChannel.App,
        scan_type: ScanType.QrCode,
        is_successful: true,
        item_info: itemInfoProperties
    }

    CfECom.logItemVerificationEvent(verificationProps)

    let itemInfoProperties = {
        id: "testItemId",
        type: ItemType.Grocery,
        batch_id: "2134",
        survey_id: "9876",
        reward_id: "4455",
        is_featured: true,
        production_date: 1680788331012,
        expiry_date: 1780788331012
    }

    let verificationProps = {
        scan_channel: ScanChannel.App,
        scan_type: ScanType.QrCode,
        is_successful: true,
        item_info: itemInfoProperties
    }

    ECommerce.logItemVerificationEvent(verificationProps)

{
  "type": "item_verification",
  "props": {
    "scan_channel": "app",
    "scan_type": "pin",
    "is_successful": true,
    "item_info": {
      "id": "ItemId",
      "type": "drug",
      "batch_id": "batch000",
      "reward_id": "reward_id0",
      "survey_id": "survey_id0",
      "is_featured": false,
      "expiry_date": 1680771806334,
      "production_date": 1680771806334
    }
  }
}

---

Item Impression Listener

To log when an item is shown to the user in a list, marking the impression of the item.

Partially Auto-Tracked

Item impression listener needs to be set up on the listviews/recyclerviews for it to start listening when the items are shown to the users.

Usage

Android (Java/Kotlin)React Native (JS/TS)Web Application (JS/TS)

No Jetpack Compose Support

Currently the Impression listener does not provide support for Jetpack Compose LazyColumn or LazyRow but for RecyclerViews (XML-based layouts) only. In order to use for Jetpack Compose, you need to create your own listener and can directly use the item event with action as impression.

    CfItemImpressionListener.trackRecyclerView(
        recyclerView = binding.imageRecyclerView, // RecyclerView to which the impression listener will be attached.
        currentDataProvider = {
            ProductsList.map { // map your internal product list to the SDK's one to provide details about the items.
                ItemImpressionModel(
                    itemProperties = ItemModel(
                        id = it.itemId,
                        quantity = it.quantity,
                        price = (it.quantity * it.price),
                        currency = CurrencyCode.IDR.name,
                        type = ItemType.drug.name,
                        stockStatus = ItemStockStatus.in_stock.name,
                        promoId = "testPromoId"
                    ),
                    catalogProperties = DrugCatalogModel(
                        market_id = "id", 
                        name = "MedName",
                        description = "",
                        supplier_id = "SupplierId",
                        supplier_name = "SupplierName",
                        producer = "",
                        packaging = "",
                        active_ingredients = [paracetamol],
                        drug_form = "otc",
                        drug_strength = "",
                        atc_anatomical_group = "",
                        otc_or_ethical = "otc"
                    )
                )
            }
        }
    )

Causal Foundry React native SDK currently supports RecyclerListViewScreen for the impression listener as it helps in recycling the views and improving performance. To start with the implementation,, you need to first map your list in the format required by the SDK.

    var contentList = YOUR_LIST.map((product, index) => ({
        item_properties: {
            id: product.id,
            price: product.price,
            currency: CurrencyCode.IDR,
            quantity: product.quantity,
            type: ItemType.Drug,
            stock_status: StockStatus.InStock,
            promo_id: "testPromoId"
        },
        catalog_properties: { // can be DrugProperties or any other e-commerce catalog props
            market_id: "id",
            name: "MedName",
            description: "testItemDescription",
            supplier_id: "SupplierId",
            supplier_name: "SupplierName",
            producer: "testProducerName",
            packaging: "10ML",
            active_ingredients: active_ingredients_array,
            drug_form: "",
            drug_strength: "",
            atc_anatomical_group: "",
            otc_or_ethical: ""
        }
    }))

then on your _lonVisibleIndicesChanged call the impression listener and pass the contentList:

    const _lonVisibleIndicesChanged = (all, now, notNow) => {
        CfECom.logItemImpressionEvent(
            "collectionId", now,
            contentList,
        )
    }

    return (
        <View style={styles.container}>
            <RecyclerListView rowRenderer={_renderRow} dataProvider={dataProvider}
                                layoutProvider={_layoutProvider}
                                onVisibleIndicesChanged={_lonVisibleIndicesChanged}
            />
        </View>
    )

Impression listener will auto track the elements shown on the screen and log the impression events and also for the redundant scroll impressions.

For the e-commerce section, it is required to track the viewable impressions, that is, those items that have been visible in the screen for, at least, a specific time. The SDK performs this tracking semi-automatically, so requires some developer intervention. There are some functions in the API for that:

• startTrackingImpressions(containerClassname: string, itemClassname: string, searchId: string)

• stopTrackingImpressions(containerClassname: string)

• restartTrackingImpressions(containerClassname: string, searchId: string)

Whenever the user goes to a page that shows a list of e-commerce items, call startTrackingImpressions, indicating the className of the container where the items are listed. All the items must also share a common className, itemClassname, to allow the SDK to track them. searchId is an identifier returned by logSearchEvent, in case the user have performed a search in that section.

When the user performs a search in the same page, call restartTrackingImpressions indicating the new searchId

In addition, each item must contain some data, as shown in the next example:

  <div 
    data-log-id="{item_id}" 
    data-log-quantity="{item_quantity}" 
    data-log-price="{item_price}" 
    data-log-currency="{item_currency_code}" // SDK provides enum/constants CurrencyCode
    data-log-type="{item_type}" // SDK provides enum/constants ItemType
    data-log-stock-status="{item_id}" // SDK provides enum/constants StockStatus
    data-log-promo-id="{item_id}" // string 
    data-log-drug-catalog-object={JSON.stringify(drugProperties)} // SDK provides object DrugProperties
    class="{item_id}" // id/class name/container name for the card layout in your code
  >

All the fields, id, quantity, price, currency (see CurrencyCode definition), type (see ItemType definition) are mandatory.

---