@benshi.ai/js-sdk/src/__tests__/ingest_schema.yml

Benshi SDK

# Required Schema for Ingestion
properties:
  u_id:
    type: string
    examples: [testUserId]
    description: user Id in the app
  d_id:
    type: string
    examples: [testDeviceId]
    description: device Id of the user
  ip:
    type: string
    examples: [0.0.0.0]
    description: ip address of the user's device
  ol:
    type: boolean
    examples: [false]
    description: connectivity status of the device when event was triggered.
  up:
    type: integer
    examples: [2300]
    description: upload speed for device when log was triggered. In kbps
  dn:
    type: integer
    examples: [2300]
    description: download speed for device when log was triggered. In kbps
  os:
    type: string
    examples: [android(30), macIntel]
    description: device, app is currently running on.
  sdk:
    type: string
    examples: [js/1.0.0-beta.5]
    description: version of the sdk used to log
  ts:
    type: string
    examples: [2022-04-27T10:30:06.239+02:00]
    description: timestamp when the event is triggered, RFC 3339 format
  block:
    type: string
    examples: [core]
    description: content block for the event being logged. default is core
    enum: [ core, e-commerce, e-learning, loyalty, payment ]
  type:
    type: string
    examples: [app]
    description: type of event being logged
    enum: [ app, cart, checkout, deferred_payment, exam, identify, item, level, media, milestone, module, nudge_response, page, question, search, track, delivery]
  props:
    type: object
    oneOf: [
      {"$ref":"#/$defs/app"},
      {"$ref":"#/$defs/page"},
      {"$ref":"#/$defs/identify"},
      {"$ref":"#/$defs/search"},
      {"$ref":"#/$defs/media"},
      {"$ref":"#/$defs/track"},
      {"$ref":"#/$defs/nudge_response"},
      {"$ref":"#/$defs/item"},
      {"$ref":"#/$defs/cart"},
      {"$ref":"#/$defs/checkout"},
      {"$ref":"#/$defs/delivery"},
      {"$ref":"#/$defs/module"},
      {"$ref":"#/$defs/exam"},
      {"$ref":"#/$defs/question"},
      {"$ref":"#/$defs/level"},
      {"$ref":"#/$defs/milestone"},
      {"$ref":"#/$defs/deferred_payment"}
    ]
    description: 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, payment and loyalty. Below is the details for the events in each content block:

# Blocks and their details


$defs:
  blocks:
    core:
      display_name: Core
      description: "required tracking events for basic navigation"
      logs:
        type: string
        enum: [app, page, identify, search, media, track, nudge_response]
    e-commerce:
      display_name: E-commerce
      description: "events for online marketplace platforms"
      logs:
        type: string
        enum: [item, cart, checkout, delivery]
    e-learning:
      display_name: E-learning
      description: "events for online learning platforms"
      logs: 
        type: string
        enum: [module, exam, question]
    payment:
      display_name: Payment
      description: "required tracking events for basic navigation"
      logs:
        type: string
        enum: [deferred_payment]
    loyalty:
      display_name: Loyalty
      description: "events for reward systems"
      logs:
        type: string
        enum: [level, milestone]
  itemObject:
    type: object
    properties:
      id:
        type: string
        examples: [itemId]
        description: Id for the item
      type:
        type: string
        examples: [drug]
        description: type of the item in the log
        enum: [ drug, electronics, clothing, book, misc ]
      quantity:
        type: integer
        examples: [1]
        description: quantity of the item, default is 1
      price:
        type: number
        examples: [12.3]
        description: total price for the item in log (unit_price * quantity)
      currency:
        type: string
        examples: [USD]
        description: currency of the item (ISO 4217)
      stock_status:
        type: string
        examples: [in_stock]
        description: to reflect the stock status of the item
        enum: [ in_stock, low_stock, out_of_stock ]
      promo_id:
        type: string
        examples: [testPromoId]
        description: id for the promo if any applied on the item
    required:
      - id
      - type
      - quantity
      - price
      - currency
  app:
    description: To log App usage related events. [Auto Triggered]
    type: object
    properties:
      action:
        type: string
        examples: [open]
        description: logs the operation on the app, if app is opened, closed or moved the background.
        enum: [ open, close, background, resume ]
      meta:
        type: object
        examples: [appName:benshi]
        description: 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:
    description: To log page viewings related events. [Auto Triggered]
    type: object
    properties:
      path:
        type: string
        examples: [ai.benshi.package, benshi.ai/package]
        description: the path for page currently being shown to the user.
      title:
        type: string
        examples: [HomePage]
        description: page or class name for the screen currently being shown.
      duration:
        type: number
        examples: [3.4]
        description: the time user spent on the screen in seconds.
      meta:
        type: object
        examples: [appName:benshi]
        description: 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

  identify:
    description: To log user auth related events. signUp, signIn and signOut
    type: object
    properties:
      action:
        type: string
        examples: [login]
        description: identify action being logged.
        enum: [ register, login, logout ]
      meta:
        type: object
        examples: [appName:benshi]
        description: 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:
    description: To log search related events
    type: object
    properties:
      id:
        type: string
        examples: [testSearchId]
        description: special id associated with that search
      query:
        type: string
        examples: [Hello]
        description: query the user is searching
      result_ids_list:
        type: array
        items:
          type: string
        examples: [ [resultId1, resultId2] ]
        description: list iof id for the elements shown in the search results.
      filter:
        type: object
        examples: [maxPrice:100]
        description: object object of filters applied to that search
      page:
        type: integer
        examples: [1]
        description: page number for search on which user is currently at.
      meta:
        type: object
        examples: [appName:benshi]
        description: 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_ids
      - page # defaulted to 1
  media:
    description: To log media related events
    type: object
    properties:
      id:
        type: string
        examples: [video_testMediaId]
        description: id associated with that media concatenated with media type
      id_source:
        type: string
        examples: [testMediaId]
        description: id associated with that media
      type:
        type: string
        examples: [video]
        description: type of media in question
        enum: [ video, audio, image ]
      action:
        type: string
        examples: [play]
        description: actions associated to the media. For image, default is play which refers to app open.
        enum: [ play, pause, seek, finish ]
      time:
        type: number
        examples: [1354000]
        description: time in milliseconds for the media when action is performed
      meta:
        type: object
        examples: ["appName:benshi"]
        description: 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
      - id_source
      - type
      - action
      - time
  track:
    description: To log events associated to in-app dictionary.
    type: object
    properties:
      type:
        type: string
        examples: [reference_guide]
        description: defaulted to reference_guide
      action:
        type: string
        examples: [view_list]
        description: type of event performed
        enum: [ view_list, view_item, external_link ]
      item_id:
        type: string
        examples: [elementId]
        description: id of the element being viewed
      meta:
        type: object
        examples: [appName:benshi]
        description: 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
  nudge_response:
    description: To log user response to nudges i.e. push notifications, in-app messages. [Auto Triggered]
    type: object
    properties:
      nudge_id:
        type: integer
        examples: [nudgeId]
        description: id associated with that nudge
      type:
        type: string
        examples: [push_notification]
        description: type of nudge the response is for. Should be same as provided by type in the request nudge API.
      response:
        type: object
        description: 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
            examples: [open]
            description: type of action performed on the push notification
            enum: [ open, discard, block ]
      meta:
        type: object
        examples: [appName:benshi]
        description: 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:
    description: To log events related to item view, impressions or if user opened the details.
    type: object
    properties:
      action:
        type: string
        examples: [view]
        description: action performed on the item
        enum: [ impression, view, detail ]
      item:
        $ref: "#/$defs/itemObject"
        description: details for the item in log
      search_id:
        type: string
        examples: [testSearchId]
        description: helps with logging search if if the item is showed based on search.
      usd_rate:
        type: number
        examples: [0.05]
        description: conversion value to USD for the currency provided in the item
      meta:
        type: object
        examples: [appName:benshi]
        description: 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:
    description: To log events related to cart in the app.
    type: object
    properties:
      id:
        type: string
        examples: [cartId]
        description: id of the Cart on which events are being performed
      action:
        type: string
        examples: [add_item]
        description: action performed on the item in cart
        enum: [ add_item, remove_item ]
      item:
        $ref: "#/$defs/itemObject"
        description: details for the item in log
      cart_price:
        type: number
        examples: [12.0]
        description: total price of the cart
      currency:
        type: string
        examples: [USD]
        description: currency code for the price of the whole cart. Currency in itemObject and here should be same.
      usd_rate:
        type: number
        examples: [0.05]
        description: conversion value to USD for the currency provided in the item
      meta:
        type: object
        examples: [appName:benshi]
        description: 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:
    description: To log events related to checkout in the app.
    type: object
    properties:
      id:
        type: string
        examples: [orderId]
        description: id of the order is checkout is successful else cart id if the checkout is not successful
      cart_id:
        type: string
        examples: cartId
        description: id of the Cart on which events are being performed
      is_successful:
        type: boolean
        examples: [true]
        description: reflect if the checkout is successful or not
      items:
        type: array
        items:
          $ref: "#/$defs/itemObject"
        description: list of items in the checkout
      cart_price:
        type: number
        examples: [12.0]
        description: total price of the checkout
      currency:
        type: string
        examples: [USD]
        description: currency code for the price of the checkout. Currency in all itemObject and here should be same.
      usd_rate:
        type: number
        examples: [0.05]
        description: conversion value to USD for the currency provided in the item
      meta:
        type: object
        examples: [appName:benshi]
        description: 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_price
      - currency
      - usd_rate
  delivery:
    description: To log events related to delivery of the order
    type: object
    properties:
      id:
        type: string
        examples: deliveredId
        description: Id for the delivery
      action:
        type: string
        examples: delivered
        description: action on the delivery of the element
        enum: [ delivered ]
      order_id:
        type: string
        examples: orderId
        description: id of the order being delivered
      meta:
        type: object
        examples: [appName:benshi]
        description: 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
  #--------------------------------------------------------------------------------------------------

  # E-LEARNING [module, exam, question]
  module:
    description: To log events related to module of e-learning section
    type: object
    properties:
      id:
        type: string
        examples: [moduleId]
        description: id of the module
      action:
        type: string
        examples: [view]
        description: action performed on the module
        enum: [ view ]
      progress:
        type: integer
        examples: [75]
        description: completion progress percentage
      meta:
        type: object
        examples: [appName:benshi]
        description: 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:
    description: To log events related to exam of e-learning section
    type: object
    properties:
      id:
        type: string
        examples: [examId]
        description: id of the exam
      action:
        type: string
        examples: [start]
        description: action performed on the exam
        enum: [ start, submit, result ]
      duration:
        type: integer
        examples: [75]
        description: time spent on the exam, in seconds
      score:
        type: number
        examples: [90.5]
        description: score achieved for the exam
      is_passed:
        type: boolean
        examples: [true]
        description: if user passed the exam?
      meta:
        type: object
        examples: [appName:benshi]
        description: 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
      - score
      - is_passed
  question:
    description: To log events related to question of e-learning section
    type: object
    properties:
      id:
        type: string
        examples: [questionId]
        description: id of the question
      exam_id:
        type: string
        examples: [examId]
        description: id of the exam from which the question is asked
      action:
        type: string
        examples: [answer]
        description: action performed on the question
        enum: [ answer, skip ]
      answer_id:
        type: string
        examples: [answerId]
        description: Id for the answer to the question
      meta:
        type: object
        examples: [appName:benshi]
        description: 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
  #--------------------------------------------------------------------------------------------------

  # LOYALTY [level, milestone]
  level:
    description: To log events related to updating user level in app
    type: object
    properties:
      prev_level:
        type: integer
        examples: [65]
        description: previous/old level score of the user
      new_level:
        type: integer
        examples: [100]
        description: new level score of the user
      module_id:
        type: string
        examples: [moduleId]
        description: Id for the module if level update is related to e-learning
      meta:
        type: object
        examples: [appName:benshi]
        description: 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:
    description: To log events related to updating user milestone in app
    type: object
    properties:
      id:
        type: string
        examples: [milestoneId]
        description: id for the milestone
      action:
        type: string
        examples: [achieved]
        description: action regarding user milestone
        enum: [ achieved ]
      meta:
        type: object
        examples: [appName:benshi]
        description: 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:
    description: To log events related to payments in uses cases where Buy Now Pay Later is implemented
    type: object
    properties:
      id:
        type: string
        examples: [paymentId]
        description: id for the payment
      order_id:
        type: string
        examples: [orderId]
        description: id for the order payment is made for
      action:
        type: string
        examples: [payment_processed]
        description: action regarding payment
        enum: [ payment_processed ]
      payment_amount:
        type: number
        examples: [15]
        description: amount for which the payment is made
      account_balance:
        type: number
        examples: [130]
        description: current account balance for user after payment amount is added
      currency:
        type: string
        examples: [USD]
        description: currency of the payment being made (ISO 4217)
      usd_rate:
        type: number
        examples: [0.05]
        description: conversion value to USD for the currency provided in the payment
      is_successful:
        type: boolean
        examples: [true]
        description: boolean to represent if the payment is successful or not
      meta:
        type: object
        examples: [appName:benshi]
        description: 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