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