GTM MANUAL SETUP GUIDE
======================

For most users, the bundled template (Main Settings → GTM Container ID →
"Download gtm-template.json") is the fastest path: import it in Merge mode,
set the pixel-code constants, publish, done.

This document covers the manual path — useful if you cannot import the JSON
template (workspace permission errors, locked containers) or you want to
understand exactly what the import does so you can audit the tags before
shipping them.


PREREQUISITES
-------------

In your Meta Business Suite → Events Manager → your Pixel → Settings → Event
Setup, turn OFF the toggle for "Track Events Automatically Without Code".
This plugin handles all event sending; leaving Meta's auto-tracking on will
double-count events on top of the plugin's deduplicated event_id stream.

In your GTM container, pause or delete any auto-created tags that start with
FB_. Since you will be creating your own tags, only those should be active.


STEP 1 — DATA LAYER VARIABLES
-----------------------------

Create the following Data Layer Variables (Variable Type: Data Layer Variable):

* DLV - event_id                       — Data Layer Variable Name: event_id
* DLV - ecommerce                      — Data Layer Variable Name: ecommerce
* DLV - Hashed Email                   — Data Layer Variable Name: user_data.email
* DLV - ecommerce.currency             — Data Layer Variable Name: ecommerce.currency
* DLV - ecommerce.value                — Data Layer Variable Name: ecommerce.value
* DLV - ecommerce.items                — Data Layer Variable Name: ecommerce.items
* DLV - ecommerce.transaction_id       — Data Layer Variable Name: ecommerce.transaction_id
* DLV - ecommerce.item_list_name       — Data Layer Variable Name: ecommerce.item_list_name
* DLV - ecommerce.shipping_method      — Data Layer Variable Name: ecommerce.shipping_method
* DLV - ecommerce.payment_method       — Data Layer Variable Name: ecommerce.payment_method


CONSTANT VARIABLES
------------------

One placeholder per platform — every Meta tag, every TikTok tag, and every
GA4 tag references these, so rotating IDs requires only one edit:

* CONST - Meta Pixel ID          — your Meta Pixel ID (e.g. 1234567890123456)
* CONST - TikTok Pixel Code      — your TikTok Pixel Code from TikTok Events Manager
* CONST - GA4 Measurement ID     — your GA4 Measurement ID (e.g. G-XXXXXXXXXX)


PINTEREST CUSTOM JS VARIABLE
----------------------------

Only needed if you actually use Pinterest. (Meta's modern Pixel template
auto-converts the GA4 ecommerce schema, so a Meta-side CJS is no longer
required.)

* CJS - Pinterest Contents

  function() {
    var ecommerce = {{DLV - ecommerce}};
    if (!ecommerce || !ecommerce.items) return undefined;
    return ecommerce.items.map(function(item) {
      return {
        id: item.id || item.item_id,
        quantity: item.quantity || 1,
        item_price: item.price
      };
    });
  }


STEP 2 — TRIGGERS
-----------------

Create the following triggers using the Custom Event type:

* CE - PageView Meta        — Event name: page_view_meta
* CE - View Item            — Event name: view_item
* CE - Add to Cart          — Event name: add_to_cart
* CE - Begin Checkout       — Event name: begin_checkout
* CE - Purchase             — Event name: purchase
* CE - View Item List       — Event name: view_item_list
* CE - View Cart            — Event name: view_cart
* CE - Select Item          — Event name: select_item
* CE - Add Shipping Info    — Event name: add_shipping_info
* CE - Add Payment Info     — Event name: add_payment_info
* CE - Search               — Event name: search


STEP 3 — TAGS
-------------

A) META TAGS

Prerequisite: install the "Meta Pixel" template by facebook from the GTM
Community Template Gallery. (The older "Facebook Pixel" template under
facebookarchive is deprecated and will not import.)

For every Meta tag, set these common fields the same way:

* Pixel ID:                  {{CONST - Meta Pixel ID}}
* Event ID:                  {{DLV - event_id}}   (required for dedup)
* Use GA4 Ecommerce data:    enabled              (auto-converts items[] → contents[])
* Consent:                   enabled              (respects Consent Mode v2)
* Send page view:            leave default

Then per tag, only the Event Name and Trigger change:

* Meta - PageView            → standard PageView,         Trigger: CE - PageView Meta
* Meta - ViewContent         → standard ViewContent,      Trigger: CE - View Item
* Meta - AddToCart           → standard AddToCart,        Trigger: CE - Add to Cart
* Meta - InitiateCheckout    → standard InitiateCheckout, Trigger: CE - Begin Checkout
* Meta - Purchase            → standard Purchase,         Trigger: CE - Purchase
* Meta - AddPaymentInfo      → standard AddPaymentInfo,   Trigger: CE - Add Payment Info
* Meta - ViewCategory        → custom event "ViewCategory", Trigger: CE - View Item List
                               (Meta has no standard ViewCategory event)


B) PINTEREST TAGS

Prerequisite: install the "Pinterest Tag" template from the GTM Community
Template Gallery. The Data Layer Variables and CJS - Pinterest Contents from
Step 1 are reused here.

Standard custom-parameter set used by most Pinterest tags:
  event_id      → {{DLV - event_id}}
  value         → {{DLV - ecommerce.value}}
  currency      → {{DLV - ecommerce.currency}}
  contents      → {{CJS - Pinterest Contents}}
  content_ids   → {{CJS - Pinterest Contents}}  (Pinterest extracts ids from the array)

Create the following tags:

* Pinterest - PageView
    Tag ID:           your Pinterest Tag ID
    Hashed Email:     {{DLV - Hashed Email}}
    Event to Fire:    page_visit
    Custom Params:    event_id → {{DLV - event_id}}
    Trigger:          CE - PageView Meta

* Pinterest - ViewContent
    Tag ID:           your Pinterest Tag ID
    Hashed Email:     {{DLV - Hashed Email}}
    Event to Fire:    view_content
    Custom Params:    standard set above
    Trigger:          CE - View Item

* Pinterest - AddToCart
    Event to Fire:    add_to_cart
    Custom Params:    standard set
    Trigger:          CE - Add to Cart

* Pinterest - InitiateCheckout
    Event to Fire:    initiate_checkout
    Custom Params:    standard set
    Trigger:          CE - Begin Checkout

* Pinterest - Purchase
    Event to Fire:    checkout
    Custom Params:    standard set
    Trigger:          CE - Purchase

* Pinterest - ViewCategory
    Event to Fire:    view_category
    Custom Params:
      event_id     → {{DLV - event_id}}
      content_name → {{DLV - ecommerce.item_list_name}}
    Trigger:          CE - View Item List


C) TIKTOK TAGS

Prerequisite: install the "TikTok Pixel" template by tiktok from the GTM
Community Template Gallery.

For every TikTok tag, set these common fields:

* Pixel Code:                {{CONST - TikTok Pixel Code}}
* Event ID:                  {{DLV - event_id}}    (required for dedup)
* Use enhanced ecommerce:    enabled               (auto-converts items[] → contents[])
* Consent:                   enabled

Event names below are TikTok's standard event roster. TikTok has no
ViewCategory event, so the plugin maps ViewCategory to Pageview server-side
and the template fires Pageview for the View Item List trigger:

* TikTok - Pageview                  → Pageview,            CE - PageView Meta
* TikTok - ViewContent               → ViewContent,         CE - View Item
* TikTok - AddToCart                 → AddToCart,           CE - Add to Cart
* TikTok - InitiateCheckout          → InitiateCheckout,    CE - Begin Checkout
* TikTok - AddPaymentInfo            → AddPaymentInfo,      CE - Add Payment Info
* TikTok - CompletePayment           → CompletePayment,     CE - Purchase
* TikTok - Search                    → Search,              CE - Search
* TikTok - Pageview (View Item List) → Pageview,            CE - View Item List


D) GA4 TAGS

Prerequisite: have your Measurement ID (starts with G-) from your GA4
property. The Data Layer Variables from Step 1 are reused.

First, create the main configuration tag:

* GA4 - Google Tag (Configuration)
    Tag Type:   Google Analytics > Google Tag
    Tag ID:     your GA4 Measurement ID
    Important:  Uncheck "Send a page view event when this configuration loads"
                — we send page_view manually below.
    Trigger:    All Pages

Then create event tags. All GA4 event tags use:
    Tag Type:         Google Analytics > GA4 Event
    Configuration Tag: GA4 - Google Tag (Configuration)

* GA4 - Event - PageView
    Event Name:       page_view
    Trigger:          CE - PageView Meta

* GA4 - Event - ViewItem
    Event Name:       view_item
    Params:           currency, value, items (from DLV)
    Trigger:          CE - View Item

* GA4 - Event - AddToCart
    Event Name:       add_to_cart
    Params:           currency, value, items
    Trigger:          CE - Add to Cart

* GA4 - Event - BeginCheckout
    Event Name:       begin_checkout
    Params:           currency, value, items
    Trigger:          CE - Begin Checkout

* GA4 - Event - Purchase
    Event Name:       purchase
    Params:           transaction_id, currency, value, items
    Trigger:          CE - Purchase

* GA4 - Event - ViewItemList
    Event Name:       view_item_list
    Params:           item_list_name, items
    Trigger:          CE - View Item List

* GA4 - Event - ViewCart
    Event Name:       view_cart
    Params:           currency, value, items
    Trigger:          CE - View Cart

* GA4 - Event - SelectItem
    Event Name:       select_item
    Params:           items
    Trigger:          CE - Select Item

* GA4 - Event - AddShippingInfo
    Event Name:       add_shipping_info
    Params:           currency, value, shipping_tier (= shipping_method), items
    Trigger:          CE - Add Shipping Info

* GA4 - Event - AddPaymentInfo
    Event Name:       add_payment_info
    Params:           currency, value, payment_type (= payment_method), items
    Trigger:          CE - Add Payment Info


E) GOOGLE ADS TAGS (Enhanced Conversions)

Prerequisite: in Google Ads, go to Goals → Conversions → your Purchase
conversion action → Tag setup → "Install the tag yourself" to get:
  - Conversion ID (format: AW-1234567890)
  - Conversion Label (format: abc123XYZ)

Enable Enhanced Conversions for that conversion action in the Google Ads
UI first (Goals → Conversions → click conversion → Enhanced Conversions
tab → "Turn on enhanced conversions" → "Google tag" method). This is the
Google Ads-side setting that allows the tag we configure below to send
hashed user data.

Step 1 — Two new CONST variables:

* CONST - Google Ads Conversion ID      Value: your AW-XXXXXXXXXX
* CONST - Google Ads Purchase Label     Value: your conversion label

Step 2 — Google Ads Google Tag (fires on All Pages):

Note: modern GTM has folded standalone "Conversion Linker" into the
unified Google Tag. Adding a Google Tag with your Google Ads ID on
All Pages provides identical gclid / gbraid / wbraid capture behavior.

* Google Ads - Google Tag (Conversion Linker)
    Tag Type:        Google Tag
    Tag ID:          {{CONST - Google Ads Conversion ID}}
    Trigger:         All Pages

Auto-captures gclid / gbraid / wbraid from ad-click URLs into the
_gcl_aw first-party cookie. Required for the Purchase Conversion tag
below to attribute conversions correctly.

Step 3 — Google Ads Conversion Tracking tag (fires on CE - Purchase):

* Google Ads - Purchase Conversion
    Tag Type:                   Google Ads Conversion Tracking
    Conversion ID:              {{CONST - Google Ads Conversion ID}}
    Conversion Label:           {{CONST - Google Ads Purchase Label}}
    Conversion Value:           {{DLV - ecommerce.value}}
    Currency Code:              {{DLV - ecommerce.currency}}
    Order ID:                   {{DLV - ecommerce.transaction_id}}
    Enable Conversion Linker:   ENABLED
    Trigger:                    CE - Purchase

Step 4 — Enable Enhanced Conversions (in Google Ads UI, not GTM):

In modern Google Ads + gtag.js, Enhanced Conversions is enabled on the
Google Ads side, NOT in the GTM tag itself. Once enabled, the gtag.js
library (loaded by the Google Tag in Step 2) automatically scrapes
email/phone form fields when the awct conversion tag fires — no GTM tag
config needed.

In Google Ads:

  1. Goals → Conversions
  2. Click your Purchase conversion action
  3. "Enhanced conversions" tab
  4. Toggle "Turn on enhanced conversions"
  5. Method: "Google tag"
  6. Implementation: "Automatic collection" (recommended for ~90% of WC
     themes; gtag.js auto-detects <input type="email"> / type="tel"
     fields on the checkout/thank-you page when the conversion fires)
  7. Save

Verify in Google Ads → Goals → Conversions → your Purchase → "Enhanced
conversions" tab. Status should say "Recording enhanced conversions"
within ~24h of the first matched conversion.

(If "Automatic collection" doesn't pick up emails on your theme's
custom checkout, switch to "Manual configuration" and add CSS selectors
for the email / phone / address inputs — same Google Ads UI panel.)

The plugin captures gclid / gbraid / wbraid into 1st-party cookies
(_mcapi_gclid, _mcapi_gbraid, _mcapi_wbraid) the moment a user lands
from an ad click. The Google Tag in Step 2 transfers those into the
_gcl_aw cookie that the awct tag reads. iOS Safari ITP blocks
third-party cookies, so this 1st-party persistence keeps Google Ads
attribution alive on iOS post-2020.


PUBLISH
-------

After all tags are created, click Submit in the top right corner, then
Publish your container. Verify in GTM Preview that each event fires on the
matching action (add a product to cart, observe AddToCart fire).


CONSENT MODE v2 + CMP-AUTO-BLOCKING
-----------------------------------

For Consent Mode v2 wiring, CMP detection, and the WooCommerce Subscriptions
integration, see the Advanced Configuration tab inside the plugin settings —
those settings live in the plugin admin, not in GTM.
