Utilisez la commande init component de l'interface de ligne de commande du kit SDK afin de créer un fichier JavaScript ou TypeScript avec la structure permettant d'utiliser le kit SDK Node.js Oracle Digital Assistant pour écrire un composant personnalisé. Le langage indiqué lors de l'exécution de la commande init pour créer le package de composants détermine si un fichier JavaScript ou TypeScript est créé.

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

Votre composant personnalisé doit exporter deux objets :

• metadata : fournit à la brique les informations suivantes sur le composant.
  • Nom de composant
  • Propriétés prises en charge
  • Actions de transition prises en charge

  Pour les flux de dialogue basés sur YAML, le composant personnalisé prend en charge les propriétés suivantes par défaut. Ces propriétés ne sont pas disponibles pour les briques conçues en mode de dialogue Visual.

  • autoNumberPostbackActions : booléen. Non obligatoire. Lorsque la valeur true est définie, les boutons et les options de liste sont numérotés automatiquement. La valeur par défaut est false. Reportez-vous à Numérotation automatique pour les canaux de texte uniquement dans les flux de dialogue YAML.
  • insightsEndConversation : booléen. Non obligatoire. Lorsque la valeur true est définie, la session arrête l'enregistrement de la conversation pour la génération de rapports d'analyse. La valeur par défaut est false. Reportez-vous à Modélisation du flux de dialogue.
  • insightsInclude : booléen. Non obligatoire. Lorsque la valeur true est définie, l'état est inclus dans la génération de rapports d'analyse. La valeur par défaut est true. Reportez-vous à Modélisation du flux de dialogue.
  • translate : booléen. Non obligatoire. Lorsque la valeur true est définie, la traduction automatique est activée pour ce composant. La valeur par défaut est celle de la variable de contexte autotranslation. Reportez-vous à Services de traduction dans les briques.
• invoke : contient la logique à exécuter. Avec cette méthode, vous pouvez lire et écrire des variables de contexte de brique, créer des messages de conversation, définir des transitions d'état, effectuer des appels REST, etc. En général, vous utilisez le mot-clé async avec cette fonction pour gérer les promesses. La fonction invoke accepte l'argument suivant :
  • context, qui nomme la référence à l'objet CustomComponentContext dans le kit SDK Node.js Digital Assistant. Cette classe est décrite dans la documentation du kit SDK disponible à l'adresse https://oracle.github.io/bots-node-sdk/. Dans les versions antérieures du kit SDK, son nom était conversation. Vous pouvez utiliser l'un ou l'autre des noms.
  Remarque
  
  Si vous utilisez une bibliothèque JavaScript qui ne prend pas en charge les promesses (et n'utilise donc pas le mot-clé async), il est également possible d'ajouter un argument done en tant que rappel que le composant appelle une fois le traitement terminé.

Voici un exemple :

'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');   
  }
}

Pour en savoir plus et découvrir quelques exemples de code, reportez-vous à Ecriture de composants personnalisés dans la documentation du kit SDK Bots Node.

Utilisez différentes combinaisons des fonctions keepTurn et transition du kit SDK Bots Node pour définir comment le composant personnalisé interagit avec l'utilisateur et comment la conversation se poursuit après que le composant renvoie le contrôle du flux vers la brique.

• keepTurn(boolean) indique si la conversation doit passer à un autre état sans inviter d'abord l'utilisateur à entrer du texte.

  Si vous voulez définir keepTurn sur True, vous devez appeler keepTurn après avoir appelé reply car reply définit implicitement keepTurn sur false.

• transition(action) fait passer le dialogue à l'état suivant une fois que toutes les réponses, le cas échéant, ont été envoyées. L'argument action facultatif nomme l'action (résultat) renvoyée par le composant.

  Si vous n'appelez pas transition(), la réponse est envoyée mais la boîte de dialogue reste dans l'état et l'entrée utilisateur suivante revient à ce composant. Autrement dit, invoke() est appelé à nouveau.

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

Voici quelques cas d'emploi courants dans lesquels vous pouvez utiliser keepTurn et transition pour contrôler le flux de dialogue :

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);
  }
}

Les méthodes d'instance CustomComponentContext permettent d'obtenir le contexte de l'appel, de modifier les variables et d'y accéder, et de renvoyer les résultats au moteur de dialogue.

Vous trouverez plusieurs exemples de code pour l'utilisation de ces méthodes dans Ecriture de composants personnalisés et Messagerie de conversation dans la documentation du kit SDK Bots Node.

La documentation de référence du kit SDK est disponible à l'adresse suivante : https://github.com/oracle/bots-node-sdk.

Lorsque vous concevez un composant personnalisé, vous devez déterminer si ce composant sera utilisé par une brique qui prend en charge plusieurs langues.

Si le composant personnalisé doit prendre en charge les briques multilingues, vous devez savoir si les briques sont configurées pour la prise en charge des langues natives ou le service de traduction.

Lorsque vous utilisez un service de traduction, vous pouvez traduire le texte de la brique. Vous disposez des options suivantes :

• Définissez la propriété translate dans l'état du composant personnalisé sur True pour traduire la réponse du composant, comme décrit dans Envoyer des réponses directement au service de traduction.

• Renvoyez les données brutes à la brique dans les variables et utilisez les valeurs des variables dans un composant système qui compose la sortie. Définissez la propriété translate de ce composant sur True. Reportez-vous à Utilisation d'un composant système pour transmettre le message au service de traduction.

• Renvoyez les données brutes à la brique dans les variables et utilisez les valeurs des variables dans un composant système qui utilise la clé de regroupement de ressources pour la langue. Reportez-vous à Utiliser un composant système pour référencer un groupe de ressources.

Pour les compétences en langue maternelle, vous avez les options suivantes :

• Transmettez les données à la brique dans des variables, puis générez le texte à partir d'un composant système en transmettant les valeurs des variables à une clé de groupe de ressources, comme décrit dans Utilisation d'un composant système pour référencer un groupe de ressources. Avec cette option, le composant personnalisé doit avoir des propriétés de métadonnées pour que la brique transmette les noms des variables dans lesquelles stocker les données.

• Utilisez le groupe de ressources du composant personnalisé pour composer la réponse du composant personnalisé, comme décrit dans Groupes de ressources de référence à partir du composant personnalisé. Utilisez la méthode conversation.translate() pour obtenir la chaîne de groupe de ressources à utiliser pour votre appel vers context.reply(). Cette option n'est valide que pour les définitions de groupe de ressources qui utilisent des paramètres positionnels (numérotés). Elle ne fonctionne pas pour les paramètres nommés. Avec cette option, le composant personnalisé doit avoir une propriété de métadonnées pour le nom de la clé de groupe de ressources, et les paramètres de la clé de groupe de ressources nommée doivent correspondre à ceux utilisés dans l'appel de context.reply().

Voici un exemple d'utilisation du regroupement de ressources à partir du composant personnalisé. Dans cet exemple, fmTemplate serait défini sur quelque chose comme ${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();  
  }
};

Dans une conversation avec assistant numérique, l'utilisateur peut interrompre un flux de conversation en modifiant le sujet. Par exemple, si un utilisateur lance un flux pour effectuer un achat, il peut interrompre ce flux afin de demander le montant des crédits dont il dispose sur une carte-cadeau. Nous appelons ce phénomène non sequitur. Pour permettre à l'assistant numérique d'identifier et de gérer des non sequiturs, appelez la méthode context.invalidInput(payload) lorsqu'une réponse de variation utilisateur n'est pas comprise dans le contexte du composant.

Dans une conversation numérique, l'exécution détermine si une entrée non valide est un non sequitur en recherchant les correspondances de réponse dans toutes les briques. Si des correspondances sont trouvées, le flux est réacheminé. Dans le cas contraire, un message s'affiche, s'il est fourni, pour inviter l'utilisateur à saisir des données, puis le composant est exécuté de nouveau. La nouvelle entrée est transmise au composant dans la propriété text.

Dans une conversation de brique autonome, l'exécution affiche le message, s'il est fourni, qui invite l'utilisateur à effectuer une saisie, puis exécute à nouveau le composant. La nouvelle entrée est transmise au composant dans la propriété text.

Cet exemple de code appelle context.invalidInput(payload) lorsque l'entrée n'est pas convertie en nombre.

"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();
    }
};

Voici un exemple de la façon dont un assistant numérique gère les entrées non valides au moment de l'exécution. Pour la première réponse relative à l'âge (twentyfive), il n'y a aucune correspondance dans les briques inscrites auprès de l'assistant numérique, donc la conversation affiche le message context.invalidUserInput indiqué. Dans la deuxième réponse relative à l'âge (send money), l'assistant numérique trouve une correspondance ; il demande ainsi s'il doit réacheminer vers ce flux.

Vous devez appeler context.invalidInput() ou context.transition(). Si vous appelez les deux opérations, assurez-vous que la variable system.invalidUserInput est toujours définie si un message supplémentaire est envoyé. Notez également que les composants d'entrée utilisateur (tels que les composants Réponse commune et Résoudre les entités) réinitialisent system.invalidUserInput.

Par exemple, supposons que vous modifiez le composant AgeChecker comme indiqué ci-dessous, et que vous appelez context.transition() aprè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;
}

Dans ce cas, le flux de données doit revenir à askage pour que l'utilisateur obtienne deux messages de sortie : "Age input not understood. Please try again", suivi de "How old are you?". Voici comment cela peut être géré dans un flux de dialogue en mode 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"