plugin-hubtype-analytics: event flow

packages/botonic-core/src/models/legacy-types.ts

@@ -201,6 +201,7 @@ export interface Session {
   _shadowing?: boolean
   external?: any
   zendesk_ticket_id?: string
+  flow_thread_id?: string
 }
 
 export type InputMatcher = (input: Input) => boolean

packages/botonic-plugin-flow-builder/src/action/index.tsx

@@ -5,7 +5,8 @@
 import { FlowContent, FlowHandoff } from '../content-fields'
 import { HtNodeWithContent } from '../content-fields/hubtype-fields'
 import { getFlowBuilderPlugin } from '../helpers'
-import { EventName, trackEvent } from '../tracking'
+import BotonicPluginFlowBuilder from '../index'
+import { EventAction, getEventArgs, trackEvent } from '../tracking'
 import { createNodeFromKnowledgeBase } from './knowledge-bases'
 
 export type FlowBuilderActionProps = {
@@ -18,15 +19,7 @@
   static async botonicInit(
     request: ActionRequest
   ): Promise<FlowBuilderActionProps> {
-    const flowBuilderPlugin = getFlowBuilderPlugin(request.plugins)
-    const locale = flowBuilderPlugin.getLocale(request.session)
-
-    const targetNode = await getTargetNode(flowBuilderPlugin.cmsApi, request)
-
-    const contents = await flowBuilderPlugin.getContentsByNode(
-      targetNode,
-      locale
-    )
+    const contents = await getContents(request)
 
     const handoffContent = contents.find(
       content => content instanceof FlowHandoff
@@ -55,26 +48,64 @@
   }
 }
 
-async function getTargetNode(cmsApi: FlowBuilderApi, request: ActionRequest) {
+async function getContents(request: ActionRequest): Promise<FlowContent[]> {
+  const flowBuilderPlugin = getFlowBuilderPlugin(request.plugins)
+  const cmsApi = flowBuilderPlugin.cmsApi
+  const locale = flowBuilderPlugin.getLocale(request.session)
+  const resolvedLocale = flowBuilderPlugin.cmsApi.getResolvedLocale(locale)
+  const context = {
+    cmsApi,
+    flowBuilderPlugin,
+    request,
+    resolvedLocale,
+  }
+
   if (request.session.is_first_interaction) {
-    const startNode = cmsApi.getStartNode()
-    await trackEvent(request, EventName.botStart)
-    return startNode
+    return await flowBuilderPlugin.getStartContents(resolvedLocale)
+  }
+
+  if (request.input.payload) {
+    return await getContentsByPayload(context)
   }
-  const contentId = request.input.payload
 
-  const targetNode = contentId
-    ? cmsApi.getNodeById<HtNodeWithContent>(contentId)
+  return await getContentsByFallback(context)
+}
+
+interface FlowBuilderContext {
+  cmsApi: FlowBuilderApi
+  flowBuilderPlugin: BotonicPluginFlowBuilder
+  request: ActionRequest
+  resolvedLocale: string
+}
+
+async function getContentsByPayload({
+  cmsApi,
+  flowBuilderPlugin,
+  request,
+  resolvedLocale,
+}: FlowBuilderContext): Promise<FlowContent[]> {
+  const targetNode = request.input.payload
+    ? cmsApi.getNodeById<HtNodeWithContent>(request.input.payload)
     : undefined
 
   if (targetNode) {
-    const eventArgs = {
-      faq_name: targetNode.code,
-    }
-    await trackEvent(request, EventName.botFaq, eventArgs)
-    return targetNode
+    const eventArgs = getEventArgs(request, targetNode)
+    await trackEvent(request, EventAction.flowNode, eventArgs)
+    return await flowBuilderPlugin.getContentsByNode(targetNode, resolvedLocale)
   }
-  return await getFallbackNode(cmsApi, request)
+  return []
+}
+
+async function getContentsByFallback({
+  cmsApi,
+  flowBuilderPlugin,
+  request,
+  resolvedLocale,
+}: FlowBuilderContext): Promise<FlowContent[]> {
+  const fallbackNode = await getFallbackNode(cmsApi, request)
+  const eventArgs = getEventArgs(request, fallbackNode)
+  await trackEvent(request, EventAction.flowNode, eventArgs)
+  return await flowBuilderPlugin.getContentsByNode(fallbackNode, resolvedLocale)
 }
 
 async function getFallbackNode(cmsApi: FlowBuilderApi, request: ActionRequest) {
@@ -95,6 +126,5 @@
   const fallbackNode = cmsApi.getFallbackNode(isFirstFallbackOption)
   request.session.user.extra_data.isFirstFallbackOption = !isFirstFallbackOption
 
-  await trackEvent(request, EventName.fallback)
   return fallbackNode
 }

packages/botonic-plugin-flow-builder/src/api.ts

@@ -250,6 +250,11 @@
     }
   }
 
+  getFlowName(flowId: string): string {
+    const flow = this.flow.flows.find(flow => flow.id === flowId)
+    return flow ? flow.name : ''
+  }
+
   getResolvedLocale(locale: string): string {
     if (this.flow.locales.find(flowLocale => flowLocale === locale)) {
       return locale

packages/botonic-plugin-flow-builder/src/index.ts

@@ -1,5 +1,6 @@
 import { Plugin, PluginPreRequest, Session } from '@botonic/core'
 import { ActionRequest } from '@botonic/react'
+import { v4 as uuid } from 'uuid'
 
 import { FlowBuilderApi } from './api'
 import {
@@ -29,6 +30,7 @@ import {
   HtNodeWithContentType,
 } from './content-fields/hubtype-fields'
 import { DEFAULT_FUNCTIONS } from './functions'
+import { EventAction, getEventArgs, trackEvent } from './tracking'
 import {
   BotonicPluginFlowBuilderOptions,
   FlowBuilderJSONVersion,
@@ -48,7 +50,7 @@ export default class BotonicPluginFlowBuilder implements Plugin {
   public getLocale: (session: Session) => string
   public trackEvent?: (
     request: ActionRequest,
-    eventName: string,
+    eventAction: string,
     args?: Record<string, any>
   ) => Promise<void>
   public getKnowledgeBaseResponse?: (
@@ -140,8 +142,19 @@ export default class BotonicPluginFlowBuilder implements Plugin {
   }
 
   async getStartContents(locale: string): Promise<FlowContent[]> {
+    const resolvedLocale = this.cmsApi.getResolvedLocale(locale)
     const startNode = this.cmsApi.getStartNode()
-    return await this.getContentsByNode(startNode, locale)
+    this.currentRequest.session.flow_thread_id = uuid()
+    const eventArgs = getEventArgs(
+      this.currentRequest as unknown as ActionRequest,
+      startNode
+    )
+    await trackEvent(
+      this.currentRequest as unknown as ActionRequest,
+      EventAction.flowNode,
+      eventArgs
+    )
+    return await this.getContentsByNode(startNode, resolvedLocale)
   }
 
   async getContentsByNode(
@@ -257,6 +270,10 @@ export default class BotonicPluginFlowBuilder implements Plugin {
     const payloadParams = JSON.parse(payload.split(SEPARATOR)[1] || '{}')
     return payloadParams
   }
+
+  getFlowName(flowId: string): string {
+    return this.cmsApi.getFlowName(flowId)
+  }
 }
 
 export * from './action'

packages/botonic-plugin-flow-builder/src/tracking.ts

@@ -1,32 +1,46 @@
 import { ActionRequest } from '@botonic/react'
 
+import { HtNodeWithContent } from './content-fields/hubtype-fields'
 import { getFlowBuilderPlugin } from './helpers'
 
 export async function trackEvent(
   request: ActionRequest,
-  eventName: EventName,
+  eventAction: EventAction,
   args?: Record<string, any>
 ): Promise<void> {
   const flowBuilderPlugin = getFlowBuilderPlugin(request.plugins)
   if (flowBuilderPlugin.trackEvent) {
-    await flowBuilderPlugin.trackEvent(request, eventName, args)
+    await flowBuilderPlugin.trackEvent(request, eventAction, args)
   }
   return
 }
 
-export enum EventName {
-  botAgentRating = 'bot_agent_rating',
-  botChannelRating = 'bot_channel_rating',
-  botFaqUseful = 'bot_faq_useful',
-  botRating = 'bot_rating',
-  botFaq = 'bot_faq',
-  botStart = 'bot_start',
-  botOpen = 'bot_open',
-  botAiModel = 'bot_ai_model',
-  botAiKnowledgeBase = 'bot_ai_knowledge_base',
-  botKeywordsModel = 'bot_keywords_model',
-  fallback = 'fallback',
-  handoffOption = 'handoff_option',
-  handoffSuccess = 'handoff_success',
-  handoffFail = 'handoff_fail',
+export function getEventArgs(request: ActionRequest, node: HtNodeWithContent) {
+  const flowBuilderPlugin = getFlowBuilderPlugin(request.plugins)
+  return {
+    flowThreadId: request.session.flow_thread_id,
+    flowId: node.flow_id,
+    flowName: flowBuilderPlugin.getFlowName(node.flow_id),
+    flowNodeId: node.id,
+    flowNodeContentId: node.code,
+    flowNodeIsMeaningful: undefined, //node?.isMeaningful,
+  }
+}
+
+export enum EventAction {
+  flowNode = 'flow_node',
 }
+
+// export enum EventName {
+//   feedback = 'feedback',
+//   flow = 'botevent',
+
+//   botOpen = 'bot_open',
+//   botAiModel = 'bot_ai_model',
+//   botAiKnowledgeBase = 'bot_ai_knowledge_base',
+//   botKeywordsModel = 'bot_keywords_model',
+//   fallback = 'fallback',
+//   handoffOption = 'handoff_option',
+//   handoffSuccess = 'handoff_success',
+//   handoffFail = 'handoff_fail',
+// }

packages/botonic-plugin-flow-builder/src/types.ts

@@ -12,7 +12,7 @@ export interface BotonicPluginFlowBuilderOptions {
   getAccessToken: () => string
   trackEvent?: (
     request: ActionRequest,
-    eventName: string,
+    eventAction: string,
     args?: Record<string, any>
   ) => Promise<void>
   getKnowledgeBaseResponse?: (

packages/botonic-plugin-hubtype-analytics/README.md

@@ -32,19 +32,52 @@ By default if you do not define these functions it will use the language defined
 
 ## Use
 
-You can use it in your actions for example an event to check that a faq has been displayed in the bot:
+You can use it in your actions.
+
+- For example an event to save a feedback given by the user:
 
 ```
   const hubtypeAnalyticsPlugin = request.plugins.hubtypeAnalytics
-  const eventBotFaq = {
-    event_type: EventName.botFaq
-    event_data: { enduser_language: 'en', faq_name: 'orders_and_deliveries' }
+  const eventProps = {
+    action: FeedbackAction.case,
+    data: {
+        possibleOptions: ['*', '**', '***', '****', '*****'],
+        possibleValues: [1, 2, 3, 4, 5],
+        option: '**',
+        value: 2,
+    }
+  }
+
+  try {
+    const response = await hubtypeAnalyticsPlugin.trackEvent(request, event)
+    console.log(response)
+  } catch(error) {
+    console.error(error)
   }
+
+```
+
+- For example an event to check that a flow content has been displayed in the bot:
+  flowThreadId -> This value is managed by the plugin-flow-builder, stored in the session and updated every time the content connected to the conversation start is displayed
+
+```
+  const hubtypeAnalyticsPlugin = request.plugins.hubtypeAnalytics
+  const eventProps = {
+    action: FlowAction.flowNode,
+    data: {
+      flowThreadId: request.session.flow_thread_id,
+      flowId: '8d527e7d-ea6d-5422-b810-5b4c8be7657b',
+      flowName: 'Main',
+      flowNodeId: 'WELCOME_MSG',
+      flowNodeContentId: '607205c9-6814-45ba-9aeb-2dd08d0cb529',
+    }
+  }
+
   try {
     const response = await hubtypeAnalyticsPlugin.trackEvent(request, event)
     console.log(response)
   } catch(error) {
-    console.log(error)
+    console.error(error)
   }
 
 ```

packages/botonic-plugin-hubtype-analytics/src/event-models/ht-event-feedback.ts

@@ -1,4 +1,4 @@
-import { EventFeedback, FeedbackAction, RequestData } from '../types'
+import { EventFeedback, EventName, FeedbackAction, RequestData } from '../types'
 import { HtEvent } from './ht-event'
 
 export interface EventDataFeedback {
@@ -17,8 +17,7 @@ export class HtEventFeedback extends HtEvent {
 
   constructor(event: EventFeedback, requestData: RequestData) {
     super(event, requestData)
-    this.data = {} as EventDataFeedback
-    this.data.action = event.data.action
+    this.type = EventName.feedback
     this.data.message_generated_by = event.data.messageGeneratedBy // ?? nomes te valor quan action es message. Si es message de knowledge base => sources y chunks. Quan es un node de flow builder => content_id
     this.data.feedback_target_id = event.data.feedbackTargetId // ?? case_id, message_id, conversation_id ???, webview_name
     this.data.feedback_group_id = event.data.feedbackGroupId // ??