@benshi.ai/js-sdk/scripts/benshi_ingest_schema.yml

Benshi SDK

# Required Schema for Ingestion
main_ingest_body:
  u_id:
    type: string
    example: testUserId
    summary: user Id in the app.
  d_id:
    type: string
    example: testDeviceId
    summary: device Id of the user.
  ip:
    type: string
    example: 0.0.0.0
    summary: ip address of the user's device.
  ol:
    type: boolean
    example: false
    summary: connectivity status of the device when event was triggered.
  up:
    type: int
    example: 2300
    summary: upload speed for device when log was triggered. In kbps.
  dn:
    type: int
    example: 2300
    summary: download speed for device when log was triggered. In kbps.
  os:
    type: string
    example: android(30) or macIntel
    summary: device, app is currently running on.
  sdk:
    type: string
    example: js/1.0.0-beta.5
    summary: version of the sdk used to log.
  ts:
    type: string
    example: 2022-04-27T10:30:06.239+02:00
    summary: timestamp when the event is triggered, RFC 3339 format.
  block:
    type: string
    example: core
    summary: content block for the event being logged. default is core.
    enum: [ core, e-commerce, e-learning, loyalty, payment ]
  type:
    type: string
    example: app
    summary: type of event being logged.
    enum: [ app, cart, cancel_checkout, checkout, deferred_payment, delivery, exam, identify, item, level, media, milestone, module, nudge_response, page, payment_method, promo, question, rate, schedule_delivery, search, track ]
  props:
    type: object
    summary: props depends on different event types based. it can contain one or more elements as a part of the property. Details for each event type are provided below.
  required:
    - u_id
    - d_id
    - ol
    - up
    - dn
    - os
    - sdk
    - ts
    - block
    - type
    - props

#--------------------------------------------------------------------------------------------------
# SDK is divided into multiple content blocks based on the app niche. This includes: core, e-commerce, e-learning, payments and loyalty. Below is the details for the events in each content block:

# Blocks and their details

blocks:
  core:
    display_name: Core
    description: "required tracking events for basic navigation"
  e-commerce:
    display_name: E-commerce
    description: "events for online marketplace platforms"
  e-learning:
    display_name: E-learning
    description: "events for online learning platforms"
  payment:
    display_name: Payment
    description: "events for in-app payments"
  loyalty:
    display_name: Loyalty
    description: "events for reward systems"


data_types:
  itemObject:
    type: object
    properties:
      id:
        type: string
        example: itemId
        summary: Id for the item.
      type:
        type: string
        example: drug
        summary: type of the item in the log.
        enum: [ drug, blood, oxygen, medical_equipment, electronics, clothing, book, misc ]
      quantity:
        type: int
        example: 1
        summary: quantity of the item, default is 1.
      price:
        type: float
        example: 12.3
        summary: total price for the item in log (unit_price * quantity).
      currency:
        type: string
        example: USD
        summary: currency of the item (ISO 4217).
      stock_status:
        type: string
        example: in_stock
        summary: to reflect the stock status of the item.
        enum: [ in_stock, low_stock, out_of_stock ]
      promo_id:
        type: string
        example: testPromoId
        summary: id for the promo if any applied on the item.
      meta:
        type: hashMap
        example: cross_matching:false
        summary: additional properties required for item with types as blood and oxygen. Also when the event type is checkout.
    required:
      - id
      - type
      - quantity
      - price
      - currency
  itemTypeObject:
    type: object
    properties:
      id:
        type: string
        example: itemId
        summary: Id for the item.
      type:
        type: string
        example: drug
        summary: type of the item in the log.
        enum: [ drug, blood, oxygen, medical_equipment, electronics, clothing, book, misc ]
      meta:
        type: hashMap
        example: cross_matching:false
        summary: additional properties required for item with types as blood and oxygen. Also when the event type is checkout.
    required:
      - id
      - type
  bloodMetaObject:
    type: object
    properties:
      cross_matching:
        type: boolean
        example: false
        summary: if the blood order also have a cross matching add-on enabled.
      temperature_strips:
        type: boolean
        example: false
        summary: if the blood order have temperature strip add-on enabled.
      extra_tests:
        type: boolean
        example: false
        summary: if the blood order have extra tests add-on enabled.
      reason:
        type: string
        example: General Surgery
        summary: reason for which blood is being purchased.
    required:
      - cross_matching
      - temperature_strips
      - extra_tests
      - reason
  oxygenMetaObject:
    type: object
    properties:
      order_type:
        type: string
        example: refill
        summary: type of the order for oxygen, refill, exchange or new cylinder.
      reason:
        type: string
        example: General Surgery
        summary: reason for which the oxygen is being purchased.
    required:
      - order_type
      - reason

#--------------------------------------------------------------------------------------------------
# Events related to content blocks

# CORE [app, page, identify, search, media, push, rate, track]
events:
  app:
    summary: To log App usage related events. [Auto Triggered].
    block: core
    props:
      type: object
      properties:
        action:
          type: string
          example: open
          summary: logs the operation on the app, if app is opened, closed or moved the background.
          enum: [ open, close, background, resume ]
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - action
  page:
    summary: To log page viewings related events. [Auto Triggered].
    block: core
    props:
      type: object
      properties:
        path:
          type: string
          example: ai.benshi.package OR benshi.ai/package
          summary: the path for page currently being shown to the user.
        title:
          type: string
          example: HomePage
          summary: page or class name for the screen currently being shown.
        duration:
          type: float
          example: 3.4
          summary: the time user spent on the screen in seconds.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - path
        - title
        - duration
  identify:
    summary: To log user auth related events. signUp, signIn and signOut.
    block: core
    props:
      type: object
      properties:
        action:
          type: string
          example: login
          summary: identify action being logged.
          enum: [ register, login, logout ]
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - action
  search:
    summary: To log search related events.
    block: core
    props:
      type: object
      properties:
        id:
          type: string
          example: testSearchId
          summary: special id associated with that search.
        query:
          type: string
          example: Hello
          summary: query the user is searching.
        results_list:
          type: itemTypeObject[]
          summary: list of ids and types for the elements shown in the search results.
        filter:
          type: hashMap
          example: maxPrice:100
          summary: hashmap object of filters applied to that search.
        page:
          type: int
          example: 1
          summary: page number for search on which user is currently at.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - query
        - results_list
        - page # defaulted to 1
  media:
    summary: To log media related events.
    block: core
    props:
      type: object
      properties:
        id:
          type: string
          example: video_testMediaId
          summary: id associated with that media concatenated with media type.
        id_source:
          type: string
          example: testMediaId
          summary: id associated with that media.
        type:
          type: string
          example: video
          summary: type of media in question.
          enum: [ video, audio, image ]
        action:
          type: string
          example: play
          summary: actions associated to the media. For image, default is play which refers to app open.
          enum: [ impression, finish, pause, play, seek ]
        time:
          type: float
          example: 1354000
          summary: time in milliseconds for the media when action is performed.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - type
        - action
        - time
  rate:
    summary: to log events related to providing rate experience for the elements in the app.
    block: core
    props:
      type: object
      properties:
        rate_value:
          type: float
          example: 4.5
          summary: rate value for the element, range is 0 to 5 (both inclusive).
        type:
          type: string
          example: order
          summary: type of the element the rate is asked for.
          enum: [ app, blood, drug, exam, media, medical_equipment, order, oxygen ]
        subject_id:
          type: string
          example: elementId
          summary: id of the element being rated.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - rate_value
        - type
        - subject_id
  track:
    summary: To log events associated to in-app dictionary.
    block: core
    props:
      type: object
      properties:
        type:
          type: string
          example: reference_guide
          summary: defaulted to reference_guide.
        action:
          type: string
          example: view_list
          summary: type of event performed.
          enum: [ view_list, view_item, external_link ]
        item_id:
          type: string
          example: elementId
          summary: id of the element being viewed.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - type
        - action
        - item_id (only when type = view_item)
  nudge_response:
    summary: To log user response to nudges i.e. push notifications, in-app messages. [Auto Triggered].
    block: core
    props:
      type: object
      properties:
        nudge_id:
          type: int
          example: nudgeId
          summary: id associated with that nudge
        type:
          type: string
          example: push_notification
          summary: type of nudge the response is for. Should be same as provided by type in the request nudge API.
        response:
          type: object
          summary: response object containing actions for the nudge shown. This can vary based on the type of the nudge shown to the user.
          properties:
            action:
              type: string
              example: open
              summary: type of action performed on the push notification
              enum: [ open, discard, block ]
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - nudge_id
        - type
        - response
  #--------------------------------------------------------------------------------------------------

  # E-COMMERCE [item, cart, checkout, delivery]

  # Below it the item object used in the following events in the e-commerce.
  
  item:
    summary: To log events related to item view, impressions or if user opened the details.
    block: e-commerce
    props:
      type: object
      properties:
        action:
          type: string
          example: view
          summary: action performed on the item.
          enum: [ add_favorite, add_reminder, detail, impression, remove_favorite, remove_reminder, remove_reminder_auto, view ]
        item:
          type: itemObject
          summary: details for the item in log.
        search_id:
          type: string
          example: testSearchId
          summary: helps with logging search if if the item is showed based on search.
        usd_rate:
          type: float
          example: 0.05
          summary: conversion value to USD for the currency provided in the item.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - action
        - item
        - usd_rate
  cart:
    summary: To log events related to cart in the app.
    block: e-commerce
    props:
      type: object
      properties:
        id:
          type: string
          example: cartId
          summary: id of the Cart on which events are being performed.
        action:
          type: string
          example: add_item
          summary: action performed on the item in cart.
          enum: [ add_item, remove_item ]
        item:
          type: itemObject
          summary: details for the item in log.
        cart_price:
          type: float
          example: 12.0
          summary: total price of the cart.
        currency:
          type: string
          example: USD
          summary: currency code for the price of the whole cart. Currency in itemObject and here should be same.
        usd_rate:
          type: float
          example: 0.05
          summary: conversion value to USD for the currency provided in the item.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - action
        - item
        - cart_price
        - currency
        - usd_rate
  checkout:
    summary: To log events related to checkout in the app.
    block: e-commerce
    props:
      type: object
      properties:
        id:
          type: string
          example: orderId
          summary: id of the order is checkout is successful else cart id if the checkout is not successful.
        cart_id:
          type: string
          example: cartId
          summary: id of the Cart on which events are being performed.
        is_successful:
          type: boolean
          example: true
          summary: reflect if the checkout is successful or not.
        items:
          type: itemObject[]
          summary: list of items in the checkout.
        cart_price:
          type: float
          example: 12.0
          summary: total price of the checkout.
        currency:
          type: string
          example: USD
          summary: currency code for the price of the checkout. Currency in all itemObject and here should be same.
        usd_rate:
          type: float
          example: 0.05
          summary: conversion value to USD for the currency provided in the item.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - is_successful
        - items
        - cart_id
        - cart_price
        - currency
        - usd_rate
  delivery:
    summary: To log events related to delivery of the order.
    block: e-commerce
    props:
      type: object
      properties:
        id:
          type: string
          example: deliveredId
          summary: Id for the delivery.
        action:
          type: string
          example: delivered
          summary: action on the delivery of the element.
          enum: [ delivered ]
        order_id:
          type: string
          example: orderId
          summary: id of the order being delivered.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - action
        - order_id
  schedule_delivery:
    summary: to log the time for which the delivery is set to be schedule.
    block: e-commerce
    props:
      type: object
      properties:
        order_id:
          type: string
          example: testOrderId
          summary: Id for the order for which the delivery is set to be scheduled.
        is_urgent:
          type: boolean
          example: false
          summary: to set if the delivery is urgent or not.
        action:
          type: string
          example: schedule
          summary: action on the schedule delivery log, new schedule or updating an existing.
          enum: [ schedule, update ]
        delivery_ts:
          type: string
          example: 2022-04-27T10:30:06.239+02:00
          summary: (RFC 3339) //currentTime for urgent, else pass the one provided to schedule.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - order_id
        - is_urgent
        - action
        - delivery_ts
  cancel_checkout:
    summary: is used to log the event when the order/cart is canceled.
    block: e-commerce
    props:
      type: object
      properties:
        id:
          type: string
          example: testId
          summary: Id for the order or cart being discarded or cancelled.
        type:
          type: string
          example: cart
          summary: type of the checkout that is being cancelled either cart or order.
          enum: [ cart, order ]
        items:
          type: itemTypeObject[]
          summary: list of items in the checkout.
        reason:
          type: string
          example: Process Too Long
          summary: reason for which the order/cart is being cancelled/discarded.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - type
        - items
        - reason
  #--------------------------------------------------------------------------------------------------

  # E-LEARNING [module, exam, question]
  module:
    summary: To log events related to module of e-learning section.
    block: e-learning
    props:
      type: object
      properties:
        id:
          type: string
          example: moduleId
          summary: id of the module.
        action:
          type: string
          example: view
          summary: action performed on the module.
          enum: [ view ]
        progress:
          type: int
          example: 75
          summary: completion progress percentage.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - action
  exam:
    summary: To log events related to exam of e-learning section.
    block: e-learning
    props:
      type: object
      properties:
        id:
          type: string
          example: examId
          summary: id of the exam.
        action:
          type: string
          example: start
          summary: action performed on the exam.
          enum: [ start, submit, result ]
        duration:
          type: int
          example: 75
          summary: time spent on the exam, in seconds.
        score:
          type: float
          example: 90.5
          summary: score achieved for the exam.
        is_passed:
          type: boolean
          example: true
          summary: if user passed the exam?
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - action
        - duration (action = submit)
        - score (action = result)
        - is_passed (action = result)
  question:
    summary: To log events related to question of e-learning section.
    block: e-learning
    props:
      type: object
      properties:
        id:
          type: string
          example: questionId
          summary: id of the question.
        exam_id:
          type: string
          example: examId
          summary: id of the exam from which the question is asked.
        action:
          type: string
          example: answer
          summary: action performed on the question.
          enum: [ answer, skip ]
        answer_id:
          type: string
          example: answerId
          summary: Id for the answer to the question.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - exam_id
        - action
        - answer_id (action = answer)
  #--------------------------------------------------------------------------------------------------

  # LOYALTY [level, milestone]
  level:
    summary: To log events related to updating user level in app.
    block: loyalty
    props:
      type: object
      properties:
        prev_level:
          type: int
          example: 65
          summary: previous/old level score of the user.
        new_level:
          type: int
          example: 100
          summary: new level score of the user.
        module_id:
          type: string
          example: moduleId
          summary: Id for the module if level update is related to e-learning.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - prev_level
        - new_level
  milestone:
    summary: To log events related to updating user milestone in app.
    block: loyalty
    props:
      type: object
      properties:
        id:
          type: string
          example: milestoneId
          summary: id for the milestone.
        action:
          type: string
          example: achieved
          summary: action regarding user milestone.
          enum: [ achieved ]
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - action
  promo:
    summary: is to log the events associated of the promo lists and promo items and when they are clicked on.
    block: loyalty
    props:
      type: object
      properties:
        id:
          type: string
          example: promoId
          summary: id for the Promo.
        action:
          type: string
          example: apply
          summary: action regarding promo event, if the event is triggered for viewing promo or applying promo on the item.
          enum: [ view, apply ]
        title:
          type: string
          example: buy 3 and get 10% off
          summary: promotional title for the promo.
        type:
          type: string
          example: add_to_cart
          summary: type of the promo that if it is related to add the product in cart or for coupon.
          enum: [ add_to_cart, coupon ]
        items:
          type: itemTypeObject[]
          summary: list of items in the promo.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - action
  #--------------------------------------------------------------------------------------------------

  # PAYMENT [deferred_payment]
  deferred_payment:
    summary: To log events related to payments in uses cases where Buy Now Pay Later is implemented.
    block: payment
    props:
      type: object
      properties:
        id:
          type: string
          example: paymentId
          summary: id for the payment.
        order_id:
          type: string
          example: orderId
          summary: id for the order payment is made for.
        action:
          type: string
          example: payment_processed
          summary: action regarding payment.
          enum: [ payment_processed ]
        type:
          type: string
          example: bank_transfer
          summary: method of payment being selected for the payment.
          enum: [ bank_transfer, cheque, cod, credit, pos, bank_card, other ]
        payment_amount:
          type: float
          example: 15
          summary: amount for which the payment is made.
        account_balance:
          type: float
          example: 130
          summary: current account balance for user after payment amount is added.
        currency:
          type: string
          example: USD
          summary: currency of the payment being made (ISO 4217).
        usd_rate:
          type: float
          example: 0.05
          summary: conversion value to USD for the currency provided in the payment.
        is_successful:
          type: boolean
          example: true
          summary: boolean to represent if the payment is successful or not.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - id
        - action
        - order_id
        - type
        - account_balance
        - payment_amount
        - currency
  payment_method:
    summary: is to log events for payments. Which method of the payment is selected for the order.
    block: payment
    props:
      type: object
      properties:
        order_id:
          type: string
          example: orderId
          summary: id for the order payment is made for.
        type:
          type: string
          example: bank_transfer
          summary: method of payment being selected for the payment.
          enum: [ bank_transfer, cheque, cod, credit, pos, bank_card, other ]
        payment_amount:
          type: float
          example: 15
          summary: amount for which the payment is made.
        currency:
          type: string
          example: USD
          summary: currency of the payment being made (ISO 4217).
        usd_rate:
          type: float
          example: 0.05
          summary: conversion value to USD for the currency provided in the payment.
        meta:
          type: hashMap
          example: appName:benshi
          summary: can use this to log extra data related to the event. This will only show on the platform and will not be processed.
      required:
        - order_id
        - type
        - payment_amount
        - currency
#--------------------------------------------------------------------------------------------------