Snippets & tags

Snippets and tags add code to your HTML pages as they're served, without changing your repository or redeploying. Snippets insert HTML you write, such as meta tags, structured data or a banner. Tags load third-party tools such as Google Analytics or a chat widget from an ID or script URL, and can wait for visitor consent.

Snippets#

Add a snippet#

1. Open your app and choose Snippets. The page shows your page's <head> and the end of its <body>, with each snippet in the slot where it lands and the pages it's on.
2. Choose Add to head or Add to end of body. A new snippet offers starter examples you can fill it from.
3. Fill in the snippet:
   • Name: a label for you.
   • Add it: In the head (before </head>) or At the end of the body (before </body>).
   • On pages matching: which pages get it. /* means every page.
   • HTML: the markup to insert, up to 8,000 characters.
4. Choose Save.

The snippet appears on the next page load, with no redeploy. Saving your first snippet turns snippets on. To edit or remove a snippet, click it. The Snippets on checkbox at the bottom turns every snippet off or back on, and takes effect right away. Snippets are inserted in the order listed, and a page without the matching closing tag is left unchanged.

Tags#

Add a tag#

1. Open your app and choose Tags.
2. Choose Add a tool, then pick a vendor, or Custom script for any script URL.
3. Paste the vendor's ID, or for a custom script enter a Script URL (https).
4. Optionally set Fire on path (for example /checkout/*) and Consent purpose.
5. Choose Save.

The page lists each tool with the pages it fires on and its consent purpose. Click one to edit or remove it. Adding a vendor tool turns tags on. Load tags on this site turns every tool off or back on, and takes effect right away.

dply adds each vendor's standard loader and setup code before </head>. Custom scripts load async unless you turn off Load async for that tool. Up to 20 tools are used.

Consent#

Turn on Wait for consent before loading analytics and marketing tools to hold back every tool whose purpose isn't Necessary until the visitor agrees. Your consent banner then calls:

// Load every held tool
window.__dplyTags.grant();

// Or only some purposes
window.__dplyTags.grant(['analytics']);

// Withdraw consent (stops loading on later pages)
window.__dplyTags.revoke();

The choice is remembered in localStorage under dply_tag_consent, so returning visitors aren't asked again. window.__dplyTags.consent and window.__dplyTags.purposes tell you the current state. Turning consent on also turns tags on. dply doesn't provide the consent banner itself.

Custom events#

window.__dplyTags.track(name, props) sends one event to every loaded tool that supports events (Google Analytics, Tag Manager, Meta Pixel, Plausible, Clarity and Hotjar):

window.__dplyTags.track('signup', { plan: 'pro' });

Path patterns#

Paths are matched after directory URLs resolve to their index file: the home page / is /index.html, and /docs/ is /docs/index.html. Use /docs/* for a section.

In dply.yaml#

snippets:
  enabled: true
  items:
    - name: Meta
      phase: head          # head or body
      path: /*
      html: '<meta name="description" content="…">'

tags:
  enabled: true
  consent_required: true
  tools:
    - vendor: ga4          # ga4, gtm, meta, clarity, hotjar, plausible, or omit for custom
      id: G-XXXXXXXXXX
      purpose: analytics   # necessary, analytics or marketing
      path: /*
    - name: Chat
      src: https://widget.example.com/chat.js

Up to 50 snippets and 20 tools are read from the file. Once you save snippets or tags in the dashboard, the dashboard settings replace that section of the repository config. The Advanced section of each page shows what the repository declares.

Related#

• Error pages
• Bot protection
• Edge middleware: for logic beyond injecting HTML
• Caching