Skip to content

Delivery Options

Jump to bottom
Ryan Wold edited this page Apr 19, 2024 · 17 revisions

Touchpoints can be delivered to users in a few different ways:

  1. On the Touchpoints website
  2. On your Website
    1. Blue primary button, when click opens a modal
    2. A custom element, when clicked, opens a modal
    3. Embedded inline within an existing element

On the Touchpoints website

By default, a Touchpoints form is available via the Touchpoints website. The URL to the form (example: https://touchpoints.app.cloud.gov/touchpoints/40/submit) is shared with a user, who clicks on the link, arrives at the Touchpoints site, and completes the form.

On your Website

Open a modal with a primary blue button, in the bottom, right corner of the website

A Touchpoints form can be included on an existing web property by including it via a <script> tag. The "Modal" option renders a standard USWDS styled button in the bottom right corner of an existing web page. When the button is clicked, a modal element containing the Touchpoints form is displayed. The form can be completed and submitted from within the modal window.

In Touchpoints:

  1. Create a Form, selecting Modal for the Delivery Method
  2. Publish the form
  3. Copy the <script> on the Form page

On your website:

  1. Add the <script> above to your website

When the script is include on your website page, it will fetch the specific forms's javascript from the Touchpoints server and

  1. render a button in the bottom right corner of the webpage and
  2. render the Touchpoints form into a modal element on the webpage

Clicking the button makes the modal appear, and the user can then complete and submit the Touchpoints forms.

Open a modal by clicking a custom button element

This image shows where to select a delivery method for a form and where to set an Element Selector, if desired.

A Touchpoints form can be included on an existing web property by including it via a <script> tag. The "Custom button modal" option requires the webmaster to add a custom element to an existing web page that has a specified id tag (example: <button id="open-my-touchpoint">Open the Touchpoints form in a Modal</button>). When the custom button is clicked, a modal element containing the Touchpoints form is displayed. The form can then be completed and submitted from within the modal element.

In Touchpoints:

  1. Create a Touchpoint, selecting Custom Modal Button for the Delivery Method, and for Element Selector, enter the html id of an element on your webpage, example: touchpoint-button (see below).
  2. Publish the form
  3. Copy the <script> on the Touchpoints Form page

On your website:

  1. Create a clickable html element with an id, example: <button id="touchpoint-goes-here"></button>
  2. Add the Touchpoints <script>

The script will load on your website, fetch the specific form's javascript from the Touchpoints web server and render the form into a hidden modal element that becomes visible when clicking on the Custom Button on your page with an id that matches the forms "Element Selector."

Embed the form inline on the website

A Touchpoints form can be included on an existing web property by including it via a <script> tag. The "Inline" option requires the webmaster to add a custom element to an existing web page that has a specified id tag (example: <div id="insert-my-touchpoint-form-here">Javascript is required to see the form</div>). When the page is rendered, the form is inserted into the custom element. The form can be completed and submitted from where it is rendered on the existing page.

In Touchpoints:

  1. Create a Form, selecting Inline for the Delivery Method, and for Element Selector, enter the html id of an element on your webpage, example: form-goes-here (see below).
  2. Publish the form
  3. Copy the <script> on the Form page

On your website:

  1. Create an html element with an id, example: <div id="form-goes-here"></div>
  2. Add the <script> to your website

The script will load on your website, fetch the specific forms's javascript from the Touchpoints server and render the form into the html element on your page with an id that matches the form's "Element Selector"

Considerations when using a Touchpoints form on a non-public or internal website

These considerations also apply when client-side customizations are made by clients, by modifying any aspect of the Touchpoints provided javascript (.js).

Touchpoints is most often used for public-facing websites, and how to deliver a form is described here.

Typically, <script src="https://touchpoints.app.cloud.gov/...> is used to embed a Touchpoints form on an existing web page.

Given additional security considerations for internal, non-public websites (aka intranet sites) should take additional steps when using Touchpoints.

These steps are relatively technical, so please consider working with your web or development team, and reach out to the Touchpoints/Feedback Analytics team for any questions and support.

Steps
  • Create the Touchpoints form as you normally would, and select a Delivery option apart from the Touchpoints-hosted option. (You should have a script tag with the link)
  • Visit the https://touchpoints.app.cloud.gov/... link directly. It will render the javascript that is executed to render the Touchpoints form on your page. Copy that code.
  • That code should be hosted on your website. For example, in /assets/javascripts/touchpoints_form.js on the intranet site. And the script tag should reference that local version of the file.

The result of this is that the non-public site will be able to render the Touchpoints form without making a call out to the public touchpoints.app.cloud.gov website.

When a response is submitted, it will be transmitted from the internal website to the public Touchpoints website.

Content Security Policy (CSP) considerations

Federal websites should be implementing CSP policies to improve security posture.

A minimal CSP tag that a website can place within the <head> tag.

<meta http-equiv="Content-Security-Policy" content="
  script-src 'self' https://touchpoints.app.cloud.gov;
  img-src 'self' https://touchpoints.app.cloud.gov;
  connect-src 'self' https://touchpoints.app.cloud.gov;
">

And here's a description of what each directive does:

  • script-src 'self' https://touchpoints.app.cloud.gov; This directive specifies that scripts can only be loaded from the same origin ('self'). This helps mitigate XSS (Cross-Site Scripting) attacks by preventing scripts from external sources.
  • img-src 'self' https://touchpoints.app.cloud.gov; This directive restricts the loading of images to the same origin ('self'). This helps prevent malicious image sources from being loaded and potentially executing harmful code.
  • connect-src 'self' https://touchpoints.app.cloud.gov; https://subdomain.example.com: This directive restricts the URLs that can be loaded via various network-related APIs such as fetch(), XMLHttpRequest, etc. Requests are allowed from the same origin ('self') and from https://subdomain.example.com.

Ultimately, be sure to check with your web or technical teams on the appropriate CSP tags for your website.

⚠️ Touchpoints requires javascript to be enabled in the browser.

If javascript is disabled in the browser, the user experiences the following:

  • For the Touchpoints hosted version, the user sees a message indicating Javascript is required.
  • For the Modal version, the user would not see the modal rendered
  • For the Custom button Modal, the user may click the button and not see any action
  • For the Inline option, the user would not see the form inserted into the element on the page
Clone this wiki locally