Implementing the Wunderkind WebSDK with Tealium

This article explains how to implement Wunderkind’s WebSDK with Tealium iQ Tag Management 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 a wrapper-and-listener pattern for all event calls to avoid race conditions and ensure reliability.

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

Note: On product detail pages (PDP), trigger both item and viewItem together in the same Tealium tag. They serve different purposes and both are required for best results—viewItem triggers behavior (e.g., product abandonment campaigns), while item supplies product metadata our models use for personalization. Both events are pivotal to your Wunderkind solution.

Tip: Do not include <script> tags inside the template’s JS block. If you prefer to avoid editing tag templates, you may implement each event as a JavaScript Code Extension scoped to a Custom Load Rule representing the event.  However, this guide uses Custom Container tags as requested.

In this guide, all WebSDK events are implemented as Tealium Custom Tags (Tealium Custom Container), since Tealium does not have a template for WebSDK events.

WebSDK wrapper and load listener

Add the wrapper once so event calls are safe and buffered until the SDK is ready. In Tealium, implement this as a JavaScript Code Extension (see setup below).

<script>

// Add once via a Tealium JavaScript Code Extension (All Pages)

// Wrapper that caches calls until the SDK is available

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));

}

// Optional: listen for SDK load event if Smart Tag loads after page code

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

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

    // Available for debugging/logging if needed

    // e.g., console.log('Wunderkind WebSDK ready');

  }, false);

}

</script>

• You don’t need to “await” WebSDK calls; they are asynchronous fire-and-forget.
• Ensure the Smart Tag previously implemented loads before event tags. 

Setup in Tealium (Extension):

1. Extensions → Add Extension → JavaScript Code.
2. Scope: All Pages (DOM Ready is typical).
3. Paste the wrapper code above. Save and publish.

Adding a logIn event

1. Under ‘iQ Tag Management’ go to the ‘Tags’ section.  Search for ‘Custom Container’ tag in the tag marketplace and add a Custom Container tag.
2. Name the new tag “Wunderkind Log In Event”.
3. Use UDO variables and map to the following fields in the logIn code.  The Custom Container tag supports custom data mappings you choose in the mapping toolbox.  Choose one and only one variable to map.  Ensure the comment indicator ‘//’ has been removed where applicable.
   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. In the tag’s Template → within u.send (or main send block), paste the JS event call for logIn using the wrapper.  Make the changes to ensure that the fields reference the values that will populate from the data layer.
5. Set Custom Container to load when a session begins with a signed-in user, when a user signs in during a session, or upon sign-up if the user is recognized as signed-in.
6. Save and publish.

wunderkindSDK('logIn', {

  // Provide at least one:

  email: b.user_email

  // emailHash: b.user_email_sha256,

  // espemailid: b.user_esp_email_id

});

Product Details Page (PDP) View: item + viewItem

Tealium container setup:

1. Under ‘iQ Tag Management’ go to the ‘Tags’ section.  Search for ‘Custom Container’ tag in the tag marketplace and add a Custom Container tag.
2. Name the new tag “Wunderkind View Item Event”.
3. Use UDO variables and map to the following fields in the item and viewItem code.  The Custom Container tag supports custom data mappings you choose in the mapping toolbox.  Ensure the comment indicator ‘//’ has been removed where applicable.
   1. item (required unless noted): 
      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. In the tag’s Template → within u.send (or main send block), paste the JS event call for item and viewItem using the wrapper.  Make the changes to ensure that the fields reference the values that will populate from the data layer.
5. Set Custom Container to load on product detail pages when product content renders. 
6. Save and publish.

// item metadata

wunderkindSDK('item', {

  id: b.product_id,                // map to your UDO variable names

  copy: b.product_name,

  category: b.product_category,

  url: b.product_url,

  imageurl: b.product_image_url,

  instock: b.product_instock       // "true" or "false"

  // Optional:

  // excluded: b.product_excluded,

  // rating_number: b.product_rating,

  // brand: b.product_brand

});

// viewItem signal

wunderkindSDK('viewItem', {

  'item:id': b.product_id,

  // Include if applicable:

  'item:itemgroupid': b.product_group_id

});

Adding a selectItem event

1. Under ‘iQ Tag Management’ go to the ‘Tags’ section.  Search for ‘Custom Container’ tag in the tag marketplace and add a Custom Container tag.
2. Name the new tag “Wunderkind Select Item Event”.
3. Use UDO variables and map to the following fields in the selectItem code.  The Custom Container tag supports custom data mappings you choose in the mapping toolbox.
   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. In the tag’s Template → within u.send (or main send block), paste the JS event call for selectItem using the wrapper.  Make the changes to ensure that the fields reference the values that will populate from the data layer.
5. Set Custom Container to load when a user selects product attributes (e.g., size, color) so Wunderkind knows which SKU is being considered.
6. Save and publish.

wunderkindSDK('selectItem', {

  'item:id': b.product_id,

  'item:itemgroupid': b.product_group_id,

  'item:feedid': b.sku_selected

});

Adding a addToCart event

1. Under ‘iQ Tag Management’ go to the ‘Tags’ section.  Search for ‘Custom Container’ tag in the tag marketplace and add a Custom Container tag.
2. Name the new tag “Wunderkind Add to Cart Event”.
3. Use UDO variables and map to the following fields in the addToCart code.  The Custom Container tag supports custom data mappings you choose in the mapping toolbox.
   1. item:id: Must match the product ID used in item and viewItem.
4. In the tag’s Template → within u.send (or main send block), paste the JS event call for selectItem using the wrapper.  Make the changes to ensure that the fields reference the values that will populate from the data layer.
5. Set Custom Container to load when a user successfully adds an item to the cart
6. Save and publish.

wunderkindSDK('addToCart', {

  'item:id': b.product_id

});

Adding a emptyCart event

1. Under ‘iQ Tag Management’ go to the ‘Tags’ section.  Search for ‘Custom Container’ tag in the tag marketplace and add a Custom Container tag.
2. Name the new tag “Wunderkind Empty Cart Event”.
3. In the tag’s Template → within u.send (or main send block), paste the JS event call for emptyCart using the wrapper.  
4. Set Custom Container to load only when a cart that previously had items is emptied, not when merely viewing an empty cart/drawer.
5. Save and publish.

wunderkindSDK('emptyCart', {});

Adding a viewCategory event

1. Under ‘iQ Tag Management’ go to the ‘Tags’ section.  Search for ‘Custom Container’ tag in the tag marketplace and add a Custom Container tag.
2. Name the new tag “Wunderkind View Category Event”.
3. Use UDO variables and map to the following fields in the addToCart code.  The Custom Container tag supports custom data mappings you choose in the mapping toolbox.
   1. items:ids: Array of product IDs visible on the category page.
   2. page:url: Canonical category page URL (strip extraneous parameters).
4. In the tag’s Template → within u.send (or main send block), paste the JS event call for viewCategory using the wrapper.  Make the changes to ensure that the fields reference the values that will populate from the data layer.
5. Set Custom Container to load when a user views a category/collection pages where product grids are visible.  It is recommended this event also triggers for when a user lands on a search results page.  
6. Save and publish.

wunderkindSDK('viewCategory', {

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

  'page:url': b.category_url

});

Adding viewSearch event

1. Under ‘iQ Tag Management’ go to the ‘Tags’ section.  Search for ‘Custom Container’ tag in the tag marketplace and add a Custom Container tag.
2. Name the new tag “Wunderkind View Category Event”.
3. Use UDO variables and map to the following fields in the viewSearch code.  The Custom Container tag supports custom data mappings you choose in the mapping toolbox.
   1. items:ids: Array of product IDs visible on the search results page.
   2. page:url: Full search results URL including query parameters.
4. In the tag’s Template → within u.send (or main send block), paste the JS event call for viewSearch using the wrapper.  Make the changes to ensure that the fields reference the values that will populate from the data layer.
5. Set Custom Container to load when a user views a search results pages only
6. Save and publish.

wunderkindSDK('viewSearch', {

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

  'page:url': b.search_results_url_with_query

});

Custom Events

1. Under ‘iQ Tag Management’ go to the ‘Tags’ section.  Search for ‘Custom Container’ tag in the tag marketplace and add a Custom Container tag.
2. Name the new tag according to the event you are tracking.
3. Use UDO variables and map to the fields you would like to add to your event.  The Custom Container tag supports custom data mappings you choose in the mapping toolbox.
4. 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.
5. Set Custom Container to load in accordance with the event you want to track.
6. Save and publish.

wunderkindSDK('customEvent', {

  eventName: 'viewDenim',     // replace with your event name

  // Optional properties:

  searchQuery: b.search_query

});

Testing and validation

Enable WebSDK debug logs:

wunderkind.sdk.turnOnDebugging();

• Reload and filter console for “web sdk” to see method calls, payloads, and validation messages. Events with missing required fields are blocked and return Promise.

Turn off logs:

wunderkind.sdk.turnOffDebugging();

Tealium publish checks:

• Use Tealium iQ Preview/Publish workflow to verify each tag’s Load Rule and payload values are present.

Smart Tag verification:

• Confirm the Wunderkind Smart Tag is bundled and loading on all pages so window.wunderkind.sdk is available before event tags run.

Troubleshooting

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

Validate in Wunderkind Platform

• In production, confirm conversions in Wunderkind Platform → Analytics → Event Monitoring (≈2-hour delay; times in EST).

Sources

• Tealium Integration Guide
• Tealium Custom Container Tag
• Tealium Javascript Code Extension
• Tealium Universal Data Object