usheru Select GTM Template

Purpose

The Usheru Select GTM Tag Template lets clients embed the Usheru Select showtime widget on film pages without custom HTML per page.

It standardizes configuration so support teams can create tags by filling a few fields:

• where to insert the widget

• which client script to load

• which movie to show

• optional language, element id, and scroll offset

The template then:

1. writes configuration to a global object

2. loads the Usheru injector helper from the CDN
   (the injector performs the DOM insertion and SPA retry)

Why a template (instead of Custom HTML)

GTM Web Custom Templates:

• provide a clean UI for non-technical users

• reduce copy/paste errors

• allow controlled script loading

• are easier to maintain at scale

Important limitation:
Web templates cannot directly modify the DOM, so the template loads an external helper (injector) to do insertion.

What the tag does when it fires

When a tag created from this template fires, it:

1. Validates required fields are present

2. Builds a config object

3. Stores it at:
   window.__usheruSelectCfg

4. Loads the injector helper:
   https://cdnstatic.usheru.com/js/usheru-select-gtm-injector.v1.0.0.js

5. Ends successfully (the injector handles the rest)

Template fields

1) Target Selector (required)

What it is:
CSS selector for the element you want to inject around or inside.

Examples:

• #film-page-main

• .movie-details

• .film-hero

Notes:

• Must match exactly one stable element on the page.

• Avoid top-level nodes like body or html (the injector blocks these for security).

2) Insert Position (required)

What it is:
Where the widget should be inserted relative to the target selector.

Allowed values:

• before — insert immediately before the target

• after — insert immediately after the target

• inside_first — insert as the first child inside the target

• inside_last — insert as the last child inside the target

3) Script Value (required)

What it is:
The client-specific Usheru script reference.

Accepted formats:

• base name: wc-testing

• base name with extension: wc-testing.js

• full URL: https://cdnstatic.usheru.com/js/wc-testing.js

• full script tag:
  <script src="https://cdnstatic.usheru.com/js/wc-testing.js"></script>

Security note:
Even if a full URL is provided, the injector will only load scripts from
https://cdnstatic.usheru.com/js/.

4) Movie ID (required)

What it is:
The movie identifier for the widget, typically IMDb style.

Format:

• must start with tt

• followed by digits
  Example: tt30144839

5) Language (optional)

What it is:
Two-letter language code to force widget localization.

Examples:

• en, es, fr, de

If blank, the widget uses default language rules.

6) Element ID (optional)

What it is:
ID assigned to the injected <where-to-watch> element. Can be used in url fragments to scroll directly to the widget

If blank, defaults to:

• usheru-select

If provided, must be a safe HTML id:

• starts with a letter

• contains letters/digits and - _ : .

7) Scroll Offset (optional)

What it is:
Pixel offset applied only when the page URL includes a matching fragment.

Example:
Client links to:
https://site.com/film/abc#usheru-select

If:

• elementId = usheru-select

• scrollOffset = 120
  then after insertion the injector will scroll to the widget and shift up by 120px (to account for sticky headers).

Accepted inputs:

• 120

• 120px

• -80

If blank or invalid, no scroll adjustment happens.

Recommended GTM variables

Support teams typically set these as GTM variables for scalability:

Script Value variable

• Lookup Table by hostname/client

• Example mapping:

  • clientA.com → wc-clientA

  • clientB.com → wc-clientB

Movie ID variable
Common sources:

• Data Layer variable if the site pushes a movie id

• URL regex extraction

• Meta tag / DOM variable
  (Depends on client integration.)

Language variable (optional)

• Static for site locale

• or derived from URL path (e.g., /es/, /en/)

Recommended triggers

Because many client sites are SPAs:

Best trigger for SPAs:
✅ Element Visibility

• CSS selector = same as Target Selector

• Fire once per page

For standard pages, use one of these triggers:

• DOM Ready if the target always exists at DOM Ready

• Custom Event if the site pushes a routing event to dataLayer

Avoid:

• Page View / Initialization triggers on SPAs (target often not ready yet)

Example tag configuration

Illustrative setup for a film page:

• Target Selector: #film-page-main

• Insert Position: inside_last

• Script Value: {{usheru_script_value}}

• Movie ID: {{usheru_movie_id}}

• Language: es

• Element ID: usheru-select

• Scroll Offset: 120

Permissions behavior (important for troubleshooting)

In GTM’s Template Editor, permissions are auto-detected from the APIs used in the Code tab. You do not manually add permissions.

Expected detected permissions:

• Inject Scripts (because the template calls injectScript)

• Access Globals (because it calls setInWindow)

• Logs to Console (optional but recommended)

If you don’t see Access Globals:

• confirm you saved the code

• confirm setInWindow is actually called in the Code tab

Troubleshooting

Tag fires but nothing appears

Most common causes:

• Target Selector doesn’t match any element

• Tag triggers too early

• Movie ID variable is empty/invalid

• Script Value is empty

Fix:

1. Confirm selector exists on the page.

2. Switch trigger to Element Visibility.

3. Inspect window.__usheruSelectCfg to confirm values are correct.

Script loads but widget doesn’t render

Likely causes:

• insertion location hides widget due to layout/CSS

• wrong movie ID

• upstream availability missing for that ID

Fix:

• Find the inserted <where-to-watch> in DOM and confirm placement.

• Verify the movie ID for that page.

Widget appears twice

Likely causes:

• two different injector tags firing

• movie ID variable changes during SPA route transitions

Fix:

• ensure only one tag per page type

• verify stable movie ID on navigation

Versioning & upgrades

The template loads a versioned injector:

usheru-select-gtm-injector.v1.0.0.js

Upgrade policy:

• new injector versions ship under a new filename

• existing versions are not modified

• support should only recommend upgrades after internal validation

Support escalation checklist

Before escalating to Engineering, collect:

1. GTM tag screenshot (values)

2. Trigger type and firing timing

3. Runtime window.__usheruSelectCfg

4. Selector location screenshot in DOM

5. Network proof of:

   • injector loading

   • resolved client script loading

6. Console errors (if any)