Yonyx Javascript API enables communication between “Embedded Yonyx” and your “Container website”.
If you have any problems or requests please contact us.

Embedded Yonyx is any Yonyx page like Yonyx Guide or Yonyx Landing Page that is embedded into your Container Website.

Container website is your website that embeds Yonyx.

Yonyx Javascript API is enabled per Line of Business.
Please send us a request at support@yonyx.com with the following details:
1. Line of Business name you want it enabled for.
2. You Container website URL where you plan to embed Yonyx.

Messages supported by this API.

Outgoing Messages
~~~~~~~~~~~~~~~~~~~~~
traversal-completed
traversal-reference-id-submitted
guidance-step-loaded
user-response-selected
dimension

Incoming Messages
~~~~~~~~~~~~~~~~~~~~~~
enable-user-responses
disable-user-responses
select-user-response
get-dimension
go-back
invoke-feedback
invoke-compliment
complete-traversal
replace-placeholders
return-command-result
set-incident-placeholder-values

This message is published to the Container Website when a guidance step is loaded by an embedded Yonyx Guide.

Structure of the message:
{
   "messageName":"guidance-step-loaded",
   "id":"222f46b0-9d59-11e2-bfd4-40406ab12aa1",
   "transcriptId":"72a3d100-b5a4-11e4-9ecf-0eeb802c7794",
   "title":"My TV Doesn't work",
   "body":"
Please check if your TV is plugged into the wall socket.
",
   "question":"Is your TV plugged into the wall socket?",
   "notes":"",
   "commandInternalName":"place-order",
   "commandParameters":[
      {
          "name":"t-shirt-size",
          "value":"Small"
      },
      {
          "name":"t-shirt-color",
          "value":"Blue"
      }
   ],
   "currentGuidanceFamilyUrl": "https://your-subdomain.yonyx.com/y/conversation/?id=4133cb50-9d62-11e2-bfd4-40406ab12aa1&did=f9e71980-3de7-11e5-9862-0800271a7174",
   "responses":[
      {
         "id":"3133cb50-9d62-11e2-bfd4-40406ab12aa1",
         "body":" No it is not.",
         "nextGuidanceFamily":"3133cb50-9d62-11e2-bfd4-40406ab12aa2",
         "nextGuidanceFamilyUrl":"https://your-subdomain.yonyx.com/y/conversation/?id=3133cb50-9d62-11e2-bfd4-40406ab12aa1&did=f9e71980-3de7-11e5-9862-0800271a7174"
      },
      {
         "id":"2bd80770-9d62-11e2-acbc-404089ef33c3",
         "body":" Yes it is",
         "nextGuidanceFamily":"2bd80770-9d62-11e2-acbc-404089ef33c4",
         "nextGuidanceFamilyUrl":"https://your-subdomain.yonyx.com/y/conversation/?id=2bd80770-9d62-11e2-acbc-404089ef33c3&did=f9e71980-3de7-11e5-9862-0800271a7174"         
      }
   ],
   "placeholders": [
      "t-shirt-size",
      "t-shirt-color"
   ],
   "placeholderValues": [
      {
         "name": "t-shirt-size",
         "value": "Small"
      },
      {
         "name": "t-shirt-color",
         "value": "Blue"
      },
  ]
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it selects the specific User Response and traverses further.

{
Structure of the message:
{
   "messageName":"select-user-response",
   "id":"3133cb50-9d62-11e2-bfd4-40406ab12aa1"
}

This message is published to the Container Website when an end user clicks on a specific “User Response” of a Guidance Step.

Structure of the message:
{
   "messageName":"user-response-selected",
   "id":"3133cb50-9d62-11e2-bfd4-40406ab12aa1",
   "body":" No it is not."
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it prevents traversal by making the User Responses non clickable.

Structure of the message:
{
   "messageName":"disable-user-responses"
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it allows traversal by making the User Responses clickable.

Structure of the message:
{
   "messageName":"enable-user-responses"
}

This message is published to the Container Website when an end user clicks on the “Done” link of a Guidance Step to wrap up the traversal.

Structure of the message:
{
   "messageName":"traversal-completed",
   "transcriptId":"72a3d100-b5a4-11e4-9ecf-0eeb802c7794",
   "transcript":"http://testisp.yonyx.com:8888/incident/?did=72a3d100-b5a4-11e4-9ecf-0eeb802c7794\n\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:31] My TV Doesn't work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:00:51] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------\nU: Yes, it did.\n--------------------------------------------\nT: [00:00:30] Use Remote Control to Turn TV On\nQ: Did the TV turn on?\n--------------------------------------------\n\n "
}

This message is published to the Container Website when an end user clicks on the “Submit” button in the “Done” window after populating Reference Id field.

Structure of the message:
{
   "messageName":"traversal-reference-id-submitted",
   "transcriptId":"72a3d100-b5a4-11e4-9ecf-0eeb802c7794",
   "referenceId":"xxxxxxxx",
   "transcript":"http://testisp.yonyx.com:8888/incident/?did=72a3d100-b5a4-11e4-9ecf-0eeb802c7794\n\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:31] My TV Doesn't work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:00:51] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------\nU: Yes, it did.\n--------------------------------------------\nT: [00:00:30] Use Remote Control to Turn TV On\nQ: Did the TV turn on?\n--------------------------------------------\n\n "
}

This message is published to the Container Website whenever the dimension of Embedded Yonyx Guide changes.

Structure of the message:
{
  "messageName": "dimension",
  "width": 568,
  "height": 309
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it publishes ‘dimension’ message back to the Container Website.

Structure of the message:
{
   "messageName":"get-dimension"
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it opens Feedback window.

Structure of the message:
{
   "messageName":"invoke-feedback"
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it opens Compliment window.

Structure of the message:
{
   "messageName":"invoke-compliment"
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it opens Done window.

Structure of the message:
{
   "messageName":"complete-traversal"
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it replaces all placeholders in the body with the replacement values carried by this message.

Structure of the message:
{
  "messageName": "replace-placeholders",
  "placeholdersReplacementMap": {
    "placeholder-1": "replacement-value-1",
    "placeholder-2": "replacement-value-2",
    "placeholder-3": "replacement-value-3"
  }
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it traverses back to the previous Guidance Step.

Structure of the message:
{
   "messageName":"go-back",
}

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it initializes the current incident with provided Placeholder values.

Structure of the message:
{
   "messageName":"set-incident-placeholder-values",
   "placeholderValues": 
    {
        "name-one" : "value one",
        "name-two" : "value two"
    }
}

Let’s walk you through the process of setting this up step by step.

Download the complete html file here

Let’s review this html file:

1. The head section includes a script file called “container-app.js”. We will review this script in Step 2.

   <script src="container-app.js"></script>

2. The body is made up of multiple sections. formHeader is used to construct the header of the app with a logo.

         <!-- 
         =================================================================================
             THIS SECTION RENDERS HEADER 
             USE YOUR OWN URL FOR LOGO HERE
         =================================================================================    
         -->  	
         <div id="formHeader" class="row " style="margin:5px;"><!-- row - formHeader  -->
         ...
         </div> <!-- row - formHeader  -->
   		

3. formLoading is used to construct wait screen.

         <!-- 
         =================================================================================
             THIS SECTION RENDERS WAIT SCREEN 
             USE YOUR OWN URL FOR SPINNING WHEEL HERE
         =================================================================================    
         -->   
         <div id="formLoading" class="row " style="margin:5px; display:none;"><!-- row - formLoading  -->
         ...
         </div> <!-- row - formLoading  -->
       

4. yonyxEmbed is used to construct Yonyx iframe embed.

         <!-- 
         =================================================================================
             THIS SECTION RENDERS EMBEDS YONYX LANDING PAGE IN AN IFRAME 
         =================================================================================    
         -->   			
         <div id="yonyxEmbed" class="row " style="margin:5px;"><!-- row - yonyxEmbed  -->
         ...
     	   <iframe id="yonyxAppFrame" frameborder="0" src="" width="100%" height="300px" style="border:none;" allowfullscreen="allowfullscreen" ></iframe>
         ...
         </div> <!-- row - yonyxEmbed  -->
   
       

5. formGuidanceStep is used to display each Guidance step’s Title, Body, Question and User responses.

         <!-- 
         =================================================================================
             THIS SECTION RENDERS THE HTML MARKUP OF EACH GUIDANCE STEP
             GUIDANCE STEP TITLE GOES INTO formGuidanceStepTitle
             GUIDANCE STEP BODY GOES INTO formGuidanceStepBody
             GUIDANCE STEP FOLLOW-ON QUESTION GOES INTO formGuidanceStepQuestion
             GUIDANCE STEP USER RESPONSES GO INTO formGuidanceStepResponses
         =================================================================================    
         -->         
         <div id="formGuidanceStep" class="row " style="display:none; margin:5px;">
         ...
         </div> <!-- row - formGuidanceStep  -->
       

6. formEmailRegistration is used display an Email Registration form for the user to enter information and submit.

         <!-- 
         =================================================================================
             THIS SECTION IS AN EXAMPLE OF HOW YOU WOULD DISPLAY A FORM SIMILAR TO 
             EMAIL REGISTRATION FORM TO THE USER AND SUBMIT THE INPUTS TO 3RD PARTY API
         =================================================================================    
         -->  
         <div id="formEmailRegistration" class="row " style="display:none; margin:5px;">
         ...
         </div> <!-- row - formEmailRegistration  -->
   
       

7. formChooseCountry is used to display a list of Counties for the user to choose.

         <!-- 
         =================================================================================
             THIS SECTION IS AN EXAMPLE OF HOW YOU WOULD DISPLAY A LIST COUNTIES RETRIEVED 
             FROM AN API AND TRAVERSAL THE GUIDE WILL DEPEND ON:
             1. COUNTRY CHOSEN BY THE USER
             2. AUTO TRAVERSE CONDITION CREATED BY THE GUIDE AUTHOR
         =================================================================================    
         -->  
         <div id="formChooseCountry" class="row " style="display:none; margin:5px;">
         ...
         </div> <!-- row - formChooseCountry  -->
       

8. formPublicIP is used to display the user’s public IP.

         <!-- 
         =================================================================================
             THIS SECTION IS AN EXAMPLE OF HOW YOU WOULD DISPLAY USER'S PUBLIC IP RECEIVED
             FROM AN API AND TRAVERSAL OF THE GUIDE WILL DEPEND ON:
             1. SUCCESS: IF THE API SUCCEEDS
             2. FAILURE: IF THE API FAILS
         =================================================================================    
         -->  
         <div id="formPublicIP" class="row " style="display:none; margin:5px;">
         ...
         </div> <!-- row - formPublicIP  -->
       

9. formWrapup is used to present the user with a summary of all choice made along with the transcript of the path that the user traversed through this Gudie.

         <!-- 
         =================================================================================
             THIS SECTION RENDERS A FINAL WRAPUP SCREEN WHERE YOU DISPLAY:
             1. SUMMARY OF VALUES INPUT BY THE USER
             2. SUMMARY OF THE PATH TRAVERSED BY THE USER THROUGH THE GUIDE
         =================================================================================    
         -->  
         <div id="formWrapup" class="row " style="display:none; margin:5px;">
         ...
         </div> <!-- row - formWrapup  -->
       

Download the complete javascript file here

Let’s review this javascript file:

1. This file is made up of multiple sections. To begin, we have the declarations.

         var stepId = null;
         var transcriptId = null;
         var transcript = null;
         var currentGuidanceFamilyUrl = null;
         var previousSteps = [];
         var transcriptIds = [];
         var transcriptUrls = "";
         var landingPageUrlFrag = "/y/portal/"; 
         var browseUrlFrag = "&at=browse";
         var searchUrlFrag = "&at=search";
   
   
         var constOriginUpstream = window.location.protocol + "//" + window.location.hostname ; 
         /*
         =================================================================================
          Replace this with your Yonyx subdomain
         =================================================================================
         */
         var constOriginDownstream = "https://testisp.yonyx.com";
         /*
         =================================================================================
          Replace this with your Yonyx LOB ID
         =================================================================================
         */      
         var lobId = "847eb630-047c-11e4-9638-bc764e10f0e8";
         /*
         =================================================================================
           Temporary data storage - used later for Placeholder replacements
         ================================================================================= 
         */
         var countryCode, countryName, publicIP, name, email, userMessage;
         var sessionPlaceholdersMap = {};
         sessionPlaceholdersMap[ "demo-email-form-values" ] = "";
         sessionPlaceholdersMap[ "demo-public-ip" ] = "";
         sessionPlaceholdersMap[ "demo-country-name" ] = "";
   
       

2. Senders: These are functions that send messages from Container app to Yonyx embed (downstream) or Host web page where the container app itself may be embedded.

         /*  
         =================================================================================
           Broadcasts messages upstream to the  web page that embeds this container app
           
           Only useful in situations where this container app is embedded:
           
                   Someother web page  -- [Upstream]
                                 ^
                                 |
                                 v
                       Embedded container app
                                 ^
                                 |
                                 v
                     Embedded Yonyx [Downstream]
   
         =================================================================================
         */
         function senderUpstream(data) {
           ...
         } 
   
         /*  
         =================================================================================
           Broadcasts messages downstream to Yonyx
         =================================================================================
         */
         function senderDownstream(data) {
           ...
         }
       

3. Listener: This function listens to incoming messages from Yonyx embed.

         /*
         =================================================================================
           Listens to incoming messages from Yonyx
           Supported Yonyx Javascript API methods : https://corp.yonyx.com/ui-api-v1/
             guidance-step-loaded
             select-user-response
             user-response-selected
             disable-user-responses
             enable-user-responses
             traversal-completed
             traversal-reference-id-submitted
             dimension
             invoke-feedback
             invoke-compliment
             complete-traversal
             replace-placeholders
             return-command-result
             get-dimension
             go-back
         =================================================================================
         */
         function listener (event) {
           ...
   
           /*
           =================================================================================
             Process incoming messages
           =================================================================================
           */
           if(data.messageName === "lob-loaded") {
             /*
             =================================================================================
               Occurs when a Yonyx landing page is loaded
             =================================================================================
             */
             ...
           }
           else if(data.messageName === "guidance-step-loaded") {
             /*
             =================================================================================
               Occurs when a Yonyx Guidance step is loaded
             =================================================================================
             */
             ...
   
             /*
             =================================================================================
               Process placeholders
             =================================================================================
             */
             ...
   
             /*
             =================================================================================
               Process commands
             =================================================================================
             */
             ...
           }
           else if(data.messageName === "traversal-completed") {
             /*
             =================================================================================
               Occurs when an internal user clicks on "Done" button after the Guide traversal
               is completed
             =================================================================================
             */
             ...
   
           }
           else if(data.messageName === "dimension") {
             /*
             =================================================================================
               When Yonyx landing page, guidance step, etc are loaded this message is 
               broadcasted by Yonyx with its dimension info
               This info can be used by the container app to adjust the height of the 
               embedded iframe
             =================================================================================
             */
   
             ...          
           }
         }
       

4. Browser Event Listener: This section wires the listener function with browser event listener.

         /*
         =================================================================================
           Register "listener" function as the browser event listener
         =================================================================================
         */
   
         if (window.addEventListener) {
           // For standards-compliant web browsers
           window.addEventListener("message", listener, false);
         }
         else {
           window.attachEvent("onmessage", listener);
         }
   
       

5. Javascript API methods: These functions are used to communicate with Yonyx embed.

         /*
         =================================================================================
           Use this method to instruct Yonyx to enable User responses (make them clickable)
         =================================================================================
         */
         function enableUserResponses() {
           ...
         }
         /*
         =================================================================================
           Use this method to instruct Yonyx to disable User responses (make them nonclickable)
         =================================================================================
         */
         function disableUserResponses() {
           ...
         }
         /*
         =================================================================================
           Use this method to instruct embedded Yonyx iframe to go back one step
         =================================================================================
         */
         function goBack( ) {
           ...
         }
   
         /*
         =================================================================================
           Use this method to instruct Yonyx to choose the User response with this id
         =================================================================================
         */
         function selectUserResponse(userResponseId) {
           ...
         }
         /*
         =================================================================================
           Use this method to instruct Yonyx to replace placeholder tokens with their 
           corresponding values
         =================================================================================
         */
         function replacePlaceHolders(placeholdersReplacementMap) {
           ...
         }
         /*
         =================================================================================
           Use this method to instruct Yonyx to click "Done"
         =================================================================================
         */
         function completeTraversal() {
           ...
         }
   
         /*
         =================================================================================
           Use this method to return a command's return value to Yonyx
           Based on this return the Guide may automatically traverse forward in a direction
           programmed by the author through auto-traverse conditions
         =================================================================================
         */
         function returnCommandResult( commandReturnValue ) {
           ...
         }
         
   
         /*
         =================================================================================
           Use this method to instruct Yonyx to broadcase its current page's dimension 
           on demand
         =================================================================================
         */
         function getDimension( ) {
           ...
         }
         /*
         =================================================================================
           Use this method to instruct the upstream web page to adjust its dimensions
         =================================================================================
         */      
         function sendDimension( ) {
           ...
         }
   
       

6. Process Commands: This functions calls appropriate functions based on current Guidance step’s command.

         /*
         =================================================================================
           Process commands
         =================================================================================
         */ 
         function processCommand( commandInternalName, stepId, transcriptId, data ) {
           
   
           // Proceed with processing the Command
           switch ( commandInternalName ) {
   
             case "demo-display-email-registration-form":
   
               // Disable Traversal
               disableUserResponses();
   
               showFormEmailRegistration(data);     
   
             break;
   
             case "demo-display-country-list":
   
               // Disable Traversal
               disableUserResponses();
   
               showFormChooseCountry(data);     
   
             break;
   
             case "demo-display-public-ip":
   
               // Disable Traversal
               disableUserResponses();
   
               showFormPublicIP(data);     
   
             break;
   
   
             default: 
   
           }
         }
       

7. Helper functions

         /*
         =================================================================================
           Helper functions
         =================================================================================
         */ 
   
         function addTranscriptId(transcriptId) {
           ...
         }
         function showMessage(formName, msg, error) {
           ...
         }
         function hideMessage(formName) {
           ...
         }      
         function restartSession() {
           ...
         }
         function hideAll() {
           ...
         }
         function clearAll() {
           ...
         }
         $(".home").click(function(e) {
           ...
         });
         $(".back").click(function(e) {
           ...
         });
         function addToPrevousSteps() {
           ...
         }
         function showHideBack() {
           ...
         }
         function showError(formName, message ) {
           ...    
         }
         function resetAttributes() {
           ...    
         }
         function getUserChoices() {
           ...    
         }
   
         $("form").submit(function() { return false; });
   
       

8. Section Yonyx Embed: These functions are used to housekeep Yonyx Embed section.

         /*
         =================================================================================
           YONYX EMBED
         =================================================================================
         */ 
         function getLandingPageUrlBrowse() {
           ...
         }
         function getLandingPageUrlSearch() {
           ...
         }
         function setEmbedUrl(url) {
           ...
         }
         function showYonyxEmbed() {
           ...
         }
         function hideYonyxEmbed() {
           ...
         }      
       

9. Section formLoading: These functions are used to housekeep wait screen.

         /*
         =================================================================================
           FORM LOADING 
         =================================================================================
         */ 
         function showFormLoading() {
           ...
         }
         function hideFormLoading() {
           ...
         }
      
       

10. Section FormGuidanceStep: These functions are used to housekeep FormGuidanceStep.

          /*
          =================================================================================
            FORM GUIDANCE STEP
          =================================================================================
          */ 
          function showFormGuidanceStep(data) {
            ...
          }
          function revealFormGuidanceStep() {
            ...
          }      
          function hideFormGuidanceStep() {
            ...
          }
          function clearFormGuidanceStep() {
            ...
          }
          $("#formGuidanceStepWrapup").click(function(e) {
            ...
          });
          $("#formGuidanceStepBrowse").click(function(e) {
            ...
          });
          $("#formGuidanceStepSearch").click(function(e) {
            ...
          });     
        

11. Section FormEmailRegistration: These functions are used to housekeep FormEmailRegistration.

          /*
          =================================================================================
            FORM EMAIL REGISTRATION
          =================================================================================
          */ 
          function showFormEmailRegistration(data) {
            ...     
          }
    
          function hideFormEmailRegistration() {
            ...    
          }
          function clearFormEmailRegistration() {
            ...    
          }
          $("#formEmailRegistrationContinue").click(function(e) {
            ...    
          });
          
        

12. Section FormChooseCountry: These functions are used to housekeep FormChooseCountry.

          /*
          =================================================================================
            FORM CHOOSE COUNTRY
          =================================================================================
          */       
          function showFormChooseCountry(data) {
            ...    
          }
    
          function hideFormChooseCountry() {
            ...    
          }
          function clearFormChooseCountry() {
            ...    
          }
          $("#formChooseCountryContinue").click(function(e) {
            ...    
          });
          
        

13. Section FormPublicIP: These functions are used to housekeep FormPublicIP.

          /*
          =================================================================================
            FORM PUBLIC IP
          =================================================================================
          */       
          function showFormPublicIP(data) {
            ...    
          }
    
          function hideFormPublicIP() {
            ...    
          }
          function clearFormPublicIP() {
            ...    
          }
          $("#formPublicIPContinue").click(function(e) {
            ...    
          });
          
        

14. Section FormWrapup: These functions are used to housekeep FormWrapup.

          /*
          =================================================================================
            FORM WRAPUP
          =================================================================================
          */   
          function showFormWrapup(data) {
            ...            
          } 
          function hideFormWrapup() {
            ...    
          }
          function clearFormWrapup() {
            ...    
          }