Skip to main content

Implementing the Wunderkind WebSDK with Google Tag Manager

Updated

This article explains how to implement Wunderkind’s WebSDK via Google Tag Manager (GTM) for ecommerce events: logIn, item, viewItem, selectItem, addToCart, emptyCart, viewCategory, viewSearch, and Custom Events. The WebSDK ships with the Wunderkind Smart Tag and becomes available on window.wunderkind.sdk once the Smart Tag loads; you do not need to install any additional scripts or packages.

Important: Fire WebSDK events only after the Wunderkind Smart Tag has loaded. SmartTag implementation is required for the WebSDK to work! This implementation prescribes the wrapper-and-listener pattern and requires all event calls use the wrapper to avoid race conditions and ensure reliability.

You can find an implementation guide for the SmartTag and Conversion pixel in GTM here.

Note: Both the item and viewItem events must fire on product detail views. They serve different purposes and both are required for optimal results.

 

GTM setup overview

You will typically configure:

  1. A single Custom HTML tag (All Pages) for the “Wunderkind WebSDK Helper” shown below (the wrapper + SDK-ready event listener).
  2. For each WebSDK event, a GTM Custom HTML tag that calls wunderkindSDK('<eventName>', { ...payload }). Map payload values using GTM Variables from your dataLayer or page context.
  3. Triggers keyed to your site’s signals (e.g., login, productDetail, add_to_cart, “category page”/“search page” conditions).

Where you see {{DLV - ...}}, substitute your actual GTM Variable names.

 

WebSDK wrapper and load listener

Because GTM tags and your site code may run before the Smart Tag finishes loading, the following helper should be added as “Wunderkind WebSDK Helper” Custom HTML tag to fire on All Pages. 

  1. Select New Tag > name it “Wunderkind WebSDK Wrapper” > and click “Choose tag type”
  2. Select “Custom HTML” as your tag type, and then paste the Wunderkind WebSDK Wrapper
  3. Update any Advanced Settings > Tag firing priority.  It’s important to set the Tag firing priority so the WebSDK Wrapper loads before the Event tags. For example, if we set the Wrapper priority to “5”, the Event tags’ priority should be 4 or below.
  4. Configure the WebSDK Wrapper to fire on All Pages with type: “Page View”

<script>

  // Add once via a Custom HTML tag on All Pages

  function wunderkindSDK(eventName, payload) {

    var sdk = window.wunderkind &&

              window.wunderkind.sdk &&

              window.wunderkind.sdk.events;

    if (sdk) {

      if (sdk[eventName]) {

        return sdk[eventName](payload);

      }

      return;

    }

    try {

      var items = JSON.parse(localStorage.getItem('wknd_web_sdk_preloaded_events'));

    } catch (e) {}

    if (Object.prototype.toString.call(items) !== '[object Array]') {

      items = [];

    }

    items.push({ eventName: eventName, payload: payload });

    localStorage.setItem('wknd_web_sdk_preloaded_events', JSON.stringify(items));

  }

  // Surface SDK-ready state to GTM as a dataLayer event

  if (!(window.wunderkind && window.wunderkind.sdk)) {

    window.addEventListener('onWunderkindWebSDKLoaded', function () {

      window.dataLayer = window.dataLayer || [];

      window.dataLayer.push({ event: 'wknd_websdk_loaded' });

    }, false);

  }

</script>

 

Events and implementation

Unless noted, values are strings. Boolean fields are explicitly noted.

Adding logIn events

  1. Create a New Tag > Custom HTML > Label it “Wunderkind LogIn Event”
  2. Copy/paste the logIn event code below. It’ll start/end with <script></script>
  3. Map the variables below to the respective data elements to populate from your data layer.  At least one of the following is needed.  Comment out or include a commented our variable depending on your implementation.
    1. email: The user’s plain text email address.
    2. emailHash: The user’s SHA256-hashed email address.
    3. espemailid: The user’s ESP email ID, if available.
  4. Set a custom Trigger for the logIn event to fire for all of the below events.  Typical signals are your login success dataLayer event or a reliable authenticated-state flag.*
    1. a session begins with a signed-in user
    2. a user signs in during a session
    3. a user completes sign-up and is recognized as signed-in. 

*GTM trigger suggestion: your login-success dataLayer event (e.g., event = loginSuccess) or an authenticated page/state condition.

Prescribed tag code (uses wrapper):

<script>

  wunderkindSDK('logIn', {

    // Provide at least one:

    email: '{{DLV - email}}'

    // emailHash: '{{DLV - email_sha256}}',

    // espemailid: '{{DLV - esp_email_id}}'

  });

</script>

 

Adding item and viewItem events

Important!: Both the item and viewItem events must fire on product detail views. They serve different purposes and both are required for optimal results—viewItem is used by Wunderkind to trigger email campaigns like product abandonment, while item supplies the product metadata our models need to personalize and optimize messaging. Both events play pivotal roles in your Wunderkind solution.

  1. Create a New Tag > Custom HTML > Label it “Wunderkind View Item Event”
  2. Copy/paste the item and viewItem event codes below. 
  3. Map the variables below to the respective data elements to populate from your data layer.  Remove commented ‘//’ for each custom variable you would like to include.
    1. item variables:
      1. id: Unique product identifier for the PDP (each product page should map to a distinct ID).
      2. imageurl: URL for a product image (fully qualified, publicly accessible).
      3. url: Canonical product page URL (strip extra query parameters where possible).
      4. copy: The product display name as it should appear in emails.
      5. category: Product type or collection (e.g., “Shirts” or “Best Sellers”).
      6. instock (boolean): Whether the item (all SKUs) is in or out of stock.
      7. excluded (boolean, optional): If true, exclude the item from all Wunderkind emails.
      8. Custom metadata (optional): Additional attributes such as rating_number, brand, etc., are allowed and should be added as extra properties.
    2. viewItem variables:
      1. item:id: Product ID that matches the id used in the item event.
      2. item:itemgroupid (required only if you run group-level catalog modules): Product group ID corresponding to the group in your product feed; may or may not match item:id.
  4. Set the Tag to fire on product detail pages (PDP) whenever a product view is rendered.

<script>

  wunderkindSDK('item', {

    id: '{{DLV - product_id}}',

    copy: '{{DLV - product_name}}',

    category: '{{DLV - product_category}}',

    url: '{{DLV - product_url_clean}}',

    imageurl: '{{DLV - product_image_url}}',

    instock: '{{DLV - product_instock}}' // "true" or "false"

    // Optional:

    // excluded: '{{DLV - product_excluded}}',

    // rating_number: '{{DLV - rating}}',

    // brand: '{{DLV - brand}}'

  });

</script>

<script>

  wunderkindSDK('viewItem', {

    'item:id': '{{DLV - product_id}}',

    // Include if applicable for your catalog setup:

    'item:itemgroupid': '{{DLV - product_group_id}}'

  });

</script>

Adding selectItem events

  1. Create a New Tag > Custom HTML > Label it “Wunderkind Select Item Event”
  2. Copy/paste the selectItem event code below. 
  3. Map the variables below to the respective data elements to populate from your data layer.  
    1. item:id: Must match the product ID used in item and viewItem.
    2. item:feedid: The selected variant’s unique SKU, corresponding to the SKU in your product feed.
    3. item:itemgroupid: Product group ID corresponding to the group in your product feed.
  4. Set a trigger for when  a user selects a specific variant (e.g., choosing size/color) so Wunderkind knows the exact SKU being considered. GTM trigger suggestion: Variant selection / attribute change dataLayer event.

Prescribed tag code (uses wrapper):

<script>

  wunderkindSDK('selectItem', {

    'item:id': '{{DLV - product_id}}',

    'item:itemgroupid': '{{DLV - product_group_id}}',

    'item:feedid': '{{DLV - sku}}'

  });

</script>

 

Adding addToCart events

  1. Create a New Tag > Custom HTML > Label it “Wunderkind Add To Cart Event”
  2. Copy/paste the addToCart event code below. 
  3. Map the variables below to the respective data elements to populate from your data layer.  
  1. item:id: Must match the product ID used in item, viewItem, and selectItem.
  1. Set a trigger for when an item is successfully added to the cart (e.g., after receiving a confirmation or when cart state updates). GTM trigger suggestion: Add-to-cart success dataLayer event.

<script>

  wunderkindSDK('addToCart', {

    'item:id': '{{DLV - product_id}}'

  });

</script>

 

Adding emptyCart events

  1. Create a New Tag > Custom HTML > Label it “Wunderkind Empty Cart Event”
  2. Copy/paste the emptyCart event code below. 
  3. Set a trigger only when the user empties a cart that currently contains items (not when simply viewing an empty cart or opening the cart drawer).

When to trigger (user experience):

  • Trigger only when the user empties a cart that currently contains items (not when simply viewing an empty cart or opening the cart drawer).

Payload fields:

  • None required.

GTM trigger suggestion: “Cart cleared” dataLayer event or a reliable condition when the cart transitions from non-empty to empty.

Prescribed tag code (uses wrapper):

<script>

  wunderkindSDK('emptyCart', {});

</script>

 

Adding viewCategory events

  1. Create a New Tag > Custom HTML > Label it “Wunderkind View Category Event”
  2. Copy/paste the viewCategory event code below. 
  3. Map the variables below to the respective data elements to populate from your data layer.  
    1. items:ids: Array of product IDs visible on the category page.
    2. page:url: Canonical category page URL (strip extraneous parameters).
  4. Set a trigger on category/collection pages when product grids are visible.  It is recommended this event also triggers for when a user lands on a search results page.  GTM trigger suggestion: Page-type “category” or post-render event when the grid and item IDs are available.

Prescribed tag code (uses wrapper):

<script>

  wunderkindSDK('viewCategory', {

    'items:ids': {{DLV - category_visible_item_ids}}, // e.g., ["item-1","item-2"]

    'page:url': '{{DLV - category_url}}'

  });

</script>

 

Adding viewSearch events*

* Required for Search Abandonment email series only.  Otherwise, the viewCategory event is recommended for Search Results pages. 

  1. Create a New Tag > Custom HTML > Label it “Wunderkind View Search Event”
  2. Copy/paste the viewSearch event code below. 
  3. Map the variables below to the respective data elements to populate from your data layer.  
    1. items:ids: Array of product IDs visible on the search results page.
    2. page:url: Full search results URL including query parameters.
  4. Set a trigger for when the user lands on a search results page.  GTM trigger suggestion: Page-type “search results” or post-render event when the grid and item IDs are available.

Prescribed tag code (uses wrapper):

<script>

  wunderkindSDK('viewSearch', {

    'items:ids': {{DLV - search_visible_item_ids}}, // e.g., ["item-1","item-2"]

    'page:url': '{{DLV - search_results_url_with_query}}'

  });

</script>

 

Custom Events

Custom events can be used to create events not listed above and that may be specific to your business.  When creating a custom event, a new eventName value must be added to the code before implementing into GTM.

  1. Create a New Tag > Custom HTML > Label it accordingly.
  2. Copy/paste the Custom event code below. Change the eventName variable’s value according to the event name you want to track.  Custom event names should follow the SDK camelCase naming conventions unless otherwise specified.
  3. Custom variables can be added (in camelCase naming convention) to the same object.
  4. Map the variables you defined to the respective data elements to populate from your data layer.  

Prescribed tag code (uses wrapper):

<script>

  wunderkindSDK('customEvent', {

    eventName: 'viewDenim',

    // Optional extra properties:

    searchQuery: '{{DLV - search_query}}'

  });

</script>

 

Testing and validation

Enable WebSDK debug logs

Run the following in your browser console, then reload. Filter console for “web sdk” to see method calls, payloads, and validation messages. The SDK blocks events with missing required fields and returns Promise<null> in those cases.

wunderkind.sdk.turnOnDebugging();

To disable logs:

wunderkind.sdk.turnOffDebugging();

Validate in Wunderkind Platform

Once live in production, confirm events at Platform → Analytics → Event Monitoring (≈2-hour reporting delay, times in EST).

GTM preview checks

  • Use GTM Preview to verify each event tag fires on the intended trigger and that payload variables are populated.
  • If deploying the Conversion Pixel, confirm the Smart Tag’s firing priority is higher so it loads first.

 

Troubleshooting

  • “SDK outside of the supported region”: If you see this in the console (after enabling debug mode) and no events dispatch, you may be testing from a location not configured for your account (e.g., VPN). If that’s unexpected, contact your Wunderkind representative.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk