Javascript API Reference
Everything you need to build on top of Yonyx.Introduction
If you have any problems or requests please contact us.
What is Embedded Yonyx Website?
What is Container website?
How to enable Javascript API?
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.
Supported Messages
======================================== Messages published by Embedded Yonyx ======================================== lob-loaded guidance-step-loaded user-response-selected traversal-completed traversal-reference-id-submitted dimension result-set-form-values result-set-incident-placeholder-values ======================================== Messages published by Container Website ==================================== 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 set-form-values
Guidance Step Loaded
Structure of the message: { messageName : 'guidance-step-loaded', id : '222f46b0-9d59-11e2-bfd4-40406ab12aa1', transcriptId : '72a3d100-b5a4-11e4-9ecf-0eeb802c7794', title : 'Place Order', body : 'T-Shirt size you chose: Small. T-Shirt color you chose: Blue. Please fill out this form.
', question : 'Are you ready to proceed?', notes : '', commandInternalName : 'place-order', commandParameters : [ { name : 'user-type', value : 'Registered' }, { name : 'channel', value : 'Website' } ], 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 : 'Yes, place oder.', 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 : 'No, skip order placement.', 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' } ], autoTraverse : false, form : [ { name : 'buyer-name', type : 'String', value : '' }, { name : 'item-name', type : 'String', value : '' }, { name : 'quantity', type : 'String', value : '' } ] }
Select User Response
{ Structure of the message: { messageName : 'select-user-response', id : '3133cb50-9d62-11e2-bfd4-40406ab12aa1' }
User Response Selected
Structure of the message: { messageName : 'user-response-selected', id : '3133cb50-9d62-11e2-bfd4-40406ab12aa1', body : ' No it is not.' }
Disable User Responses
Structure of the message: { messageName : 'disable-user-responses' }
Enable User Responses
Structure of the message: { messageName : 'enable-user-responses' }
Traversal Completed
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 " }
Traversal Reference Id Submitted
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 " }
Dimension
Structure of the message: { messageName : 'dimension', width : 568, height : 309 }
Get Dimension
Structure of the message: { messageName : 'get-dimension' }
Invoke Feedback
Structure of the message: { messageName : 'invoke-feedback' }
Invoke Compliment
Structure of the message: { messageName : 'invoke-compliment' }
Complete Traversal
Structure of the message: { messageName : 'complete-traversal' }
Replace Placeholders
Structure of the message: { messageName : 'replace-placeholders', placeholdersReplacementMap : { 'placeholder-1' : 'replacement-value-1', 'placeholder-2' : 'replacement-value-2', 'placeholder-3' : 'replacement-value-3' } }
Go Back
Structure of the message: { messageName : 'go-back' }
Set Incident Placeholder Values
Structure of the message: { messageName : 'set-incident-placeholder-values', placeholderValues : [ { name : 'some name', value : 'some value' }, { name : 'some name', value : 'some value' } ] }
Result of Set Incident Placeholder Values
Structure of the message: { messageName : 'result-set-incident-placeholder-values', success : false, message : 'Placeholder names can only contain alphabets, numerals and hyphen.' }
Set Form Values
1. Validates the form values.
2. Submits the form.
3. Updates the current incident with provided Form values as Placeholder values.
4. Returns the result in “Result of Set Form Values” message.
Structure of the message: { messageName : 'set-form-values', formValues : [ { name : 'buyer-name', type : 'String', value : 'John Doe' }, { name : 'item-name', type : 'String', value : 'T-Shirt' }, { name : 'quantity', type : 'String', value : '3' } ] }
Result of Set Form Values
Structure of the message: { messageName : 'result-set-form-values', success : true, message : 'Submit form values succeeded.', formValues : [ { name : 'buyer-name', type : 'String', value : 'John Doe' }, { name : 'item-name', type : 'String', value : 'T-Shirt' }, { name : 'quantity', type : 'String', value : '3' } ] }
Live Demo
Simple Embed (Open Demo) | Embed with Custom UI (Open Demo) | |
---|---|---|
User Interface | This type of container app simply embeds Yonyx and leverages Yonyx’s native UI completely. | This type of container app, in addition to embedding Yonyx, also controls the UI elements that display Title, Body and Follow on question. |
Commands with data capture form |
Once the container app has been programmed to handle data-capture command differently than a generic command, introducing additional data-capture commands does not need developer involvement. Form validation and submission are all handled by Yonyx natively. |
Once the container app has been programmed to handle data-capture command differently than a generic command, introducing additional data-capture commands does not need developer involvement unless form UI customizations are needed. Form validation and submission need to be handled by the container app by calling “Set Form Values” and listening to “Result of Set Form Value”. |
Other Commands that interact with your internal/external systems | Developer involvement is needed for command implementations that perform actions other than data capture. | Developer involvement is needed for command implementations that perform actions other than data capture. |
This page demonstrates a Container Website hosted at “rackcdn.com” communicating with Yonyx Guide hosted at testisp.yonyx.com.
This demo can be used to understand the following:
- Use Commands to invoke functions that in turn call external 3rd party APIs to GET or POST data. This demo uses 3 Commands:
- demo-display-email-registration-form: This is a data-capture command (command that contains a form). It presents an Email Registration Form and on submit saves the information to the current Incident as Placeholder Values.
- demo-display-country-list: This is a data-capture command. It presents a list of Countries in a dropdown and on submit saves the information to the current Incident as Placeholder Values.
- demo-display-public-ip: This is a generic command. It retrieves the user’s public IP using a 3rd party API.
- Use Placeholder to present data to the user within a Guidance step.
- demo-email-form-values: To display Email Registration Form information provided by the user within a separate Guidance step.
- demo-country-name: To display Country chosen by the user within a separate Guidance step.
- demo-public-ip: To display the user’s Public IP within a separate Guidance step.
Step-by-step Walkthrough
Step 1: Create an html file.
Let’s review this html file:
- 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>
- 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 -->
- 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 -->
- 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 -->
- 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 -->
- 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 -->
- 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 -->
- 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 -->
- 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 -->
Step 2: Create a javascript file.
- 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" ] = "";
- 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) { ... }
- 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 ================================================================================= */ ... } }
- 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); }
- 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( ) { ... }
- 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: } }
- 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; });
- 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() { ... }
- Section formLoading: These functions are used to housekeep wait screen.
/* ================================================================================= FORM LOADING ================================================================================= */ function showFormLoading() { ... } function hideFormLoading() { ... }
- 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) { ... });
- Section FormEmailRegistration: These functions are used to housekeep FormEmailRegistration.
/* ================================================================================= FORM EMAIL REGISTRATION ================================================================================= */ function showFormEmailRegistration(data) { ... } function hideFormEmailRegistration() { ... } function clearFormEmailRegistration() { ... } $("#formEmailRegistrationContinue").click(function(e) { ... });
- Section FormChooseCountry: These functions are used to housekeep FormChooseCountry.
/* ================================================================================= FORM CHOOSE COUNTRY ================================================================================= */ function showFormChooseCountry(data) { ... } function hideFormChooseCountry() { ... } function clearFormChooseCountry() { ... } $("#formChooseCountryContinue").click(function(e) { ... });
- Section FormPublicIP: These functions are used to housekeep FormPublicIP.
/* ================================================================================= FORM PUBLIC IP ================================================================================= */ function showFormPublicIP(data) { ... } function hideFormPublicIP() { ... } function clearFormPublicIP() { ... } $("#formPublicIPContinue").click(function(e) { ... });
- Section FormWrapup: These functions are used to housekeep FormWrapup.
/* ================================================================================= FORM WRAPUP ================================================================================= */ function showFormWrapup(data) { ... } function hideFormWrapup() { ... } function clearFormWrapup() { ... }
Step 8: Insert Placeholders
Insert these Placeholders in corresponding nodes. Click here to learn how to insert a Placeholder.
- demo-country-name
- demo-country-name
- demo-public-ip
- demo-email-form-values
Step 9: Finally, make these changes
- Publish this guide to an LOB in your account.
- In the Javascript file, replace “https://testisp.yonyx.com” with your own Yonyx subdomain.
- In the Javascript file, replace “847eb630-047c-11e4-9638-bc764e10f0e8” with the LOB id where you just published the guide.
- Deploy your container app (html and javascript files) to a web server. LAMP or MAMP would work just fine during development and testing stages.
- Last but not least, email us at support@yonyx.com to let us know about your container app url, so we can whitelist it. Whitelisting is a necessary step for container apps to work.