Tutorial de práctica: Creación de una nueva acción de Kaizala

  • Artículo

Información general

En este tutorial, crearemos una acción de Kaizala personalizada utilizando el marco de acción extensible proporcionado por la plataforma kaizala.

Crearemos una acción "Hacer comentarios" que permitirá a los usuarios de Kaizala solicitar comentarios a otros usuarios en términos de clasificación de 1 a 5 star sobre las preguntas que se hagan, junto con los comentarios que quieran proporcionar.  

Puede descargar paquetes de acción de Kaizala de ejemplo desde aquí.

Requisitos previos

  • Un smartphone (Android/iOS) con la aplicación Kaizala instalada
  • Una cuenta de Office365
  • Acceso a un editor HTML/JS (bloc de notas/Visual Studio Code/etc.)

Pasos para crear una acción de ejemplo

  • Paso 1: Creación de un nuevo directorio para el paquete de acción

    • Cree un nuevo directorio en el escritorio & asígnele el nombre "SampleAction"
    • Coloque todos los archivos posteriores en este directorio.

  • Paso 2: Definición de un modelo de datos para la acción

    • En primer lugar, debemos definir el modelo de datos que se usará en nuestra acción personalizada.

    • Las acciones de Kaizala son actualmente modelos de datos basados en formularios. Por lo tanto, primero tendremos que definir las "preguntas" que necesitamos incluir en nuestro formulario.

    • Puesto que se trata de una acción "Pedir comentarios", planeamos usar dos fragmentos de datos.

      • Clasificación numérica (valor de 1 a 5)
      • Comentarios o comentarios textuales, si los hubiera

    • La infraestructura de Kaizala Forms admite los siguientes tipos de preguntas:

      Tipo de pregunta Description
      SingleSelect Pregunta de opción única con opciones
      MultiSelect Pregunta de opción múltiple con opciones
      Texto Pregunta con una respuesta de texto sin formato
      Numérico Pregunta con una respuesta numérica
      Ubicación Pregunta con una respuesta de ubicación
      DateTime Pregunta con respuesta DateTime
      Imagen Pregunta con una imagen como respuesta

    • Para nuestras dos preguntas, usaremos el tipo de pregunta "Numeric" & "Text" para el número de clasificación & los comentarios respectivamente.

      • Cree un nuevo archivo denominado "appModel.json" y coloque el siguiente contenido en el archivo. El archivo contiene las dos preguntas enumeradas en orden
      { 
    "questions": [{ 
            "title": "Rating", 
            "type": "Numeric" 
        }, 
        { 
            "title": "Comments", 
            "type": "Text" 
        } 
    ], 
    "title": "Ask Feedback", 
    "visibility": "All", 
    "isAnonymous": false, 
    "isResponseAppended": false 
} 
      • Nota: El código anterior también contiene metadatos adicionales que se obtendrán más adelante (fuera del ámbito de esta sesión)
      • Guardar el archivo

  • Paso 3: Definición de una vista para crear la solicitud de comentarios

    • Ahora crearemos un nuevo archivo HTML que se usará para crear nuevas instancias de nuestra acción de Kaizala.
    • Esta es la vista que se invoca cuando se pulsa el icono de la paleta. En este punto de vista, nos gustaría preguntarles sobre qué quieren comentarios. 
    • Cree un nuevo archivo denominado "CreationView.html" y coloque el código HTML siguiente en el archivo.
      <html> 
 
<head> 
</head> 
 
<body onload="onCreatePageLoad()"> 
    <br/> <br/> 
    <div> 
        <p>What would you like feedback on?</p> 
        <br/> <br/> 
        <input type="text" name="description" id="description" placeholder="Enter question text here" value=""> 
    </div> 
    <br/> <br/> 
    <div> 
        <input type="submit" name="submit" value="Submit" onclick="submitData()"> 
    </div> 
</body> 
 
</html> 
    • Guardar el archivo

  • Paso 4: Inclusión del SDK de Js de Kaizala Forms

    • Para facilitar a los desarrolladores el aprovechamiento de la infraestructura de formularios, Kaizala proporciona una biblioteca contenedora de JavaScript que puede incluir en las acciones personalizadas.
    • Descargue el archivo siguiente & colocarlo en el mismo directorio que el datamodel.json y CreationView.html

  • Paso 5: Uso del SDK de Js de Kaizala Forms para enviar el formulario

    • Agregue el siguiente fragmento de código en el <head> elemento del "CreationView.html" para hacer referencia al SDK de JS de Kaizala Forms.

      <head> 
    <script type="text/javascript" src="KASClient.js"></script> 
</head> 

    • Ahora, cuando el usuario hace clic en enviar, debemos comprobar que ha escrito una pregunta para hacer comentarios y crear la instancia de formulario.

    • También es necesario crear una instancia del formulario en la carga de la página. Agregue el siguiente fragmento de código de JavaScript al "CreationView.html" dentro del <head> elemento .

          <script type="text/javascript"> 
        var _form; // type: KASForm
 
        // Below will be called on onload of CreationView.html 
        function onCreatePageLoad() { 
            KASClient.Form.initFormAsync (function (form, error) { 
                if (error != null) { 
                    showAlert("Error:initFormAsync:" + error); 
                    return; 
                } 
                _form = form; 
            }); 
        } 
 
        function submitData() {
            var description = document.getElementById("description").value; 
            if (description == null || description == "") { 
                KASClient.App.showNativeErrorMessage("Please enter the details for what you would like feedback on."); 
            } else { 
                // Set the description to form title 
                _form.title = description; 
 
                // Finally send the request 
                KASClient.Form.submitFormRequest(_form); 
            } 
        } 
    </script>

    • Guardar el archivo

  • Paso 6: Creación del manifiesto del paquete de acción

    • Ahora que tenemos una apariencia de lo que queremos lograr y hemos creado correctamente una vista, ahora crearemos el archivo de manifiesto del paquete que hace referencia a estos archivos. 

    • El archivo de manifiesto del paquete proporciona información esencial para que la plataforma de Kaizala reconozca y ejecute la acción personalizada de Kaizala. 

    • Crearemos un manifiesto de paquete y especificaremos lo siguiente:

      • Nombre para mostrar de la acción de Kaizala
      • Identificador personalizado para la acción
      • Asignación de la vista de creación a nuestra página de CreationView.html

    • Antes de eso, necesitaremos un icono para el paquete action. Descargue el archivo de icono & guárdelo como icon.png en la misma carpeta que los demás archivos.

    • Cree un nuevo archivo denominado "package.json" y agregue el siguiente fragmento de código al archivo. Asegúrese de editar el identificador para que la acción sea única o distinta.

      { 
    "id": "com.microsoft.mobile.kaizala.swads.FeedbackSample", 
    "schemaVersion": 1, 
    "version": 1,
    "minorVersion": 1,
    "providerName": "Microsoft Inc.", 
    "displayName": "Ask Feedback", 
    "description": "Custom action to collect feedback.", 
    "icon": "icon.png", 
    "appModel": "appModel.json", 
    "views": { 
        "CreationView": { 
            "labelHeader": "Feedback requested", 
            "sourceLocation": "CreationView.html" 
        } 
    } 
}

    • Puede configurar la tarjeta que aparece en el lienzo de chat de Kaizala especificando las cadenas en el manifiesto del paquete.  

    • Modifique el objeto "Views" del manifiesto del paquete para que coincida con el fragmento de código siguiente:

      "views": { 
            "CreationView": { 
                "labelHeader": "Feedback requested", 
                "sourceLocation": "CreationView.html"            
            }, 
            "ChatCanvasCardView": { 
                "labelResponded": "You have provided feedback.", 
                "labelRespondToForm": "PROVIDE FEEDBACK", 
                "isResponseEditable": true 
            } 
} 

    • Guardar el archivo

  • Paso 7: Creación de la vista de respuesta

    • Ahora crearemos la vista que aparece a los usuarios de Kaizala respondiendo a una instancia de nuestra acción.
    • Cree una nueva llamada de archivo ResponseView.html e inserte el fragmento de código siguiente en el archivo.
    • Haremos lo siguiente
      • Agregar selección de botón de radio para la clasificación
      • Preparación de un objeto y código de respuesta del formulario para enviar el formulario
          <html> 
     
    <head> 
        <title></title> 
        <script type="text/javascript" src="KASClient.js"></script> 
        <script> 
            var _form; // type: KASForm
            var _myFormResponses; // type: KASFormResponse[]
     
            // Below will be called on onload of ResponseView.html 
            function onResponsePageLoad() { 
                KASClient.Form.getFormAsync(function (form, error) { 
                    if (error != null) { 
                        KASClient.App.showNativeErrorMessage("Error:getFormAsync:" + error); 
                        return; 
                    } 
                    _form = form; 

                    // Document title would be the form title
                    document.getElementById("title").innerHTML = _form.title;

                    KASClient.Form.getMyFormResponsesAsync(function (responses, error) { 
                        if (error != null) { 
                            KASClient.App.showNativeErrorMessage("Error:getMyFormResponsesAsync:" + error); 
                            return; 
                        } 
                        _myFormResponses = responses;

                        // Render previous response, if any
                        if (isCurrentUserResponded()) {
                            var rating = _myFormResponses[0].questionToAnswerMap["0"];
                            var remark = _myFormResponses[0].questionToAnswerMap["1"];

                            var options = document.getElementsByName('option');
                            options[rating - 1].checked = true;

                            document.getElementById("description").value = remark;
                            document.getElementById("description").placeholder = "";
                        }
                    }); 
                }); 
            } 
     
            function submitData() { 
                var selectedOption = getSelectedOption(); 
                var remark = document.getElementById("description").value; 
                submitFormResponse(selectedOption, remark); 
            } 
     
            function getSelectedOption() { 
                // Check which radio button is checked 
                var options = document.getElementsByName('option'); 
                for (var i = 0; i < options.length; i++) { 
                    if (options[i].checked) { 
                        return parseInt(options[i].value); 
                    } 
                } 
            } 
     
            // Below will be called when responder submits a new response 
            function submitFormResponse(selectedOption, remark) { 
                if (remark == null || remark == "") { 
                    KASClient.App.showNativeErrorMessage("Please fill remark"); 
                } else if (selectedOption == "") { 
                    KASClient.App.showNativeErrorMessage("Please select one option"); 
                } else { 
                    // For submitting response a question-answer 
                    // map is required, lets create that! 
                    var questionToAnswerMap = JSON.parse("{}"); 
                    questionToAnswerMap[0] = selectedOption; 
                    questionToAnswerMap[1] = remark; 
     
                    var responseId = null; 
                    var isEditingPreviousResponse = false;

                    // If there is a previous response, update it
                    if (isCurrentUserResponded()) {
                        responseId = _myFormResponses[0].id;
                        isEditingPreviousResponse = true;
                    }
     
                    // Finally submit the response 
                    KASClient.Form.sumbitFormResponse(questionToAnswerMap, responseId, isEditingPreviousResponse); 
                } 
            }

            function isCurrentUserResponded() {
                return _myFormResponses && _myFormResponses.length > 0;
            }
        </script> 
    </head> 
     
    <body onload="onResponsePageLoad()"> 
        <br/> <br/> 
        <div> 
            <p id="title"></p> 
        </div> 
        <div> 
            <br/> <br/> 
            <div> 
                <p>Select your rating:</p> 
                <br/> <br/> 
                <div> 
                    <label>1</label> 
                    <input type="radio" name="option" id="option0" value="1" checked> 
                </div> 
                <div> 
                    <label>2</label> 
                    <input type="radio" name="option" id="option1" value="2"> 
                </div> 
                <div> 
                    <label>3</label> 
                    <input type="radio" name="option" id="option2" value="3"> 
                </div> 
                <div> 
                    <label>4</label> 
                    <input type="radio" name="option" id="option3" value="4"> 
                </div> 
                <div> 
                    <label>5</label> 
                    <input type="radio" name="option" id="option4" value="5"> 
                </div> 
            </div> 
            <br/> <br/> 
            <div> 
                <p>Comments</p> 
                <input type="text" name="description" id="description" placeholder="Please enter your comments here."> 
            </div> 
            <br/> <br/> 
        </div> 
        <div class="footer"> 
            <input type="submit" name="submit" value="Submit" onclick="submitData()"> 
        </div> 
    </body> 
     
    </html> 
    `````

  • Paso 8: Creación de la vista de resumen

    • Ahora crearemos la vista que aparece a los usuarios de Kaizala viendo el resumen de la acción.

    • Cree una nueva llamada de archivo SummaryView.html e inserte el fragmento de código siguiente en el archivo. Esto creará una vista de resumen del total de clasificaciones y comentarios

        <html> 
   
  <head> 
      <title></title> 
      <script type="text/javascript" src="KASClient.js"></script> 
      <script type="text/javascript"> 
          // Globals 
          var _form; // type: KASForm 
          var _myFormResponses; // type: KASFormResponse[]
          var _formSummary; // type: KASFormFlatSummary 
          var _users; // type: Dictionary<UserId: KASUser>
   
          // Below will be called on onload of SummaryView.html 
          function onSummaryPageLoad() {            
              KASClient.Form.getFormAsync(function (form, error) {                
                 if (error != null) {                    
                    KASClient.App.showNativeErrorMessage("Error:getFormAsync:" + error);                    
                    return;                
                 }                
                 _form = form;
                 KASClient.App.showProgressBar("Fetching summary");
                 KASClient.Form.getFormSummaryAsync(
                    function (flatSummary, processedSummary, error) { // In this callback data is fetched from local database
                       if (error != null) {                    
                          KASClient.App.showNativeErrorMessage("Error:getFormSummaryAsync:callback1:" + error);                    
                          return;                
                       } 
                       onGetSummary(flatSummary);
                    },
                    function (flatSummary, processedSummary, error) { // In this callback data is fetched from server
                       KASClient.App.hideProgressBar();
                       if (error != null) {                    
                          KASClient.App.showNativeErrorMessage("Error:getFormSummaryAsync:callback2:" + error);                    
                          return;                
                       }
                       onGetSummary(flatSummary);
                    }
                 );           
              });        
           }

           function onGetSummary(summary) {
              _formSummary = summary;                    
              KASClient.App.getUsersDetailsAsync(_formSummary.getRespondedUserIds(), function (users,
                 error) {                        
                 if (error != null) {                            
                    KASClient.App.showNativeErrorMessage("Error:getUsersDetailsAsync:" + error);                            
                    return;                        
                 }                        
                 _users = users;  // Document title would be the form title 

                 document.getElementById("title").innerHTML = _form.title; 

                 // Get all responses of the user, and find the average
                 var totalRating = 0;                        
                 var responseCount = 0;          
                 for (var userId in _users) {
                    var userResponses = _formSummary.getResponsesForUserId(userId); // type: Dictionary<QuestionId, string[]>
                    totalRating += parseInt(userResponses["0"][0]);                            
                    responseCount += 1;                       
                 } 

                 document.getElementById("avg").innerHTML = totalRating / responseCount;                    
              });
           }
      </script> 
  </head> 
   
  <body onload="onSummaryPageLoad()"> 
      <div class="header"> 
          <p id="title">Title</p> 
          <br/> <br/> 
          <p id="rating">Average Rating: </p> 
          <p id="avg">avg</p> 
      </div> 
  </body> 
   
  </html>

    • Edite el objeto Views del manifiesto del paquete de la siguiente manera:

         "views": { 
            "CreationView": { 
                "labelHeader": "Feedback requested", 
                "sourceLocation": "CreationView.html"            
            }, 
            "ChatCanvasCardView": {
                "labelResponded": "You have provided feedback.", 
                "labelRespondToForm": "PROVIDE FEEDBACK", 
                "isResponseEditable": true 
            }, 
            "ResponseView": { 
                "labelHeader": "Provide feedback",
                "sourceLocation": "ResponseView.html" 
            }, 
            "ResponseResultsView": { 
                "labelPageHeader": "Feedback summary",
                "sourceLocation": "SummaryView.html" 
            } 
   }       
 `````

   

  • Paso 9: Creación del paquete de acción de Kaizala

    • Comprimir todos los archivos en un único archivo ZIP
    • Asegúrese de que el archivo ZIP no incluye otro directorio dentro de él, pero los archivos están presentes en el directorio raíz del archivo ZIP.

  • Paso 10: Inicie sesión en el Portal de administración de Kaizala

    • Abra una ventana del explorador y vaya a https://manage.kaiza.la/
    • En la esquina superior izquierda, haga clic en "Iniciar sesión"
    • Escriba sus credenciales de Office365 para iniciar sesión en el portal. Si se solicita, conceda permisos al portal de administración para acceder a la información del perfil (solo es necesario por primera vez)
    • Pulse "Agregar número de teléfono" en la esquina superior derecha & comprobar su número de teléfono

  • Paso 11: Carga del paquete de acción

    • Vaya a "Acciones" con la barra de navegación izquierda.
    • En la lista desplegable de la derecha, elija "Importar acción" y haga clic en Iniciar.
    • Haga clic en Cargar y seleccione el archivo ZIP que ha creado.
    • Haga clic en Importar.
    • Una vez que el paquete se haya importado correctamente, vuelva a buscar Acciones para confirmarlo. Debería ver la acción que aparece en "creado por este identificador".
    • Para probar esta acción, siga estos pasos .

  • Paso 12: Creación de un nuevo grupo de Kaizala

    • En el portal de administración de Kaizala, vaya a "Grupos" mediante la barra de navegación izquierda.
    • Pulse en "Crear grupo"
    • Asigne al grupo el nombre "Kaizala Actions Testing"
    • Compruebe que el grupo aparece en la aplicación de Kaizala.

  • Paso 13: Publicación de la acción en el grupo

    • Vaya a "Grupos" con la barra de navegación izquierda.
    • Pulse en el nombre del grupo que creó en el paso 13.
    • Pulse en la pestaña "Acciones".
    • Seleccione la acción que creó en el paso 12 & haga clic en "Agregar acción". Ahora debería ver que la acción de Kaizala personalizada aparece en la pestaña Detectar.

  • Paso 14: Uso de la acción personalizada de Kaizala

    • Agregue la acción personalizada a la paleta y úsela en el grupo.