@yoctol/analytics

yoctol-analytics

Module	Description
yoctol-analytics	Yoctol's analytics module, which supports chatbot message and Facebook post analytics.
yoctol-analytics-sdk	Analytics SDK for chatbot to track chat logs.

Using this analytics module, you can get a analytics table like this.

Simple Guide

Install

$ npm install @yoctol/analytics

$ npm install @yoctol/analytics-sdk

Usage

First install sdk and log data into bot db using monk or knex client. Then analytics can generate corresponding files based on report setting.

• sdk default mongo collection name: interactionLogs
• sdk default knex table name: interaction_logs

Sample Report Setting

• switchToHumanPayloads only supported in messenger platform.

reporterSettings: [
      {
        title: '總覽',
        className: 'Statistics',
        config: {
          switchToHumanPayloads: {
            postback: ['__SWITCH_TO_HUMAN__'],
            quick_reply: ['__SWITCH_TO_HUMAN__', '__INTENT_轉接專人__'],
          },
        },
      },
      {
        title: '互動次數（每日）',
        className: 'Histogram',
        config: {
          switchToHumanPayloads: {
            postback: ['__SWITCH_TO_HUMAN__'],
            quick_reply: ['__SWITCH_TO_HUMAN__', '__INTENT_轉接專人__'],
          },
          periodMinutes: 24 * 60,
        },
      },
      {
        title: '互動次數（每小時）',
        className: 'Histogram',
        config: {
          switchToHumanPayloads: {
            postback: ['__SWITCH_TO_HUMAN__'],
            quick_reply: ['__SWITCH_TO_HUMAN__', '__INTENT_轉接專人__'],
          },
          periodMinutes: 60,
        },
      },
      {
        title: '按鈕觸發次數',
        className: 'Postback',
        config: {},
      },
      {
        title: '訊息記錄',
        className: 'Log',
        config: {},
      },
    ],
}

SDK

const logger = new AnalyticsLogger({ knexClient, monkClient, logDbName });

logger.insertLog({ id, platform, platformChannelId, direction, event, triggers })

AnalyticsLogger Input

Parameter	Description
id	analytics request id
platform	platform name, available values 'line', 'messenger', 'universal'
platformChannelId	Bot binding channel (for LINE)/page id (for Facebook)
direction	user message (incoming) or bot message (outgoing), available values: 'incoming', 'outgoing'
event	raw event from the specified platform.
triggers	trigger context from NLU triggers (including intent-entity model, regular expression and keywords), see here
kuratorProjectId	optional (special case for Fubon)

triggers

triggers: trigger | [trigger] // single object or array of objects

trigger: {
   intentId: "NLU INTENT ID",
   intentName: "NLU INTENT NAME",
   entityId: "NLU ENTITY ID",
   entityName: "NLU ENTITY NAME",
   entityValueId: "NLU ENTITY VALUE ID",
   entityValueName: "NLU ENTITY VALUE NAME",
   regexp: "^REGEXP$/g",
   keywords: ["KEYWORD1", "KEYWORD2", "KEYWORD3"],
   displayName: "ACTION NAME WHEN TRIGGERED BY PAYLOAD OR UNKNOWN",
   actionId: "ACTION ID WHEN TRIGGERED BY PAYLOAD OR UNKNOWN"
   isFallback: Boolean // unknown or not
}

Generic Message

Before the analytics pipeline, we use an adapter to transform platform format message to a generic format:

{
  id: STRING (uuid)
  direction: STRING ('incoming' | 'outgoing')
  type: STRING ('text' | 'quick_reply' | 'button' | ...)
  platform: STRING ('messenger' | 'line' | 'universal' | ...)
  text: STRING
  postback: STRING
  context: {
      trigger: JSON
      ... extendibleFields
  },
  raw: JSON
  ... extendibleFields
}

Architecture

We arrange analytics module for yoctol chatbot in a pipeline structure:

Raw message logs from database (MongoDb/MSSQL) passes through the whole component and aggregates to analytics tables (in .xlsx/.csv/.json format)

Streamed Processing

For memory saving issue, this analytics module partially fetch messages from databases, and then aggregate each chunk into the final result table(s).

I18n

I18n tables are in src/locale/{bot, analytics}/{en, zh}.json.

Use functions in src/i18n.js to implement i18n in tables:

• setLocale(locale): set locale to be 'zh' or 'en'
• translate(key, params, namespace = 'analytics'): use the template of key from namespace to generate a i18n string with parameters params

e.g.

import { setLocale, translate as t } from '../i18n';

setLocale('zh');

const intentName = '表示開心';

const title = t('title_entities_of_intent', {
  intentName,
});

console.log(title);

// output: 表示開心 的抽換詞類統計

Settings

Initialization

new Analytics({ ... options });

Parameters

Parameter	Description
kuratorProjectId	kurator project id for filtering specific project.
platformChannelId	LINE channel id or messenger recipient id for filtering specific channel.
mongoUrl	URL of mongoDB.
mongoClient	mongoDB client compatible with native basic APIs, in here we use monk.
knexClient	knex client for Relational DBs, we have only tested MSSQL.
collectionNames	collection/table names of DB for analytics. See here
platform	messaging platform. Now support:　‘line‘, ‘messenger‘, 'generic'
startDate	starting date
endDate	ending date
analyzerSettings	settings for analyzers, see here.
reporterSettings	settings for reporters, see here.
locale	Specify locale for analytics. Now support: en, zh
customAdapter	Adapter for generic message analytics.
stream	stream processing mode (boolean)
chunkSize	chunk size for stream, enabled only when stream is true
definition	kurator definition for retrieving action names.

collectionNames

default:

{
  logsName: 'interactionLogs',
  sessionsName: 'sessions',
}

analyzerSettings

e.g.

{
  filteredUserIds: [],
  conversationSplitMinutes: 15,
}

reporterSettings

e.g.

[
  {
    title: 'title_overview',
      className: 'Statistics',
        config: {
        switchToHumanPayloads: {
          postback: ['__SWITCH_TO_HUMAN__'],
          quick_reply: ['__SWITCH_TO_HUMAN__', '__INTENT_轉接專人__'],
        },
      },
    },
]

Components from Analytics Architecture

Adapter

An adapter transforms raw chatbots log into generic message format for later processing.

Analyzer

An analyzer is a auxiliary data processor for reporters. It consumes message logs and produces specific type of structured data.

The following are structures of each analyzer's output data.

IntentAnalyzer

  Output: Map of Intent

  Intent: {
    id: Number,
    count: Number,
    entities: Map of Entity,
  }

  Entity: {
    id: Number,
    count: Number,
    entityValues: Map of EntityValues,
  }

  EntityValue: {
    id: Number,
    count: Number,
  }

e.g.

{
  'intentName1': {
    id: 1,
    count: 123,
    entities: {
      'entityName1': {
        id: 1,
        count: 34,
        entityValues: {
          'entityValueName1': {
            id: 1,
            count: 16
          },
          'entityValueName2': {
            id: 2,
            count: 12
          },
        },
      },
      'entityName2': {
        id: 2,
        count: 47,
        entityValues: {}
      }
    }
  },
  'intentName2': {
    id: 2,
    count: 456,
    entities: {},
  },
}

UserAnalyzer

UserAnalyzer produces a list of user ids.

Output: List of Strings

UserConversationAnalyzer

UserConversationAnalyzer produces logs grouped by conversations, and conversations grouped by users.

Output: List of UserConversation

UserConversation: {
  id: String,
  conversations: List of Conversation,
  conversationtCount: Number,
}

Conversation: List of ProcessedLog // logs processed by adapaters

e.g.

[
  {
    id: 'userId1',
    conversations: [
      [ {...rawLog1 }, { ...rawLog2 }, { ...rawLog3 }],
      [ {...rawLog4 }, { ...rawLog5 }, { ...rawLog6 }],
    ],
    conversationsCount: 2,
  },
  ...
]

Reporter

A reporter aggregates structured data tables

Here's the list of all reporters and their brief descriptions

ActionReporter / PostbackReporter / QuickReplyReporter / ReferralReporter

These 4 reporters simply give (field value, count) pairs for specific field in chat logs.

HistogramReporter

HistogramReporter is to produce statistics based on time duration (daily, hourly)

example config:

{
    switchToHumanPayloads: {
      postback: ['__SWITCH_TO_HUMAN__'],
      quick_reply: ['__SWITCH_TO_HUMAN__', '__INTENT_轉接專人__'],
    },
    periodMinutes: 24 * 60,
  }

IntentReporter / IntentEntityReporter

These 2 reporters produces intent stats and entity stats for each intents.

UnknownReporter

Unknown reporter shows all messages with unknown intent.

LogReporter

LogReporter produces raw logs

StatisticsReporter

StatisticsReporter produces the general statistics table.

example config:

    switchToHumanPayloads: {
      postback: ['__SWITCH_TO_HUMAN__'],
      quick_reply: ['__SWITCH_TO_HUMAN__', '__INTENT_轉接專人__'],
    },
  }

Writer

A writer writes JSON produces by reporters into files. Currently there are 3 Writers for different formats:

ExcelWriter

CsvWriter

JsonWriter