Embed Pega content on your website with less effort by following best practices for mashups. Building a guidelines-compliant application results in less issues and saves you time on troubleshooting and fixing errors.

Use the following guidelines and best practices when you create mashups:

• Specify the host page URL as the trusted origin on the application rule form so that the mashup host-gadget communication works as intended.

  1. In the header of Dev Studio, click the name of the application, and then click Definition.

  2. Click the Integration&security tab, and then in the Mashup security section, add the URL of your web page to the allow list for the application by specifying the host, port and protocol.

     For example: https://www.example.com:443
     Note: You can skip the port number for well-known ports, such as port 80, which identifies HTTP traffic for a web server, and port 443 for HTTPS traffic.

• Do not load your mashup with an XHTML Strict doctype because most browsers do not support XHTML.

• Ensure that the Pega software versions match when you embed a mashup in a Pega Platform application.

  For example: For example, do not embed a Pega Platform 7.2 gadget in a Pega Platform 8.1.4 application.

• Ensure that you disable SameSite cookies by clearing the CSRF (Cross-site request forgery) token.

  For more information, see Enabling and configuring Cross-Site Request Forgery settings.

• If you use mashups and the CSRF token is active, add the domains where the mashup scripts are embedded to the Allowed referrers field on the Cross-Site Request Forgery landing page.

  For more information, see Enabling and configuring Cross-Site Request Forgery settings.

• If you enable encryption while generating a mashup and want to pass custom parameters or dynamic parameters from the host page, either mention all the required parameters in the mashup channel while generating the mashup code, or use the following pega.web.api.setAuthenticationParameters API before the system loads the mashup on the web page:

  <script src ='http://samplehost:port /prweb/IAC/?pzuiactionzzz=CXtpbn1iaXB1MndsRVBEMGFReHpjeWEwS1k1ZlNycFcvRUVBQTZPYUxrSjNoL0ZOdnV2QjV4b3ZR%0ARWZuL3ZKdGV5TEtK’ ></script>
   
  <script>
  function loadGadget() {
                  pega.web.api.setAuthenticationParameters("PegaGadget", {
  UserIdentifier: "XXXX",
  Password: btoa("YYYYY"),
  customParam1: “Value1”,
  customParam2: “Value2”
  });      
  pega.web.api.doAction("PegaGadget", "load");
  };
            
   </script>
                  <button onclick="loadGadget()">Load the gadget</button>
  <div id='PegaGadget'
  data-pega-encrypted ='true' 
  data-pega-encrypted-hash = 'pzuiactionzzz=CXtpbn1wU3DFd1FSaWhOdEhlVjRTZjZ2ZncrWDlDN3dkYmVoL2hNMFkxWDIyTGJJM3hoYkZFTktJ%0Ac1ZTSWlJeVY5U3ZobmNuUDdhWWY0VEZxMlBFVWp1dEZ1ckkwK2JoQzltNm4rckxhRGFKbVd6YzJ4%0Acnd3SUlHTkROdmI4VlNiTlQ4TFBBWnYwa1BQWGRyUldZb3dhRU00S1BXMnpaa1hTSEwvSmdaYjhp%0ARTlxZkIzYlBab2FKU2V0bUlqaUpkSlhJN2I%3D' 
  data-pega-gadgetname ='PegaGadget' 
  data-pega-action ='createNewWork' 
  data-pega-action-param-classname ='PegaSample-Work’
  data-pega-action-param-flowname ='pyStartCase' 
  data-pega-isdeferloaded ='true'
  data-pega-resizetype ='stretch' 
  data-pega-url ='http://samplehost:port/prweb'></div>  
  

  Note: The pega.web.api.setAuthenticationParameters API sends the client-side dynamic parameters as part of the query parameters, not in the encrypted hash which is generated on the server when you generate the mashup code.

• Ensure that your mashup displays as intended by not using the nosniff setting.

  The nosniff response header prevents Google Chrome and Internet Explorer from trying to mime-sniff the content-type of a response away from the content-type that the server declares.
  For example: The nosniff parameter in the following sample code breaks the mashup functionality:

  {"X-Content-Type-Options":"nosniff","X-XSS-Protection":"1; mode=block","Strict-Transport-Security":"max-age=31536000; includeSubDomains"} 

• Do not use the APR connector protocol in a Tomcat container because the protocol returns an empty POST body to the Pega Platform engine. Instead, use the correct NIO or NIO2 protocol for the Tomcat version.

  For more information, see the Troubleshooting Error adopting from POST body SAXParseException: Content is not allowed in Prolog article on Pega Community.

• Best practices for using multiple mashups

  Learn about how Pega Platform supports semantic and non-semantic URLs, and discover the best practices for loading multiple mashups to ensure that your mashups work as intended.