Use o comando init component da CLI do SDK para criar um arquivo JavaScript ou TypeScript com o framework para trabalhar com o Node.js SDK do Oracle Digital Assistant na criação de um componente personalizado. O idioma especificado quando você executou o comando init para criar o pacote do componente determina se um arquivo JavaScript ou TypeScript será criado.

bots-node-sdk init component <component name> c components

Seu componente personalizado deve exportar dois objetos:

• metadata: Fornece à habilidade as informações a seguir do componente.
  • Nome do componente
  • Propriedades suportadas
  • Ações de transição suportadas

  Para fluxos de caixas de diálogo baseados em YAML, o componente personalizado suporta as propriedades a seguir por padrão. Essas propriedades não estão disponíveis para habilidades projetadas no modo de diálogo Visual.

  • autoNumberPostbackActions: Booliano. Não é obrigatório. Quando true, os botões e as opções de lista são numerados automaticamente. O padrão é false. Consulte Numeração Automática para Canais Somente Texto em Fluxos de Caixas de Diálogo YAML.
  • insightsEndConversation: Booliano. Não é obrigatório. Quando true, a sessão interrompe a gravação da conversa para geração de relatório de informações. O padrão é false. Consulte Modelar o Fluxo de Caixas de Diálogo.
  • insightsInclude: Booliano. Não é obrigatório. Quando true, o estado é incluído no relatório de informações. O padrão é true. Consulte Modelar o Fluxo de Caixas de Diálogo.
  • translate: Booliano. Não é obrigatório. Quando true, a tradução automática é ativada para este componente. O padrão é o valor da variável de contexto autotranslation. Consulte Serviços de Tradução em Habilidades.
• invoke: Contém a lógica a ser executada. Neste método, você pode ler e gravar variáveis de contexto de habilidade, criar mensagens de conversa, definir transições de estado, fazer chamadas REST e muito mais. Normalmente, você usaria a palavra-chave async com essa função para tratar promessas. A função invoke usa o seguinte argumento:
  • context, que nomeia a referência ao objeto CustomComponentContext no Node.js SDK do Digital Assistant. Essa classe é descrita na documentação do SDK em https://oracle.github.io/bots-node-sdk/. Nas versões anteriores do SDK, o nome era conversation. Você pode usar qualquer um dos nomes.
  Observação
  
  Se você estiver usando uma biblioteca JavaScript que não suporta promessas (e, portanto, não está usando a palavra-chave async), também será possível adicionar um argumento done como um callback que o componente chama quando terminar o processamento.

Veja aqui um exemplo:

'use strict';

module.exports = {

  metadata: {
    name: 'helloWorld',
    properties: {
      human: { required: true, type: 'string' }
    },
    supportedActions: ['weekday', 'weekend']
  },

  invoke: async(context) => {
    // Retrieve the value of the 'human' component property.
    const { human } = context.properties();
    // determine date
    const now = new Date();
    const dayOfWeek = now.toLocaleDateString('en-US', { weekday: 'long' });
    const isWeekend = [0, 6].indexOf(now.getDay()) > -1;
    // Send two messages, and transition based on the day of the week
    context.reply(`Greetings ${human}`)
      .reply(`Today is ${now.toLocaleDateString()}, a ${dayOfWeek}`)
      .transition(isWeekend ? 'weekend' : 'weekday');   
  }
}

Para saber mais e explorar alguns exemplos de código, consulte Criando Componentes Personalizados na documentação do SDK do Nó de Bots.

Use diferentes combinações das funções Bots Node SDK keepTurn e transition para definir como o componente personalizado interage com um usuário e como a conversa continua depois que o componente retorna o controle de fluxo para a habilidade.

• keepTurn(boolean) especifica se a conversa deve fazer a transição para outro estado sem primeiro solicitar a entrada do usuário.

  Observe que se você quiser definir keepTurn como true, você deve chamar keepTurn depois de chamar reply, porque reply define implicitamente keepTurn como false.

• transition(action) faz com que a caixa de diálogo faça a transição para o próximo estado depois que todas as respostas, se houver, forem enviadas. O argumento opcional action nomeia essa ação (resultado) que o componente retorna.

  Se você não chamar transition(), a resposta será enviada, mas a caixa de diálogo permanecerá no estado e a entrada subsequente do usuário retornará para esse componente. Ou seja, invoke() é chamado novamente.

invoke: async (context) ==> {
   ...
   context.reply(payload);
   context.keepTurn(true);
   context.transition ("success"); 
}

Aqui estão alguns casos de uso comuns em que você usaria keepTurn e transition para controlar o fluxo de caixas de diálogo:

invoke: async (context) => {
    const listVariableName = context.properties().variableName;
    ...
    // Write list of options to a context variable
    context.variable(listVariableName, list);
   // Navigate to next state without 
   // first prompting for user interaction.
   context.keepTurn(true);
   context.transition();
 }

context.keepTurn(false);
context.transition("success");

  invoke: async (context) => {
    // Perform conversation tasks.
    const tracking_token = "a2VlcHR1cm4gZXhhbXBsZQ==";    
    const quotes = require("./json/Quotes.json");
    const quote = quotes[Math.floor(Math.random() * quotes.length)];
    
    // Check if postback action is issued. If postback action is issued, 
    // check if postback is from this component rendering. This ensures
    // that the component only responds to its own postback actions.     
    if (context.postback() && context.postback().token == tracking_token && context.postback().isNo) {
      context.keepTurn(true);
      context.transition();
    } else {
      // Show the quote of the day.
      context.reply("'" + quote.quote + "'");
      context.reply(" Quote by: " + quote.origin);
      // Create a single message with two buttons to 
      // request another quote or not.
      const mf = context.getMessageFactory();
      const message = mf.createTextMessage('Do you want another quote?')
        .addAction(mf.createPostbackAction('Yes', { isNo: false, token: tracking_token }))
        .addAction(mf.createPostbackAction('No', { isNo: true, token: tracking_token })); 
      context.reply(message);
      // Although reply() automatically sets keepTurn to false, 
      // it's good practice to explicitly set it so that it's
      // easier to see how you intend the component to behave.
      context.keepTurn(false);
    };
  }

invoke: async (context) => {

  const quotes = require("./json/Quotes.json");
  const quote = quotes[Math.floor(Math.random() * quotes.length)];
  
  // Check if postback action is issued and postback is from this component rendering. 
  // This ensures that the component only responds to its own postback actions.     
  const um = context.getUserMessage()
  if (um instanceof PostbackMessage && um.getPostback() && um.getPostback()['system.state'] === context.getRequest().state && um.getPostback().isNo) {
    context.keepTurn(true);
    context.transition();
  } else {
    // Show the quote of the day.
    context.reply(`'${quote.quote}'`);
    context.reply(`Quote by: ${quote.origin}`);
    // Create a single message with two buttons to request another quote or not.
    let actions = [];

    const mf = context.getMessageFactory();
    const message = mf.createTextMessage('Do you want another quote?')
      .addAction(mf.createPostbackAction('Yes', { isNo: false }))
      .addAction(mf.createPostbackAction('No', { isNo: true }));
    context.reply(message);
    // Although reply() automatically sets keepTurn to false, it's good practice to explicitly set it so that it's
    // easier to see how you intend the component to behave.
    context.keepTurn(false);
  }
}

Use os métodos de instância CustomComponentContext para obter o contexto da chamada, acessar e alterar variáveis e enviar os resultados de volta para o mecanismo de caixa de diálogo.

Você pode encontrar vários exemplos de código para usar esses métodos em Criando Componentes Personalizados e Mensagens de Conversa na documentação do Bots Node SDK

A documentação de referência do SDK está em https://github.com/oracle/bots-node-sdk.

Ao projetar um componente personalizado, você deve considerar se o componente será usado por uma habilidade que suporte mais de um idioma.

Se o componente personalizado tiver que suportar habilidades em vários idiomas, você precisará saber se as habilidades estão configuradas para suporte ao idioma nativo ou serviço de tradução.

Ao usar um serviço de tradução, você pode traduzir o texto da habilidade. Estas são as opções disponíveis:

• Defina a propriedade translate no estado do componente personalizado como verdadeira para traduzir a resposta do componente, conforme descrito em Enviar Respostas Diretamente ao Serviço de Tradução.

• Envie dados brutos de volta para a habilidade em variáveis e use os valores das variáveis em um componente do sistema que compõe a saída. Defina a propriedade translate desse componente como verdadeira. Consulte Usar um Componente do Sistema para Passar a Mensagem ao Serviço de Tradução.

• Envie dados brutos de volta para a habilidade em variáveis e use os valores das variáveis em um componente do sistema que use a chave do pacote de recursos para o idioma. Consulte Usar um Componente de Sistema para Fazer Referência a um Pacote de Recursos.

Para habilidades de idioma nativo, você tem estas opções:

• Informe os dados de volta à habilidade em variáveis e, em seguida, gere o texto de um componente do sistema informando os valores das variáveis para uma chave do pacote de recursos, conforme descrito em Usar um Componente do Sistema para Fazer Referência a um Pacote de Recursos. Com essa opção, o componente personalizado deve ter propriedades de metadados para que a habilidade informe os nomes das variáveis nas quais armazenar os dados.

• Use o pacote de recursos do componente personalizado para compor a resposta do componente personalizado, conforme descrito em Reference Resource Bundles from the Custom Component. Você usa o método conversation.translate() para obter a string do pacote de recursos a ser usada para sua chamada para context.reply(). Esta opção só é válida para definições de pacotes de recursos que usam parâmetros posicionais (numerados). Não funciona para parâmetros nomeados. Com essa opção, o componente personalizado deve ter uma propriedade de metadados para o nome da chave do pacote de recursos, e os parâmetros da chave do pacote de recursos nomeado devem corresponder aos usados na chamada para context.reply().

Veja um exemplo de como usar o pacote de recursos do componente personalizado. Neste exemplo, fmTemplate seria definido como algo como ${rb('date.dayOfWeekMessage', 'lundi', '19 juillet 2021')}.

'use strict';

var IntlPolyfill    = require('intl');
Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;

module.exports = {
  metadata: () => ({
    name: 'Date.DayOfWeek',
    properties: {
      rbKey:   { required: true,  type: 'string'    }
    },
    supportedActions: []
  }),
  invoke: (context, done) => {
    const { rbKey } = context.properties();
    if (!rbKey || rbKey.startsWith('${')){
      context.transition();
            done(new Error('The state is missing the rbKey property or it uses an invalid expression to pass the value.'));
    }
    //detect user locale. If not set, define a default
    const locale  = context.getVariable('profile.locale') ? 
      context.getVariable('profile.locale') : 'en-AU';  
    const jsLocale     = locale.replace('_','-');
    //when profile languageTag is set, use it. If not, use profile.locale
    const languageTag = context.getVariable('profile.languageTag')?
                      context.getVariable('profile.languageTag') : jslocale;
   /* =============================================================
      Determine the current date in local format and 
      the day name for the locale
      ============================================================= */
    var now          = new Date();
    var dayTemplate  = new Intl.DateTimeFormat(languageTag,
      { weekday: 'long' });
    var dayOfWeek    = dayTemplate.format(now);
    var dateTemplate = new Intl.DateTimeFormat(languageTag, 
      { year: 'numeric', month: 'long', day: 'numeric'});
    var dateToday    = dateTemplate.format(now);

   /* =============================================================
      Use the context.translate() method to create the ${Freemarker} 
      template that's evaluated when the reply() is flushed to the 
      client.
      ============================================================= */
    const fmTemplate = context.translate(rbKey, dateToday, dayOfWeek );

    context.reply(fmTemplate)
                .transition()
                .logger().info('INFO : Generated FreeMarker => ' 
                + fmTemplate);
    done();  
  }
};

Em uma conversa com assistente digital, um usuário pode interromper um fluxo de conversa alterando o assunto. Por exemplo, se um usuário iniciar um fluxo para fazer uma compra, ele poderá interromper esse fluxo para perguntar quanto ele tem de crédito em um cartão-presente. Nós chamamos isso de não sequenciadores. Para permitir que o assistente digital identifique e manipule não sequenciadores, chame o método context.invalidInput(payload) quando uma resposta do usuário não for compreendida no contexto do componente.

Em uma conversa digital, o runtime determina se uma entrada inválida é um não sequenciador, procurando correspondências de resposta em todas as habilidades. Se encontrar correspondências, ele redirecionará o fluxo. Caso contrário, ele exibirá a mensagem, se fornecida, solicitará ao usuário a entrada e, em seguida, executará o componente novamente. A nova entrada é transmitida ao componente na propriedade text.

Em uma conversa de habilidade stand-alone, o runtime exibe a mensagem, se fornecida, solicita ao usuário a entrada e, em seguida, executa o componente novamente. A nova entrada é transmitida ao componente na propriedade text.

Esse código de exemplo chama context.invalidInput(payload), sempre que a entrada não é convertida em um número.

"use strict"
 
module.exports = {
 
    metadata: () => ({
        "name": "AgeChecker",
        "properties": {
            "minAge": { "type": "integer", "required": true }
        },
        "supportedActions": [
            "allow",
            "block",
            "unsupportedPayload"
        ]
    }),
 
    invoke: (context, done) => {
        // Parse a number out of the incoming message
        const text = context.text();
        var age = 0;
        if (text){
          const matches = text.match(/\d+/);
          if (matches) {
              age = matches[0];
          } else {
              context.invalidUserInput("Age input not understood. Please try again");
              done();
              return;
          }
        } else {
          context.transition('unsupportedPayload");
          done();
          return;
        }
 
        context.logger().info('AgeChecker: using age=' + age);
 
        // Set action based on age check
        let minAge = context.properties().minAge || 18;
        context.transition( age >= minAge ? 'allow' : 'block' );
 
        done();
    }
};

Este é um exemplo de como um assistente digital trata uma entrada inválida no runtime. Para a primeira resposta de idade (twentyfive), não há correspondência em habilidade alguma registrada no assistente digital; dessa forma, a conversa exibe a mensagem context.invalidUserInput especificada. Na segunda resposta de idade (send money), o assistente digital encontra uma correspondência e pergunta se ele deve redirecionar para esse fluxo.

Chame context.invalidInput() ou context.transition(). Se você chamar as duas operações, certifique-se de que a variável system.invalidUserInput ainda esteja definida se qualquer mensagem adicional for enviada. Observe também que os componentes de entrada do usuário (como os componentes Resposta Comum e Resolver Entidades) redefinem system.invalidUserInput.

Digamos, por exemplo, que modificamos o componente AgeChecker conforme mostrado a seguir e chamamos context.transition() após context.invalidInput().

if (matches) {  age = matches[0]; } else { 
      context.invalidUserInput("Age input not understood. Please try again"); 
      context.transition("invalid"); 
      context.keepTurn(true);
      done();
      return;
}

Nesse caso, o fluxo de dados precisa fazer uma nova transição para askage para que o usuário receba duas mensagens de saída – "Entrada de idade não compreendida. Tente novamente" seguido por "Quantos anos você tem?". Veja como isso pode ser tratado em um fluxo de caixas de diálogo no modo YAML.

  askage:
    component: "System.Output"
    properties:
      text: "How old are you?"
    transitions:
      next: "checkage"
  checkage:
    component: "AgeChecker"
    properties:
      minAge: 18
    transitions:
      actions:
        allow: "crust"
        block: "underage"
        invalid: "askage"