Google Tag Manager Integration

What It Does

The GTM integration enables two key capabilities:

1. Promo Banner Injection — Automatically display promotional banners on pages that contain ILLIXIS-published content. Banners appear in the same positions as shown in the ILLIXIS preview.
2. E-Commerce Tracking — Track user behavior, page views, and conversions across your site to power analytics and attribution.
3. Tracking Pixel Auto-Installation — Install ad platform tracking pixels (Meta, TikTok, LinkedIn, Microsoft UET, GA4, StackAdapt, Pinterest) into your GTM container with one click. No manual GTM navigation or code copying required.

All features work through Custom HTML tags that ILLIXIS creates and manages in your GTM container. You control when changes go live via GTM's publish workflow.

Prerequisites

Before connecting GTM, ensure you have:

1. A Google Tag Manager account — Create one at tagmanager.google.com if needed.
2. A GTM container — At least one container must exist in your account.
3. Publish permissions — Your Google account needs permission to create tags, triggers, and publish versions.
4. GTM installed on your website — The GTM snippet must be present on pages where you want tracking and promos.

Required GTM Permissions

ILLIXIS requests the following GTM API scopes during OAuth:

| Permission | Purpose |
|------------|---------|
| tagmanager.edit.containers | Create and delete tags, triggers, variables |
| tagmanager.edit.containerversions | Create versions from workspace |
| tagmanager.publish | Publish versions to make changes live |

If you only have Viewer access to the GTM account, you won't be able to complete the OAuth flow. Contact your GTM admin to upgrade your permissions.

How to Connect

Step 1: Start the OAuth Flow

1. Go to Settings in ILLIXIS (click gear icon in navigation)
2. Click Integrations tab
3. Scroll to the Tracking section
4. Find Google Tag Manager
5. Click Connect

This redirects you to Google's OAuth consent screen.

Step 2: Authorize ILLIXIS

1. Sign in with the Google account that has GTM access
2. Review the permissions ILLIXIS requests
3. Click Allow

You'll be redirected back to ILLIXIS after authorization completes.

Step 3: Select Your Container

After OAuth, ILLIXIS shows all GTM containers you have access to:

1. A dropdown appears with all available containers
2. Each container shows: Container Name (GTM-XXXXX)
3. Select the container installed on your website
4. Click Select Container

ILLIXIS saves your container selection and is now connected.

Enabling Promo Banners

Once connected with a container selected, you can enable promotional banners:

How Promo Banners Work

• Banners only appear on pages with ILLIXIS-published content
• Banner positions match the preview shown in ILLIXIS
• Pages without ILLIXIS content show nothing
• The promo widget script loads asynchronously (no performance impact)

Enable the Promo Widget

1. Go to Settings → Integrations → Tracking
2. Click Manage on Google Tag Manager
3. Toggle Enable Promo Banners to ON
4. ILLIXIS creates a Custom HTML tag named "Illixis Promo Widget"
5. Click Publish to GTM to make it live immediately

Alternatively, you can review changes in GTM before publishing manually.

What Gets Created in GTM

When you enable promo banners, ILLIXIS creates:

| Component | Name | Description |
|-----------|------|-------------|
| Tag | Illixis Promo Widget | Custom HTML tag that loads the promo script |
| Trigger | All Pages - Illixis | Pageview trigger that fires on every page (or uses existing "All Pages" trigger) |
| Workspace | Illixis Workspace | Created only if no workspaces exist |

The Custom HTML tag contains a script that:

1. Sets a global config variable with your tenant ID
2. Dynamically loads the promo widget from app.illixis.io
3. The widget checks if the current page has ILLIXIS content
4. If yes, displays banners in the designated positions

Disable the Promo Widget

To stop showing promo banners:

1. Go to Settings → Integrations → Tracking
2. Click Manage on Google Tag Manager
3. Toggle Enable Promo Banners to OFF
4. Click Publish to GTM to apply immediately

The tag is removed from GTM (not just paused).

E-Commerce Tracking Setup

E-commerce tracking captures user behavior for analytics and attribution.

What Gets Tracked

• Page views with hostname detection
• User sessions and engagement
• Conversion events (when configured with GA4/Google Ads)
• Custom events from ILLIXIS content

Enable E-Commerce Tracking

1. Go to Settings → Integrations → Tracking
2. Click Manage on Google Tag Manager
3. Toggle Enable E-Commerce Tracking to ON
4. ILLIXIS creates a tag named "ILLIXIS E-commerce Tracking"
5. Click Publish to GTM

What Gets Created

| Component | Name | Description |
|-----------|------|-------------|
| Tag | ILLIXIS E-commerce Tracking | Custom HTML tag that loads the tracking script |
| Trigger | All Pages - Illixis | Shared with promo widget (or existing "All Pages" trigger) |

Tracking Pixel Auto-Installation

Install ad platform tracking pixels into your GTM container with one click. No manual GTM navigation, no code copying, no understanding what a "Custom HTML tag" is.

Supported Platforms

| Platform | What Gets Installed |
|----------|-------------------|
| Meta (Facebook/Instagram) | Meta Pixel — tracks pageviews for ad optimization and retargeting |
| TikTok | TikTok Pixel — tracks pageviews for ad optimization |
| LinkedIn | LinkedIn Insight Tag — tracks pageviews for B2B ad targeting |
| Microsoft/Bing | UET Tag — tracks pageviews for Microsoft Ads optimization |
| Google Analytics 4 | gtag.js — sends pageview data to your GA4 property |
| StackAdapt | Universal Pixel — tracks pageviews for programmatic campaigns |
| Pinterest | Pinterest Tag — tracks pageviews for Pinterest ad optimization |

How to Install Tracking Pixels

1. Go to Settings → Integrations → Tracking
2. Click Manage on Google Tag Manager
3. Scroll down to the Tracking Pixels section
4. Each connected ad platform shows as a card with its status:

• Not Connected — Connect the ad platform first in Settings → Integrations
• Ready to Install — Click Install to add the pixel to GTM
• Installed — Pixel is active in your GTM container

5. Click Install All & Publish to install all available pixels at once

What Gets Created in GTM

For each pixel installed, ILLIXIS creates:

| Component | Name Pattern | Description |
|-----------|-------------|-------------|
| Tag | ILLIXIS - {Platform} {Type} | Custom HTML tag with the platform's tracking snippet |
| Trigger | All Pages | Shared pageview trigger (fires on every page) |

Example tag names:

• ILLIXIS - Meta Pixel
• ILLIXIS - GA4 Tag
• ILLIXIS - TikTok Pixel

Removing a Tracking Pixel

1. Go to the Tracking Pixels section on the GTM management page
2. Find the platform you want to remove
3. Click Remove
4. The tag is deleted from GTM (click Publish to make the removal live)

Maya Can Help

Maya, your AI marketing assistant, can detect when you have ad platforms connected but haven't installed their tracking pixels. She'll suggest installing them and can do it for you conversationally:

Maya: "I notice you have Meta and TikTok connected but their tracking pixels aren't installed on your website. Want me to install them via GTM?" >You: "Yes, install all of them" >Maya: "Done! I've installed Meta Pixel and TikTok Pixel via GTM and published the changes."

Conversion Event Tracking

After installing base tracking pixels, add conversion events to track real business outcomes — leads, purchases, sign-ups, and more. Base pixels tell ad platforms "someone visited." Conversion events tell them "someone converted."

How It Works

1. You provide a thank-you page URL (the page people see after converting, e.g., /thank-you)
2. You select a conversion type (Lead, Purchase, Sign-up, Contact, or Add to Cart)
3. ILLIXIS creates a URL-filtered GTM trigger that only fires on that page
4. ILLIXIS creates per-platform conversion tags for every platform with a base pixel installed
5. You publish to GTM to make it live

Supported Conversion Types

| Type | Best For |
|------|----------|
| Lead / Form Submission | Contact forms, demo requests, quote requests |
| Purchase / Sale | Order confirmations, checkout completion |
| Sign-up / Registration | Account creation, newsletter signup, free trial starts |
| Contact / Inquiry | General inquiry forms |
| Add to Cart | E-commerce cart additions (for retargeting cart abandoners) |

How to Set Up Conversion Events

1. Go to Settings → Integrations → Tracking
2. Click Manage on Google Tag Manager
3. Scroll down to the Conversion Events section
4. Click Add Conversion Event
5. Select the conversion type (e.g., Lead)
6. Enter the thank-you page URL (e.g., /thank-you)
7. Choose URL match type (contains, equals, or regex)
8. Click Create Event
9. Click Install All & Publish to install conversion tags on all platforms and publish

What Gets Created in GTM

For each conversion event, ILLIXIS creates:

| Component | Name Pattern | Description |
|-----------|-------------|-------------|
| Trigger | ILLIXIS - {Event Name} ({URL}) | Pageview trigger that only fires on the matching URL |
| Tags | ILLIXIS - {Platform} {Type} Conversion ({Name}) | Per-platform conversion event tags |

Example: A "Lead" conversion on /thank-you with Meta and GA4 pixels installed creates:

• Trigger: ILLIXIS - Lead Form — /thank-you (/thank-you)
• Tags: ILLIXIS - Meta Lead Conversion (Lead Form — /thank-you), ILLIXIS - GA4 Lead Conversion (Lead Form — /thank-you)

Multiple Conversion Events

You can create multiple conversion events for different business outcomes:

• Lead form submission → /thank-you
• Purchase completion → /order-confirmation
• Newsletter signup → /subscribe-success

Each event gets its own URL trigger and set of platform tags.

Removing Conversion Events

1. To remove tags but keep the event: Click Remove Tags on the event card
2. To delete entirely: Click the trash icon on the event card (removes all GTM tags, trigger, and the event record)

Maya Can Help

Maya can set up conversion tracking conversationally:

Maya: "I notice you have Meta and GA4 pixels installed but no conversion tracking. What counts as a conversion for your business?" >You: "When someone fills out our contact form" >Maya: "Got it — a lead conversion. What page do people see after submitting the form?" >You: "/thank-you" >Maya: "I'll set up lead tracking on your thank-you page for Meta and GA4. Done! Lead conversions on /thank-you are now being tracked. You can manage these in Settings → GTM → Conversion Events."

Verifying Conversion Events

1. Use GTM Preview Mode and navigate to your conversion URL
2. Confirm the URL trigger fires (not the All Pages trigger)
3. Confirm conversion tags execute (check the tag list in Preview)
4. Complete a real conversion and verify it appears in each platform's dashboard within 24 hours

Publishing Changes

Changes you make in ILLIXIS (enabling/disabling features) are saved to your GTM workspace but are not live until published.

Publish from ILLIXIS

Click Publish to GTM to immediately publish all pending changes. This creates a new version in GTM with notes indicating it was published via ILLIXIS.

Publish Manually in GTM

Alternatively, review changes in GTM before publishing:

1. Go to tagmanager.google.com
2. Select your container
3. Review the workspace changes
4. Click Submit → Publish

Version History

Every publish creates a version in GTM. You can:

• View version history in GTM admin
• Roll back to previous versions if needed
• See which changes came from ILLIXIS (noted in version description)

Verifying Your Setup

Check Connection Status

1. Go to Settings → Integrations → Tracking
2. The GTM card shows:

• Connected badge if OAuth is active
• Container name if a container is selected
• Promo Widget status (Enabled/Disabled)

Verify Tags in GTM

1. Go to tagmanager.google.com
2. Select your container
3. Click Tags in the left menu
4. Look for "Illixis Promo Widget" and/or "ILLIXIS E-commerce Tracking"

Test on Your Website

Use GTM's Preview Mode to test without affecting live visitors:

1. In GTM, click Preview
2. Enter your website URL
3. Browse to a page with ILLIXIS content
4. Check that the Illixis tags fired in the debug panel

Check Live Behavior

After publishing:

1. Visit a page with ILLIXIS-published content
2. Open browser DevTools (F12)
3. Check Network tab for requests to app.illixis.io
4. Promo banners should appear in designated positions

Changing Containers

To switch to a different GTM container:

1. Go to Settings → Integrations → Tracking
2. Click Manage on Google Tag Manager
3. Click Change Container
4. Confirm the action (this clears current container selection)
5. Select the new container from the dropdown
6. Re-enable promo widget and tracking as needed

Note: Changing containers does not automatically remove tags from the old container. Manually delete "Illixis" tags from the old container if no longer needed.

Disconnecting GTM

To completely remove the GTM connection:

1. Go to Settings → Integrations → Tracking
2. Click Disconnect on Google Tag Manager
3. Confirm the action

This will:

• Revoke ILLIXIS access to your GTM account
• Clear stored tokens and container settings
• Leave existing tags in GTM (remove them manually if needed)

Troubleshooting

"No containers found"

Cause: Your Google account doesn't have access to any GTM containers.

Fix:

1. Go to tagmanager.google.com
2. Create a new container, or
3. Ask your GTM admin to grant you access to an existing container

"Could not get or create GTM workspace"

Cause: ILLIXIS couldn't access or create a workspace in your container.

Fix:

1. Verify you have Edit permissions (not just View)
2. Check if the container has active workspaces
3. Try disconnecting and reconnecting GTM

"Failed to create tag"

Cause: Permission issues or API errors.

Fix:

1. Verify you have Edit and Publish permissions
2. Check GTM API quotas aren't exceeded
3. Wait a few minutes and retry

"Tag already exists"

Cause: A tag named "Illixis Promo Widget" or "ILLIXIS E-commerce Tracking" already exists.

Fix: This is informational, not an error. ILLIXIS reuses existing tags instead of creating duplicates.

Promo banners not appearing

Checklist:

1. Is the promo widget enabled in ILLIXIS?
2. Did you publish changes to GTM?
3. Is GTM installed on the page?
4. Does the page contain ILLIXIS-published content?
5. Check browser console for JavaScript errors
6. Use GTM Preview Mode to verify the tag fires

Tags not firing in GTM Preview

Checklist:

1. Is the "All Pages" trigger configured?
2. Is the tag paused in GTM?
3. Are there conflicting trigger filters?
4. Check for JavaScript errors in the Custom HTML

Security & Privacy

What ILLIXIS Stores

• Refresh token — Used to access GTM API without repeated OAuth
• Container ID — Identifies which container to manage
• Container path — API path for making requests
• Tag IDs — Track which tags ILLIXIS created

ILLIXIS does not store:

• Your Google password
• Other GTM containers you have access to
• Data from your website visitors

What ILLIXIS Can Do

With the authorized permissions, ILLIXIS can:

• Create, update, and delete tags in your selected container
• Create triggers and workspaces
• Publish container versions
• List containers you have access to

ILLIXIS cannot:

• Access other Google services (Analytics, Ads, etc.) via GTM OAuth
• Modify tags not created by ILLIXIS
• Access visitor data from your website

Revoking Access

To revoke ILLIXIS access from Google's side:

1. Go to myaccount.google.com/permissions
2. Find ILLIXIS
3. Click Remove Access

Best Practices

Connect GTM Early

Connect GTM when setting up ILLIXIS so promo banners are ready when you start publishing content.

Use Dedicated Workspace

If you have complex GTM configurations, consider creating a dedicated "Illixis" workspace in GTM for reviewing changes before publishing.

Publish Promptly

After enabling or disabling features in ILLIXIS, publish to GTM so changes take effect. Unpublished changes only exist in the workspace.

Review Before Publishing

For production sites with high traffic, use GTM Preview Mode to test changes before publishing.

Clean Up Old Tags

If you disconnect ILLIXIS, remember to delete "Illixis" tags from your GTM container manually.

Related Features

• GA4 Integration — Sync traffic data and create retargeting audiences
• Cross-Channel Analytics — Unified performance reporting
• Content Publishing — Publish articles that trigger promo banners
• Advertising — Create and manage ad campaigns across 8 platforms