Developer docs

Google Tag Manager

The DeploySeal tag template installs the widget through Google Tag Manager, for sites whose scripts are managed in a GTM container rather than in the page layout. It loads the same widget as the snippet, from the same address, and tells the site page it came from the template, so a container change is all it takes. The template is open source at github.com/deployseal/gtm-template.

How it configures the widget

A GTM template cannot put attributes on the script tag it inserts, so it cannot write the snippet's data-ds-* attributes. Instead the template sets a configuration object, window.__deploysealConfig, holding the same values, and only then inserts the plain widget tag; the widget reads the object exactly as it would read the attributes. If the object is already set, because the snippet or a plugin got there first, the template leaves it alone and inserts nothing, so a page never ends up with two widgets.

// What the tag does, in the page's terms
window.__deploysealConfig = {
  dsSiteKey: 'ls_••••••••••••••••••••••••••••••••••••',
  dsEnvironment: 'staging',
  dsBuild: '{{DeploySeal build}}',
  dsInstaller: 'gtm-template/1.0.0',
}
// then
<script async src="https://cdn.deployseal.com/ds-widget.js"></script>

The template asks GTM for two permissions only: to inject scripts from https://cdn.deployseal.com/, and to read and write __deploysealConfig (and read __deployseal) on the window.

Import the template

Until the template is listed in the Community Template Gallery, import it from the repository:

1. Download template.tpl from the latest release.
2. In your container open Templates → Tag Templates → New, then the three-dot menu at the top right, Import, and choose the file. Press Save and close the editor.
3. Open Tags → New → Tag Configuration, choose DeploySeal widget under Custom, and fill in the fields below.
4. Give it the trigger described under Triggers, check it in Preview, then Submit the container.
5. Load a page on the environment and watch its card on the site page turn Live.

Remove any pasted snippet from those pages once the tag is live; otherwise the site page warns that two install paths are live on the environment.

Fields

Triggers

• Fire only on the environment's hostnames. Use a Page View trigger that fires on Some Page Views where Page Hostname equals your staging host, or matches a RegEx for several. A container is usually shared by staging and production, so an All Pages trigger would put the widget on your live site.
• One tag per environment. Every environment has its own key, and the key decides where evidence lands. Create one tag for staging and one for UAT, each with its own hostname trigger, or a single tag whose Site key is a Lookup Table on Page Hostname with an empty default:

Variable type:   Lookup Table
Input variable:  {{Page Hostname}}
  staging.example.com   →  ls_…  (the Staging key)
  uat.example.com       →  ls_…  (the UAT key)
Default value:   (leave empty)

With an empty default the tag has no key on any other hostname, so it fails there and loads nothing. Set the Environment field the same way, from a second Lookup Table.

Do not fire the tag on production unless a campaign is testing production and the production environment in DeploySeal lists that origin. The widget answers only on registered origins and shows itself only to invited testers, but it is still a script every visitor downloads.

The build marker variable

The readiness report compares the release a campaign declares with the build the widget observed, so the marker must change with every deployment. Have your deploy write it somewhere GTM can read and point a variable at it: a Data Layer variable your page pushes, a JavaScript variable, or a DOM Element variable reading <meta name="ds-build" content="a1b2c3d"> (which the widget also reads on its own when the field is empty). Then set the Build marker field to that variable, for example {{DeploySeal build}}. Prefer the git SHA; the build marker rules are the same for every install path.

Troubleshooting