Getting started

Install with a script tag

Use this for a site that has no Vite plugin or Next package: one script tag, pasted into your pages. Passback adds its button to every page that carries the tag, and each comment is filed in the tracker you connected to the site.

Before you start

• Your site is added in the dashboard, with the addresses it is served from.
• A tracker is connected to the site. The page Connect a tracker shows how.

Get your tag

In the dashboard, open your site and choose Install. It shows your site key, your script tag with a button to copy it, and the allowed origins. The tag has this shape, with your own addresses where the capitals are:

<script
  src="WIDGET_SCRIPT_ADDRESS"
  data-passback-endpoint="API_ADDRESS/v1/ingest/SITE_KEY"
  data-passback-screenshots="true"
  async
></script>

Always copy the tag from the dashboard: the addresses in it are the ones your Passback account uses.

Paste it

Paste the tag into the <head> of every page that should show the button, or just before </body>. Put it only where you want the button: for example in the template of your staging site and not in the one of your production site. The button appears on every page that carries the tag.

Where the tag goes in your framework

The tag is plain HTML. Put it in the file that produces the <head> of your pages:

• Plain HTML or a static site generator: the template or layout that holds <head>.
• Angular: src/index.html.
• webpack: the HTML template that HtmlWebpackPlugin reads.
• SvelteKit: src/app.html.
• Astro: the layout component that renders <head>.
• Nuxt: app.head.script in nuxt.config.ts, as in the first block below.
• React Router: the Layout in app/root.tsx, inside <head>, as in the second block below.

For Nuxt, add one entry:

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'WIDGET_SCRIPT_ADDRESS',
          'data-passback-endpoint': 'API_ADDRESS/v1/ingest/SITE_KEY',
          'data-passback-screenshots': 'true',
          async: true,
        },
      ],
    },
  },
});

For React Router, render the same tag between the charset meta element and <Meta />:

<head>
  <meta charSet="utf-8" />
  <script
    src="WIDGET_SCRIPT_ADDRESS"
    data-passback-endpoint="API_ADDRESS/v1/ingest/SITE_KEY"
    data-passback-screenshots="true"
    async
  />
  <Meta />
</head>

The advice above stands: put the tag only where the button belongs. In these frameworks, render it only for the staging build, and let the framework's own build-mode or environment check decide. Copy the addresses from the dashboard.

For installation with the Vite plugin, see SvelteKit, Astro, Nuxt or React Router.

Allowed origins

Passback accepts comments only from the addresses listed under Allowed origins in the Install section. An address is the scheme, the host and, if there is one, the port the page is served from, and nothing else: https://staging.example.com or http://localhost:3000. A site lists up to 10. Change the list and click Save origins. A comment from an address that is not on the list is refused, and the pin shows that it was not sent.

Screenshots

data-passback-screenshots="true" lets a comment carry a picture of the page. Pictures need the Premium plan. The picture is rendered from the page, with private fields blacked out. The browser does not ask you to share your screen.

If the capture or the upload fails, the comment is still sent, without the picture.

The widget script loads the other two files it needs, collector.js and shot.js, from the address it was loaded from, so keep the three files together. If shot.js is served from somewhere else, add data-passback-shot with its address.

Content Security Policy

If your site sends a Content Security Policy, allow these:

• script-src https://cdn.passback.dev, for the three files.
• connect-src https://api.passback.dev, for sending comments and pictures.
• style-src 'unsafe-inline', because the widget adds one style element to its own box and cannot carry a nonce.

If the addresses in the tag from the dashboard differ, use those instead.

Check it works

1. Open one of your allowed addresses, with the tag in place. The Passback button appears in the bottom right corner.
2. Leave a comment as the page Your first comment describes. When it is sent, it appears as a new item in your tracker.

To check the tracker without a page, use File a test comment in the Relay section of the dashboard.

Next: Your first comment