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


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.
